(Document-)Controller :: Adventure PHP Framework (APF)

(Document-)Controller

1. Aim of a (document-)controller

As mentioned under Standard taglibs and described on the templates page controller according to the MVC paradigma are userd 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 base_controller. 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 base_controller {

   public function my_document_controller(){
   }

   public function transformContent(){
   }

}

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 base_controller has four important helper methodes:

__getTemplate():
Method to get a reference of a HTML template object.
__getForm():
Function to get a reference of a form object defined within the current template file.
__placeholderExists():
This method checks whether a place holder tag exists in the current template file.
__templatePlaceholderExists():
Tests if a specific placeholder exists in a given template.

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

Besindes, each document controller instance contains a reference on the current DOM node the controller is responsible for transformation. The reference is stored in the $this->__Document variable. Using this reference, you can access the document's foo attribute via

PHP-Code

$this->__Document->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

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" file="website_v1_controller"
class="website_v1_controller" @>
[..]
<meta name="DC.Date" content="<html:placeholder name="Date" />" />
<meta name="DC.Type" content="Text" />
<meta name="DC.Format" content="text/html" />
<meta name="DC.Identifier" content="Dipl.-Ing. (FH) Christian W. Achatz" />
<meta name="DC.Source" content="<html:placeholder name="URI" />" />
<meta name="DC.Language" content="de" />
<meta name="DC.Relation" content="<html:placeholder name="URI" />" />
[..]
<meta name="keywords" lang="de" content="PHP,Framework,PageController,FrontController,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 base_controller {

   function website_v1_controller(){
   }

   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" file="list_v1_controller"
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 readably 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() methode 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 base_controller {

   function list_v1_controller(){
   }

   function transformContent(){

      // Set list to placehodler "List"
      $this->setPlaceHolder('List',$this->__buildList());

   }

   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 transformieren and return the code
      return $Template__ListHeader->transformTemplate();

   }

   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 transformieren 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 guestbook and contact form tutorial. 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.