(Document-)Controller

1. Aim of a (document-)controller

As mentioned under Standard taglibs and described on the templates page controller according to the MVC paradigm are used to generate dynamic content. To be able to perceive this task a document controller must be "announced" to a DOM node. This happens in the first line of a template file by using the <@controller @> tag. The page controller then assigns the document controller given there to the topical DOM node and executes it within the transformation of the current node.

2. Design of a (document-)controller

Each document controller inherits from the basic document controller BaseDocumentController. This class implements a lot of helpful methods to generate dynamic content. Example for this is the function getTemplate() that returns a reference of a HTML template contained in the node, or the method setPlaceHolder() that can be used to fill a place holder defined via the <html:placeholder /> tag.

The scaffolding of a document controller has the always following figure:

PHP-Code

class my_document_controller extends BaseDocumentController {
   public function transformContent(){
   }
}

Please use base_controller as a basis for your document controller implementations in version 1.16 and before. BaseDocumentController is available only since 1.17.

A document controller is, in principle, a PHP class "like anyone else". To the developer it is considered freely to define own class variables, to introduce own methods and to integrate other classes. It is important that only the interface shown before is implemented.

As described in the API documentation the BaseDocumentController has four important helper methods:

getDocument(): Returns a reference on the current DOM node. This enables you to access the entire tree using the methods getChildren() and getParentObject().
getTemplate($name): Returns a reference on a template object (instance of TemplateTag) defined within the current document.
getForm($name): Returns a reference on a form object (instance of HtmlFormTag) defined within the current document.
getLabel($name): Returns a reference on a label object (instance of LanguageLabelTag) defined within the current document.
getIterator(): Returns a reference on an iterator object (instance of HtmlIteratorTag) defined within the current document.
placeHolderExists($name): Checks, whether a place holder exists within the current document.
templatePlaceHolderExists(TemplateTag &$template, $name): Checks, whether a place holder exists within the applied template instance of the current document.
setPlaceHolder($key, $value): Fills a place holder with the applied value.
setPlaceHolders(array $placeHolderValues): Fills a list of place holders with the applied values.
setPlaceHolderIfExist($name, $value): Fills a place holder if it exists within the current document.
setPlaceHoldersIfExist(array $placeHolderValues): Fills a list of place holders if they are defined within the current document.

Moreover, the BaseDocumentController inherits all attributes and functions of the class APFObject.

Please note that the getIterator() method is available only since release 1.17. In versions before, it is contained in the iteratorBaseController class (see Special-taglibs).

Besides, each document controller instance contains a reference on the current DOM node the controller is responsible for transformation. The reference can be retrieved using the $this->getDocument() method. Using this reference, you can access the document's foo attribute via

PHP-Code

$this->getDocument()->getAttribute('foo')

Due to usability reasons, the document controller also knows all attributes of the current document to transform. These are stored within the internal class variable $this->attributes and can directly be accessed within the document controller.

3. (Document-)controller example

Since release 1.14 it is sufficient to specify a document controller using the namespace and class attribute. file is no more necessary.

3.1. Representation of dynamic meta tags

This chapter now describes the controller implementation of the template example shown in chapter 2.1 on the Templates page. In addition the template is to be extended by the definition of the document controller at first and looks, hence, as follows:

APF-Template

<@controller
   namespace="sites::apfdocupage::pres::templates::documentcontroller"
   class="website_v1_controller"
@>
[..]
<meta name="keywords" lang="de" content="PHP,Framework,Page-Controller,Front-Controller,Pattern,[..]" />
<meta name="date" content="<html:placeholder name="Date" />" />
<meta name="robots" content="index,follow" />
<meta name="revisit-after" content="5 days" />
[..]

In this case the accompanying document controller implements merely the method transformContent() which is called during the transformation. The source code of the class looks as follows:

PHP-Code

class website_v1_controller extends BaseDocumentController {

   public function transformContent(){

      // Set placeholder "URI"
      $this->setPlaceHolder('URI',$_SERVER['REQUEST_URI']);

      // Set placeholder "Date"
      $this->setPlaceHolder('Date',date('Y-m-d'));

   }

}

3.2. Display of dynamic lists

The following lines hak back on the example on the Templates page, chapter 2.2. The template described there aimed to generate a list. In addition the template - like above - must be extended by the definition the of document controller at first:

APF-Template

<@controller
   namespace="sites::apfdocupage::pres::templates::documentcontroller"
   class="list_v1_controller"
@>
[..]
<html:placeholder name="List" />

<html:template name="ListHeader">
  <table cellpadding="0" cellspacing="0" border="0">
    <tr>
      <td>
         <strong>ExampleList</strong>
      </td>
    </tr>
    <template:placeholder name="TableElements" />
  </table>
</html:template>

<html:template name="ListItem">
    <tr>
      <td>
         <template:placeholder name="ItemValue" />
      </td>
    </tr>
</html:template>

Now the corresponding document controller implements on the one hand the method transformContent(), however, and is extended with the private methods buildList() and buildListItem(). So the tasks are packed in own "helper methods" and the code gets more clear and better readability though. The loading of the list is delegated to a fictive business component called listLoader which returns a list (=array) of listItem objects. The latter is a data object which inherits from APFObject and exactly has one attribute with the name ListContent. To get the attribute of each object the generic get() method can be used. Then the list is walked through and the HTML code is generated:

PHP-Code

import('sites::demosite::biz','listLoader');

class list_v1_controller extends BaseDocumentController {

   public function transformContent(){

      // Set list to place holder "List"
      $this->setPlaceHolder('List',$this->buildList());

   }

   private function buildList(){

      // Create listLoader
      $listLoader = &$this->getServiceObject('sites::demosite::biz','listLoader');

      // Load list
      $List = $listLoader->loadList();

      // Initialize HTML buffer
      $Buffer = (string)'';

      // Get a reference of the "Header" template
      $Template__ListHeader = &$this->getTemplate('ListHeader');

      // Walk through the list and generate an item
      foreach($List as $lKey => $lItem){

         // Generate the HTML code of an item and add it to the buffer
         $Buffer .= $this->buildListItem($lItem);

      }

      // Set items into the "Header" template
      $Template__ListHeader->setPlaceHolder('TableElements',$Buffer);

      // Transform the template and return the code
      return $Template__ListHeader->transformTemplate();

   }

   private function buildListItem(&$listItem){

      // Get a reference if the "ListItem" template
      $Template__ListItem = &$this->getTemplate('ListItem');

      // Fill place holder of the template
      $Template__ListItem->setPlaceHolder('ItemValue',$listItem->get('ListContent'));

      // Transform the template and return the code
      return $Template__ListItem->transformTemplate();

   }

}

3.3. More examples

To get specific examples of the benefit please have a look at the and Contact form pages. More information about forms can be found on the page Forms.

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.