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.

Note: Please be aware, that within a tag definition only spaces are allowed as a seperator. 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

Taglibs are only "valid" within a specific document of the object tree. That means, that the parser methode __extractTagLibTags() only parses the taglibs known in one specific node. To be able to integrate a self-implemented taglib in the present document the following tag is used. This XML tag should be placed possibly at the beginning of the document, or at least befor it is used because of tag can only be successfully integrated after the taglib is parsed.
APF-Template
<core:addtaglib namespace="" prefix="" class="" />
Description of the attributes:
  • namespace: Namespace path seperated with "::". (Allowed characters: [A-Za-z0-9_-:])
  • prefix: XML prefix (Allowed characters: [a-z])
  • class: XML class (Allowed characters: [a-z])
Taglib classes generated by the developer must be named like "<prefix>_taglib_<class>". Thereby, <prefix> is the prefix and <class> identifies the class of the XML tag used to inside a template. The methods to be implemented within the class are to be taken from the API documentation. In common the tag is used for the integration of the form taglib or to load user specific taglibs. Own taglibs are usualy created, when a application needs to be separated into independent parts and these want to be used in different contexts or modules of the application.


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=""]/>
Description of the attributes:
  • namespace: Namespace path seperated with "::". (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.
can be used. 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="sites::testsite::pres::templates" template="[pagepart = test]" /> <core:importdesign namespace="sites::testsite::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 inteded 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.

1.3. Setattribute

The <core:setattribute /> can be used to manipulate the attributes of it's parent document within the APF DOM tree.

APF-Template
<core:setattribute name="" value="" />

In order to use the tag it must be announced using the

APF-Template
<core:addtaglib namespace="core::pagecontroller" prefix="core" class="setattribute" />

directive.

Description of the attributes:
  • name: Name of the attribute. (Allowed characters: [A-Za-z0-9_-])
  • value: Value. (Allowed characters: [A-Za-z0-9-_:.])

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');

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. The behavior is identical to the "<template:getstring />" tag described in chapter 2.2.3.
APF-Template
<html:getstring namespace="" config="" entry="" />
To use the tag it must be announced using the
APF-Template
<core:addtaglib namespace="tools::html::taglib" prefix="html" class="getstring" />
directive.

Description of the attributes:
  • 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="modules::mymodule" config="language" entry="title" />
should display a multilangual title within a template, the configuration file
Code
/config/modules/mymodule/{CONTEXT}/{ENVIRONMENT}_language.ini
must be filled with the content
APF-Konfiguration
[de] title = "Mein Modul" [en] title = "My module"
This description of this tag can also be applied to the tags <form:getstring /> (chapter 2.4.19.) and <template:getstring /> (chapter 2.3.3.).


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=""> [<template:placeholder name="" />] [<template:addtaglib namespace="" prefix="" class="" />] </html:template>
Description of the attributes:
  • name: Name of the templates of 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-_])
Access to a template grants the private 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:

Template:
APF-Template
<@controller namespace="" file="" class="" @> <html:placeholder name="Content" /> <html:template name="MyTemplate"> <template:placeholder name="MyPlaceHolder"> </html:template>
Controller:
PHP-Code
class myDocumentController extends base_controller { function transformContent(){ $Template__MyTemplate = &$this->__getTemplate('MyTemplate'); $Template__MyTemplate->setPlaceHolder('MyPlaceHolder','MyContent'); $this->setPlaceHolder('Content',$Template__MyTemplate->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() methode 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. Template enhancement:
If the standard functionality of HTML templates must be extended, the tag "<template:addtaglib />" can be used to achieve this goal. The behavour of the is similar to "<core:addtaglib />" that can be used in context of template files to add tag libs there.
APF-Template
<template:addtaglib namespace="" prefix="" class="" />
Description of the attributes:
  • namespace: Namespace path seperated with "::". (Allowed characters: [A-Za-z0-9_-:])
  • prefix: XML prefix (Allowed characters: [a-z])
  • class: XML class (Allowed characters: [a-z])
An example of the use of the XML tag is the taglib tag <[html|template]:getstring / > to read a string from a configuration file and display it. See chapter 2.2.3 or 2.4 for more details.


2.3.3. Getstring:
The tag "template:" gives the opportunity to read a configuration string from a language-dependent configuration file and so create multi-language GUIs.
APF-Template
<template:getstring namespace="" config="" entry="" />
To use the tag it must be announced using the
APF-Template
<template:addtaglib namespace="tools::html::taglib" prefix="template" class="getstring" />
directive.

Description of the attributes:
  • namespace: Namespace of the configuration file. (Allowed characters: [A-Za-z0-9_-:])
  • config: Name of the configuration file. (Allowed characters: [A-Za-z0-9-_])
  • entry: Name of the configuration key. (Allowed characters: [A-Za-z0-9-_.])

2.4. Form

The form taglibs shipped with each APF release can be read about under Forms (as of release 1.11). Releasing version 1.11, the documentation was moved there for for clarity.
In case you are still using the form taglibs from release 1.10, the documentation can be found on Form taglibs (until version 1.10). Please note the HOWTO HOWTO im Wiki if you intent to use the old form taglibs together with the new release.

3. Document

3.1. createobject

This tag enables the developer to create a website with language-dependent content view based on html files, that contain the content and functionality of the content pages. Content files are expected to reside in a folder ./frontend/content/ in parallel to the current bootstrap file (index.php). As an example this documentation page is based on this concept. Content diles must be named like
Code
c_{LANGCODE}_{NAME}.html
whereas
  • LANGCODE is a 2 letter ISO language code (de, en, it, es, ...) and
  • NAME is the URL name of the current page.
APF-Template
<doc:createobject requestparam="" defaultvalue="" />
Description of the attributes:
  • requestparam: URL parameter, that describes, which content fil has to be loaded. (Allowed characters: [A-Za-z0-9])
  • defaultvalue: Default value of the parameter defined through requestparam.
To use the tag it must be announced using the
APF-Template
<core:addtaglib namespace="tools::html::taglib" prefix="doc" class="createobject" />
directive.

If the tag could not find an appropriate file according to the requestparam, it expects a file with the name
Code
c_{LANGCODE}_404.html
to indicate, that the desired page cannot be displayed. In case the error file is not present a php error will be displayed.

4. Document controller

As already described under controller a document controller must be declared via
APF-Template
<@controller namespace="" file="" class="" @>
Description of the attributes:
  • namespace: Namespace path to the controller. (Allowed characters: [A-Za-z0-9:])
  • file: Name of the file, the controller resides in. (Allowed characters: [A-Za-z0-9_])
  • class: Class name of the controllers. (Allowed characters: [A-Za-z0-9_])
Any implementation must inherit from the abstract document controller base_controller. This class is defined in the pagecontroller.php file under apps/core/pagecontroller and must not be included separately.


5. Front controller

Since release 1.4-18.11.2007 the tag "<fcon:importdesign />" was added. It 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 "prepagecreate" mode (see FrontController, chapter 1.6). This action then can assign parameters to the model object that are contained in the URL.
APF-Template
<fcon:importdesign templatenamespace="" modelnamespace="" modelfile="" modelclass="" modelparam="" [sessionsingleton=""] />
Description of the attributes:
  • templatenamespace: Namespace path to the desired template folder. (Allowed characters: [A-Za-z0-9:])
  • modelnamespace: Namespace path to the model class. (Allowed characters: [A-Za-z0-9:])
  • modelfile: Class file of the model. (Allowed characters: [A-Za-z0-9_])
  • modelclass: Class name of the model. (Allowed characters: [A-Za-z0-9_])
  • modelparam: Model attribute that indicates the inclusion if the template file. (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)

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.