Templates

1. The use of templates

Templates in this framework are a kind of "waste product" of the DOM structure explained under Classes and serve the abstraction and separation of function and representation according to the MVC pattern. They offer the possibility to define different partial elements or views in XML and HTML code with which afterwards a controller can generate a dynamic view. There are two kinds of templates used in this frameworks. To the one hand the template files which are intended to the storage of the XML and HTML fragments which represent the contents of a DOM node, on the other hand HTML templates within these files which define a reusable area of XML and HTML code. The latter is often required for the representation of lists in which a list element is joined by any iteration template in the controller to form a list.


2. Structure of templates

Templates can contain three different types of contents:
  • XML taglibs
  • HTML code
  • Simple text
Taglib tags are XML tags familiar to the tag parser. They are composed of two main elements: <prefix:class /> whereas "prefix" and "class" can be represented by every legal XML compilant prefix and class sign. The signs [a-z] are permitted here. Every tag can own any number of attributes and any contents in not self-closing tags. These have the form attribute="value". HTML code and an easy text are usable as attributes of taglib tags as well as the content of the tag.


3. Typical templates

In the following some typical templates are performed and explained:


3.1. Template for the representation of dynamic contents

One example for the representation of dynamic contents is the filling of HTML meta tags. Therefore several <html:placeholder /> tags can be placed in the template. The dynamic meta tags on this documentation site have the following figure:

APF template
[..] <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 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,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" /> [..]
Here two different place holders are available to be filled in a controller with different content. During transformation of the DOM node the XML tags are replaced with the contents set in the controller.


3.2. HTML templates

HTML-Templates serve - as already appealed - for the definition of reusable HTML fragments for the representation of lists or tables. Here - in common - one HTML element is represented by one template which can be used by the controller to construct a views or a view element. HTML templates are not displayed directly on the place of their definition, but are structural elements to the generation of elements and can be used by the controller of the current node. In the following a template file should be presented to generate single column table:
APF template
[..] <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>
The template file defines thre different elements:
  • HTML place holder:
    This serves the representation of the complete list. It is filled in the controller with the HTML code of the generated list.
  • HTML template "ListHeader":
    This HTML template defines the head of the table. It contains one place holder for the elements of the table.
  • HTML template "ListItem":
    This HTML template represents on list element. It includes on place holder to display the content of the list element.
The document controller of the current DOM node has to implement the following functionality:

                    START
                      |
                      v
      +--------------------------------+
      |      Load list entries         |
      +--------------------------------+
                      |
                      v
      +--------------------------------+
      |     Initialize list buffer     |
      +--------------------------------+
                      |
                      v
      +--------------------------------+
      |       Run through list         |
      +--------------------------------+
                      |
                      v
      +--------------------------------+
      |     Insert list value in       |
      |      template "ListItem"       |
      +--------------------------------+
                      |
                      v
      +--------------------------------+
      |  Transform "ListItem" and add  |
      |         to list buffer         |
      +--------------------------------+
                      |
                      v
      +--------------------------------+
      |     Insert list buffers in     |
      |      template "ListHeader"     |
      +--------------------------------+
                      |
                      v
      +--------------------------------+
      |   Transform of the template    |
      |  "ListHeader" and insert the   |
      |  content into the place holder |
      |             "List"             |
      +--------------------------------+
                      |
                      v
                     END

Note: Templates that are not used to generate lists or self-repeating structures can be displayed directly where they are declared. Therefore, the method transformOnPlace() must be applied to the desired template. In order to display the HTML template
APF template
... <html:template name="my_template"> ... </html:template> ...
right where it was defined within the template file, the following code must be present in the corresponding document controller
PHP code
class SampleController extends BaseDocumentController { public function transformContent(){ $template = &$this->getTemplate('my_template'); $template->transformOnPlace(); } }

3.3. Dynamic inclusion of views

To be able to dynamically include views in a specific template the <core:importdesign /> tag was introduced. This gains the ability to define a view (e.g. a login form) which behaviour can be influenced by URL parameters:
APF template
<core:importdesign namespace="[..]" template="[pagepart = start]" />
If the param "pagepart" is not set in the URL the template file "start" is loaded into that view. Whether the param is set, the content of the defined template is loaded into the view. This makes it possible to generate a series of views (e.g. a multi-page form) or include different modules via URL parameter. Because it can come to interference while integrating several modules with the "pagepart" parameter, the URL parameter to use to inlclude the template can be manipulated ba the the attribute incparam. Inclusion then is as follows:
APF template
<core:importdesign namespace="[..]" incparam="myurlparam" template="[myurlparam = start]" />
A concrete example of the dynamic view integration is the control of the indicated perspective of the present site. As desired by the user one of the avaliable views is displayed (normal web page view or print view). To produce this behaviour the <core:importdesign /> must be configured in the website.html as follows:
APF template
<core:importdesign namespace="sites::apfdocupage::pres::templates" template="[perspective=site]" incparam="perspective" />
With this configuration it is easy to supply a printing function. Please refer to the printer symbol placed on top of the site to get a feeling of the function of this definition.


3.4. More tags

Standard taglibs describes all tags shipped with each release. To get specific examples of the benefit please have a look at the guest book and contact form tutorial.


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.