Page controller

1. Introduction

The page controller is the heart of the adventure php framework. This component consists of different base classes, that are described in the classes chapter. The functionality of the page controller is to provide a reusable environment for applications, that are implemented following the MVC pattern. It features a unique mechnaism to load and handle templates with aid of the functionality contained in tags, to execute controllers and to manage the MVC tree, that was build by the taglib's functionality.

Because of the DOM tree structure, the page controller is a HMVC controller. This pattern describes, that a hierarchical DOM tree consists of any count of MVC cells, that are managed by a generic component (here: the APF page controller). Applying the HMVC pattern, you assume, that a model is not bound to one MVC cell strictly, but is available for more than one DOM nodes. This makes it possible to easily and flexibly develop modules and applications.

2. Functionality

Due to the fact, that the page controller does only provide a framework, or is responsible to operate it's workflow respectively, the application logic can directly be influenced by tags and controllers. This means, that the page controller is application logic independent. For this reason it is possible to create tags with different functions (e.g. forms, include further templates, place holders, ...). The workflow diagram describes the actions, that are passed through, and the points, the developer can influence to apply the requirements of his application to. Click on the image to enlarge it!

2.1. Activity diagram

Page controller timing model (APF)

2.2. Description

The following list describes the workflow again in textual form:

  • At the beginning of a request the bootstrap file (typically: index.php) is called.
  • With this file the page controller's Page object is instanciated. Inside the constructor, the input filter configures in the Registry is executed. The filter preprocesses the user input (keyword: URL rewriting) and checks the parameters for potential security problems.
  • As of the loadDesign(), the initial template is loaded and parsed.
  • During the parse operation, the page controller looks up, if the template contains document controller declarations and further tags as described on Standard taglibs.
  • If a document controller tag is included, this information is extracted from the content and prepared for the transformation.
  • If known tags as described on Standard taglibs are included, they are analyzed and linked as child objects into the current DOM node.
  • During the parse operation of the current tag, the corresponding tag lib class (PHP class) is created and the attributes and the content is applied to that instance. After that, the onParseTime() method is called (see Implementation of tags). The implementation of this function affects the proceeding of the content of the tag, that can possibly contain further tags. Thus, the content is typically processed for known tags and so on...
  • After parsing a node, it is linked to the DOM tree as a child of the current node. Then, the onAfterAppend() method is called on each of the children. As of this moment, the single nodes "know" their neighbours through the $this->parentObject and $this->children references. Hence, the onAfterAppend() contains tag functionality, that needs to know it's related DOM nodes.
  • If the loadDesign() method has finished, a complete APF DOM tree is available, that consists of a number of nodes, that are directly influenced by the template and tag definition the developer created.
  • On the $page->transform() call, the DOM tree is traversed recursively and each element is transformed. Thereby, each node is responsible for it's transformation itself. Because most of the nodes typically extend the Document class, tha workflow is as follows: at first, the method checks, if a document controller was defined. If yes, the class is created and applied with the references, attributes and contents necessary for transformation. After that the transformContent() is called.
  • After the document controller execution the list of child nodes of the current DOM node is walked through and transformed by calling the transform() method on each of the children. Each node is responsible for it's transformation itself. The only thing, that is important is, that the function call must return the transformed content of the node, because the calling node has to continue processing it.
  • After all nodes are transformed, the HTML code of the page exists. This content is then applied to the output filter - if desired - and then sent to the client.
Starting with release 1.14 the execution of input and output filters has been refactored. Within this task execution filters is not a part of the page controller's tasks any more since the page controller component is subjected to HMVC management only. Now, filters are executed by the Front controller only.

3. Further resources

Further information can be found in the German language forum thread Ein Einfaches Formular erstellen. (German).

Further reading on the timing model can be found in the Wiki (German).

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.