Standard taglibs

This chapter describes the taglib tags available out-of-the-box. Within not self-closing tags all HTML tags and formatting are permitted. All tags can be equipped with the usual HTML attributes, provided that these are relevant for the issue or function.

Please be aware, that within a tag definition only spaces are allowed as a separator. Tabs or new line characters are not parsed and using them can lead to unrecognized error on tag definition analysis!

1. Core

1.1. Addtaglib

The Page controller of the APF is designed with the HMVC pattern and manages all elements and components of your software using documents. Each document - a.k.a. node - may contain further nodes. A node is represented by the Document class and it's children.

The APF parser is designed to process all tags that either match

APF template
<prefix:name />


APF template

including all tag attributes defined along with the tag. Creating the DOM tree the parser used the Document::$knownTags (static) and Document::$knownInstanceTags (per instance) lists to evaluate the implementation of the respective tag. In case you intend to a custom tag that has not been registered with the APF you may want to use the <core:addtaglib /> tag. This tag registers the desired custom tag with the APF parser either globally for all templates or just the local DOM node. Tags registered within templates can directly be used after registration.

The signature of the tag is as follows:

APF template
<core:addtaglib class="" prefix="" name="" [scope=""] />
Description of the attributes:
  • class: The fully-qualified class name of the tag implementation. (Allowed characters: [A-Za-z0-9_\])
  • prefix: The XML prefix. (Allowed characters: [a-z])
  • name: The XML tag name. (Allowed characters: [a-z])
  • scope: Defines the tag registration type. global means project scope and local registers the tag for the current DOM node only. Default: global. (Allowed values: global|local)

The methods that have to be implemented within a tag class can be found in the API documentation or the Implementation of tags tutorial. The naming if the tag class can be freely defined by the developer using the class attribute. At the same time, it is possible to register one tag implementation with different prefixes.

Creating custom tags is recommended in case functionality should be used throughout multiple projects or in case the desired functionality cannot be implemented using a (Document-)Controller.

Registration of tags using <core:addtaglib /> is the same as adding them within your bootstrap file. In order to keep your template code clean it is recommended to add custom project tags within the index.php via
PHP code
Document::addTagLib('VENDOR\..\DateDisplayTag', 'date', 'display');
Details can be taken from chapter Implementation of tags.

1.2. Importdesign

To include another template into a certain place in the space of a present template the tag

APF template
<core:importdesign namespace="" template="" [incparam=""] [context=""] />

can be used.

Description of the attributes:
  • namespace: Namespace path separated by "\". (Allowed characters: [A-Za-z0-9_-:])
  • template: Name of the desired template. (Allowed characters: [A-Za-z0-9-_])
  • incparam: URL parameter that is used for template inclusion.
  • context: Redefines the context starting with the current DOM node.

If a so-called pagepart template is defined with the definition of this tag, a template can be integrated depending by the specified URL parameter. Standard parameter is pagepart, nevertheless, this can be adapted with the optional attribute incparam. Example of the integration with the pagepart parameter is:

APF template
<core:importdesign namespace="VENDOR\pres\templates" template="[pagepart = test]" /> <core:importdesign namespace="VENDOR\pres\templates" template="[cmsmodule = test]" incparam="cmsmodule" />

The integrated template automatically inherits the qualities of the father's object. In particular context and language will be adopted.

The context should be used, if you are intended to use a module twice within one application/website with different configuration. Doing so, the module should be included using the importdesign taglib or a derived class to provide the correct context to the module. Please note, that all taglibs below this DOM node are initialized with the manually configured context and thus can access context and environment dependent configuration.

2. Html

2.1. Placeholder

To be able to fill contents in a document controller dynamically the tag <html:placeholder /> was introduced.

APF template
<html:placeholder name="" />
Description of the attributes:
  • name: Name of the place holder. The name is used to access this place holder within a document controller. (Allowed characters: [A-Za-z0-9-_])

To fill a place holder with contents you can insert the following instruction in a document controller:

PHP code
$this->setPlaceHolder('NameOfThePlaceHolder', 'ContentOfThePlaceHolder');

In addition, any number of string replacements can be registered with a place holder. This enables you to inject dynamic content into the place holder using a tag implementation or a document controller.

2.2. Getstring

The tag <html:getstring /> gives the opportunity to read a configuration string from a language-dependent configuration file and so create multi-language GUIs.

APF template
<html:getstring [name=""] namespace="" config="" entry="" />
Description of the attributes:
  • name: Name of the place holder as identifier for the getLabel() method (Allowed characters: [A-Za-z0-9_-])
  • namespace: Namespace of the configuration file. (Allowed characters: [A-Za-z0-9_-\])
  • config: Name of the configuration. (Allowed characters: [A-Za-z0-9-_])
  • entry: Name of the configuration key. (Allowed characters: [A-Za-z0-9-_.])

The language dependent configuration file must contain one section per language (two-letter ISO country code) and the configuration keys used in the tag within each of the language sections. If the tag

APF template
<html:getstring namespace="VENDOR\modules\guestbook" config="language.ini" entry="title" />

should display a multi-language title within a template, the configuration file


must be filled with the content

APF configuration
[de] title = "Mein Modul" [en] title = "My module"

Moreover, language-dependent texts can be added place holders that can be filled dynamically within a (Document-)Controller at runtime. The place holder is defined by it's name enclosed by brackets:


This place holder can be referred to by it's key user-name later on. Please note the subsequent language text file that defines three keys including one or more place holders:

APF configuration
[en] headline = "This is a {word}" intro.text = "This is a text with {count} place holder." message = "This is a message from {user-name} sent at {date}." ...

The values defined above can be used within your template files as follows:

APF template
<h3><html:getstring name="headline" namespace="..." config="..." entry="headline"/></h3> <html:form name="Form"> <p> <html:getstring name="intro-text" namespace="..." config="..." entry="intro.text"/> </p> ... </html:form> <html:template name="Message"> ... <p> <html:getstring name="message" namespace="..." config="..." entry="message"/> </p> </html:template>

To fill the place holders you are provided several possibilities as you can take from the below document controller. They all use the getLabel() method to obtain an instance of the appropriate label tag. The instance itself provides the setPlaceHolder() function that takes the name and the value as it's arguments. You may use the method in fluid interface style to add more than one place holder:

PHP code
use APF\core\pagecontroller\BaseDocumentController; class SampleController extends BaseDocumentController { public function transformContent() { // Fill place holder within a < html:getstring /> directly within the template: $this->getLabel('headline')->setPlaceHolder('word', 'Headline'); // Fill place holder within a < html:getstring /> within a form: $form = $this->getForm('Form'); $form->getLabel('intro-text')->setPlaceHolder('count', 'one'); // Fill place holder within a < html:getstring /> within a template tag: $tmpl = $this->getTemplate('Message'); $tmpl->getLabel('message') ->setPlaceHolder('user-name', 'John') ->setPlaceHolder('date', date('d.m.Y H:i:s')); } }
The number of place holders per language key is not restricted. Place holders that are not filled are displayed literally within the output.

2.3. Template

2.3.1. Basic functions

To be able to define further reusable elements the so-called templates are introduces. These can be manipulated and be processed within a document controllers. Each template again has place holders than can be filled dynamically.

APF template
<html:template name=""> [<html:placeholder name="" />] [<core:addtaglib class="" prefix="" name="" />] [<html:getstring namespace="" config="" entry="" />] </html:template>
Description of the attributes:
  • name: Name of the templates or name of the place holder within a templates. The name is used to access this object within a document controller. (Allowed characters: [A-Za-z0-9-_])
In case you want to add further tags within <html:template /> you can add them using the <core:addtaglib /> tag eprior usage.

Access to a template grants the protected method getTemplate() of a document controller. With the help of this function a reference on a template object can be gathered. A typical application case looks like this:

APF template
<@controller class="" @> <html:placeholder name="Content" /> <html:template name="MyTemplate"> <html:placeholder name="MyPlaceHolder"> </html:template>
PHP code
use APF\core\pagecontroller\BaseDocumentController; class SampleController extends BaseDocumentController { public function transformContent(){ $tmpl = $this->getTemplate('MyTemplate'); $tmpl->setPlaceHolder('MyPlaceHolder','MyContent'); $this->setPlaceHolder('Content',$tmpl->transformTemplate()); } }

Here a document controller, a HTML place holder and a template with accompanying place holder is defined in the template file. Now in the controller you can get a reference on the template by using the getTemplate() method and fill it with setPlaceHolder(). Afterwards the template is transformed and the output is used to fill the HTML place holder by means of setPlaceHolder(). It is possible to define several templates inside a template file. Often this is used for the issue of displaying different announcements with different events.

2.3.2. Clear template content

In case you are using a template to display repetitive content you should keep in mind that the instance of the template tag (TemplateTag) is always the same instance within loops. Filling only parts of the place holders within one loop the place holders filled within previous loops will not be cleared. In order to avoid weired situations you may want to use the clear() method at the end of a loop:

PHP code
use APF\core\pagecontroller\BaseDocumentController; class SampleController extends BaseDocumentController { public function transformContent() { $template = $this->getTemplate('table-line'); $elements = ...; foreach($elements as $element) { $template->setPlaceHolder('foo', $element->getFoo()); $bar = $element->getBar(); if(!empty($bar)) { $template->setPlaceHolder('bar', $bar); } $buffer .= $template->transformTemplate(); $template->clear(); } $this->setPlaceHolder('content', $buffer); } }

Calling clear() means that all place holder tags (instances of PlaceHolderTag) will be reset - meaning the content is removed.

If your templates contain custom place holder tags or you have defined further elements that need to be reset after each loop run you can apply a custom implementation of the TemplateTagClearApproach interface to the clear() call. The following code box contains the standard implementation of the APF that resets all place holder tags as well as the string place holders defined within the <*:getstring /> tag instances:

PHP code
use APF\core\pagecontroller\TemplateTagClearApproach; class DefaultTemplateTagClearApproach implements TemplateTagClearApproach { public function clear(TemplateTag &$node) { $node->clearPlaceHolders(); // clear language label place holders foreach ($node->getChildren() as &$child) { if ($child instanceof LanguageLabelTag) { $child->clearPlaceHolders(); } } } }

In case you want to apply a custom deletion approach the controller code changes as follows:

PHP code
use APF\core\pagecontroller\BaseDocumentController; use APF\core\pagecontroller\DefaultTemplateTagClearApproach; class SampleController extends BaseDocumentController { public function transformContent() { $template = $this->getTemplate('table-line'); $elements = ...; $clearApproach = new DefaultTemplateTagClearApproach(); foreach($elements as $element) { $template->setPlaceHolder('foo', $element->getFoo()); $bar = $element->getBar(); if(!empty($bar)) { $template->setPlaceHolder('bar', $bar); } $buffer .= $template->transformTemplate(); $template->clear($clearApproach); } $this->setPlaceHolder('content', $buffer); } }

3. Document controller

As already described under (Document-)Controller a document controller must be declared via

APF template
<@controller class="" @>
Description of the attributes:
  • class: Fully-qualified class name of the controller. (Allowed characters: [A-Za-z0-9_\])

Details can be found under (Document-)Controller.

4. Front controller

The <fcon:importdesign /> tag aids the implementation of front controller based applications and makes it possible to include views by the use of application model information according to the MVC pattern. Therefore a separate model class that provides the information must be created for the entire application or a single module. The control of the view integration is regulated typically by an own front controller actions that is executed in TYPE_PRE_PAGE_CREATE mode (see Front controller). This action then can assign parameters to the model object that are contained in the URL.

APF template
<fcon:importdesign template-namespace="" template-param="" model="" [sessionsingleton=""] />
Description of the attributes:
  • template-namespace: Namespace path to the desired template folder. (Allowed characters: [A-Za-z0-9\])
  • template-param: Model attribute that indicates the inclusion if the template file. (Allowed characters: [A-Za-z0-9_])
  • model: Fully-qualified class name of the model. (Allowed characters: [A-Za-z0-9_])
  • sessionsingleton: Defines, if the model object is created in SINGLETON or SESSIONSINGLETON mode. If the attribute is not present or contains any other value than true, the SINGLETON mode will be used. (Allowed values: true|false)

To use the tag it must be announced using

APF template
<core:addtaglib class="APF\tools\html\taglib\FrontControllerImportTemplateTag" prefix="fcon" name="importdesign" />
Please ensure your model implements the FrontControllerImportTemplateModel interface. The tag uses methods getTemplateNamespace() and getTemplateName() to evaluate the template to load.


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.

In order to provide a state-of-the-art web experience and to continuously improve our services we are using cookies. By using this web page you agree to the use of cookies. For more information, please refer to our Privacy policy.