Templates

1. Definition of templates

The Adventure PHP Framework (APF) uses several meanings of template:

  • Templates are the basis of the HMVC pattern implementation of the Page controller. This component creates a DOM structure using template files (HTML files) or tags and enables the developer to dynamically create the surface of a website or an application according to the requirements.
  • Besides, templates are often referred to as re-usable elements within template files. A common representative is the <html:template /> tag that can be used to realize conditional output or to display repetitive content within template files.

The definition of the MVC pattern describes the meaning of model, view, and controller. The HMVC pattern defines a hierarchical structure of MVC DOM elements that is created based on template content. The Page controller uses the information that are contained within the template files and created child nodes within the current node.

Each template, or each node of the HMVC DOM tree respectively, may define a (Document-)Controller according to the definition of the MVC pattern.

2. Content of templates

Template files typically contain three types of content:

  • APF tags (e.g. <html:placeholder />)
  • HTML code (e.g. <p>...</p>)
  • Any text

Tags are XML tags that are known to the APF parser such as <prefix:name />. They can define any number of attributes - e.g. attribute="value". Explicitly closing tags may contain further tags or simple textual content.

HTML code and any kind of text can be used to fill the content of your web site or application and are not treated by the APF parser. Thus, you can use both as content of attributes and tags.

Please be aware that HTML code within tag attributes can only be processed in case there are no quotes (").

Within APF tags any kind of HTML code can be placed as long as the code does not interfere with the nested tag structure.

Details on the APF parser can be read about under Implementation of tags.

2.1. Template files

Template files are used within the Adventure PHP Framework to create the UI of a web site or application and the Front controller is always started with an initial template.

Within template files APF tags (see Standard taglibs), HTML code or any kind of text can be placed. In most cases the template - e.g. the initial template - contains the basic frame of a web site or an application and defines place holders for dynamic content or includes further templates. Displaying dynamic content, each template may define a (Document-)Controller that is executed on transformation.

The following code box contains the basic frame of a web site:

APF template
<@controller class="VENDOR\pres\controller\MainController" @> <!DOCTYPE html> <html> <head> <title><html:placeholder name="title" /></title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> </head> <body> <header> <h1><html:placeholder name="title" /></h1> <core:importdesign namespace="VENDOR\pres\templates" template="navi" /> </header> <div id="content"> <core:importdesign namespace="VENDOR\pres\templates" template="content" /> </div> <footer> <core:importdesign namespace="VENDOR\pres\templates" template="footer" /> </footer> </body> </html>

The above template defines two place holder tags that are filled by the MainController and includes further templates using three <core:importdesign /> tag that take care of navigation, content, and footer.

A list of known tags can be found under Standard taglibs or Special-tags respectively. The Implementation of tags tutorial describes how to create custom tags and functions for your web site or application.

Besides the standard template functions Extended template functionality describes additional functionality as shorter place holders as well as a syntax to access objects from within a template.

2.2. HTML templates

HTML templates are used to define reusable HTML fragments to display conditional content or to create lists. It is recommended to create one template per element that can be used by the controller. HTML templates are not automatically displayed where they are defined but are structural elements that are used to generate content.

The following code box shows an HTML template that is used to create a dynamic table:

APF template
<@controller class="VENDOR\pres\controller\ListController" @> <table> <thead> <tr> <td>Frage</td> <td>Antwort</td> </tr> </thead> <tbody> <html:placeholder name="table-rows" /> </tbody> </table> <html:template name="table-row"> <tr> <td><html:placeholder name="question" /></td> <td><html:placeholder name="answer" /></td> </tr> </html:template>

The template itself contains the frame of the table and the <html:template /> tag defines one line of the table. Generating the content the following controller can be used:

PHP code
use APF\core\pagecontroller\BaseDocumentController; class ListController extends BaseDocumentController { public function transformContent() { $row = $this->getTemplate('table-row'); $buffer = ''; foreach ($this->getItems() as $item) { $row->setPlaceHolder('question', $item->getQuestion()); $row->setPlaceHolder('answer', $item->getAnswer()); $buffer .= $row->transformTemplate(); } $this->setPlaceHolder('table-rows', $buffer) } /** * @return FaqEntry[] */ private function getItems() { ... } }
Templates that are not used for list generation or for repetitive content can be displayed directly where they are defines. For that reason, please use transformOnPlace() within your document controller. Example:
PHP code
class MainController extends BaseDocumentController { public function transformContent(){ $tmpl = &$this->getTemplate('template-name'); $tmpl->transformOnPlace(); } }

In order to simplify display of lists you may want to directly fill place holders. Fur this reason, you can combine two features: the third parameter of the setPlaceHolder() method allows to append content to a place holder and the TemplateTag supports direct output generation implementing the __toString()-Method which internally transforms the template.

The controller implementation can be rewritten as follows:

PHP code
use APF\core\pagecontroller\BaseDocumentController; class ListController extends BaseDocumentController { public function transformContent() { $row = $this->getTemplate('table-row'); foreach ($this->getItems() as $item) { $row->setPlaceHolder('question', $item->getQuestion()); $row->setPlaceHolder('answer', $item->getAnswer()); $this->setPlaceHolder('table-rows', $row, true); } } /** * @return FaqEntry[] */ private function getItems() { ... } }

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.