Special-taglibs

This documentation page describes advanced functions of the framework, that are designed for special application cases of more complex software designs.

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. Iterator

The iterator tag was introduced in version 1.6 (final) to simplify the display mechanism of objects or associative arrays. For this reason an iterator tag defined within a template file must be filled by the document controller with the desired data. The definition of the tag looks as follows:

APF template
<html:iterator name=""> ... [<iterator:addtaglib namespace="" class="" prefix="" name="" />] [<iterator:getstring namespace="" config="" entry="" />] [<iterator:placeholder name="" />] ... <iterator:item [getter=""]> <item:placeholder [name=""][getter=""] /> [<item:getstring namespace="" config="" entry="" />] [<item:addtaglib namespace="" class="" prefix="" name="" />] </iterator:item> ... </html:iterator>

The <html:iterator /> tag defines the iterator and the <iterator:item /> tag contains the graphical description of how a data element should be displayed. Inside the data element a various number of placeholders and HTML tags (<item:placeholder />) can be defined. The name of the placeholder is equal to the name of the class attribute or array offset at the same time. In order to change the name of the get method, the optional tag attribute getter must be added to the <iterator:item /> tag definition. Please note, that the tag implementation uses the get() function as the default getter.

Description of the attributes:
  • name (1): Name of the iterators. (Allowed characters: [A-Za-z0-9])
  • getter: Name of the method that is used to retrieve an object's attribute. (Allowed characters: [A-Za-z0-9_])
  • name (2): Name of the place holder. (Allowed characters: [A-Za-z0-9])
Retrieving an object's attribute can be done in two ways since release 1.14:
  • Using the <iterator:item/> tag you can define a generic method for all place holders. Doing so, you can specify the name of the attribute within the <item:placeholder/> tag using the name attribute. The value of this attribute then refers the object's property to display. Example:
    APF template
    <html:iterator name="..."> <iterator:item getter="getProperty"> <item:placeholder name="DisplayName" /> </iterator:item> </html:iterator>
    Within this mode the tag expects the current object to implement a method like
    PHP code
    public function getProperty($name)
    that returns the value of the property (here DisplayName). This is the default behaviour for release before 1.14.
  • In case no generic method is available for retrieving the desired object attributes, you are now able to define a getter method using the <item:placeholder/> tag for each place holder. Example:
    APF template
    <html:iterator name="..."> <iterator:item> <item:placeholder getter="getDisplayName" /> </iterator:item> </html:iterator>
    Within this mode the tag expects the current object to implement a method like
    PHP code
    public function getDisplayName()
    that returns the value of the property. This possibility has been introduced in release 1.14.
You can also mix the possibilities described above. In case a generic method as well as a dedicated method is specified, the local one will win the race.

To use the tag it must be announced using the

APF template
<core:addtaglib namespace="tools::html::taglib" class="HtmlIteratorTag" prefix="html" name="iterator" />

directive.

Before release 1.17 the document controller responsible for the current Document must inherit from the iteratorBaseController class located in the tools::html::taglib::documentcontroller namespace. Since release 1.17 the getIterator() method is directly contained in BaseDocumentController.

The following code fragment shows, how to use the iterator tag:

PHP code
class ListController extends BaseDocumentController { public function transformContent(){ ... // Get a reference om the iterator tag $Iterator = &$this->getIterator('...'); // Fill the data container with a list of objects or associative arrays $Iterator->fillDataContainer(...); // Display on the place of definition ... $Iterator->transformOnPlace(); // ... or insert the content of the tag into a place holder $this->setPlaceHolder('...',$Iterator->transformIterator()); ... } }
In order to display language dependent value within the iterator (e.g. for language dependent table headers), the <iterator:getstring /> and <item:getstring /> tags can be used. The functionality is equal to the <html:getstring /> tag. If you are not comfortable with this tag, feel free to add your custom taglibs using the <iterator:addtaglib /> and <item:addtaglib /> tags. The functionality is equal to the <core:addtaglib /> tag.

In case the entries of a list or table should be added ascending numbers you may add a <item:placeholder /> tag within an <iterator:item /> that takes the name IterationNumber. Sample:

APF template
<html:iterator name=""> <iterator:item [getter=""]> <item:placeholder name="IterationNumber"> </iterator:item> </html:iterator>

In case the iterator tag is used in conjunction with the Pager the numbers on the second page should not start with 1 again. For this reason, the <html:iterator /> needs to know about the pager you are using providing the pager attribute pointing to the appropriate pager configuration.

Within the below example the iterator tag uses the values within the PagerExample section inside the /apps/config/modules/pager/{ENVIRONMENT}_pager.ini configuration file.

APF template
<html:iterator name="" pager="PagerExample"> <iterator:item [getter=""]> <item:placeholder name="IterationNumber"> </iterator:item> </html:iterator>

2. Media stream tags

The media stream tags enable the developer to store and deliver GUI ressources directly from the namespace of a specific module. For this reason, the framework contains an abstract implementation of a streaming taglib and several dedicated taglibs, that generate a media url. Further, a generic front controller action is included, that streams the media files, that are requested by the tags.

In order to use the tags you must be sure, that the front controller action, that is intended to deliver the desired files, has a valid configuration for the current context. The action config is expected to be contained in the

Code
/config/tools/media/actions/{CONTEXT}/{ENVIRONMENT}_actionconfig.ini

file. The content of the file can be taken from the following code box:

APF configuration
[streamMedia] FC.ActionNamespace = "tools::media::actions" FC.ActionClass = "StreamMediaAction" FC.InputClass = "StreamMediaInput" FC.InputParams = ""

A example configuration file is also included in the apf-configpack-* release file under tools/media/actions/.

In order to generate dynamic media urls, the following taglibs are included in the framework:

  • FormMediaInclusionTag: To be used within the html:form tag
  • MediaInclusionTag: To be used within a template file
  • MediaInclusionTag: To be used within the html:template tag

To be able to use one of the taglibs, the tag must be introduced to the desired scope using the <*:importdesign /> tags. The following code box shows an real life application example:

APF template
<core:addtaglib namespace="tools::form::taglib" class="HtmlFormTag" prefix="html" name="form" /> <html:form name="TestFormular"> <form:addtaglib namespace="tools::media::taglib" class="FormMediaInclusionTag" prefix="form" name="mediastream" /> <img src="<form:mediastream namespace="modules::mymodule::pres::images" filename="phone_icon.png" />" alt="" /> <form:text name="phonenumber" /> <br /> <form:button name="send" value="Absenden" /> </html:form>

As you can take from the example above, the <*:mediastream /> tags expect the following attributes to be filled:

  • namespace: Namespace to the desired media file. (Allowed characters: [A-Za-z0-9:])
  • filename: Name of the media file. (Allowed characters: [A-Za-z0-9_.-])
If you intend to manipulate the namespace of the file, that should be delivered, because you want to store the image files in the config namespace - using the context to give the application an individual touch - you have to act like this:
  1. Add an id attribute to the desired tag:
    APF template
    <core:addtaglib namespace="tools::media::taglib" class="MediaInclusionTag" prefix="html" name="mediastream" /> <img src="<html:mediastream namespace="config::modules::mymodule::pres::images" filename="phone_icon.png" id="PhoneIcon" />" alt="" />
  2. Manipulate the namespaces within the responsible document controller:
    PHP code
    class ExampleController extends BaseDocumentController { public function transformContent(){ $mediaStreamTag = &$this->getMediaStreamTagByID('PhoneIcon'); $mediaStreamTag->setAttribute($mediaStreamTag->getAttribute('namespace').'::'.$this->getContext()); } private function &getMediaStreamTagByID($id){ $children = &$this->getDocument()->getChildren(); foreach($children as $objectId => $DUMMY){ if(get_class($children[$objectId]) == 'MediaInclusionTag'){ return $children[$objectId]; } } throw new InvalidArgumentException('No media stream tag contained within the current document!'); } }
  3. Manipulation of the file name within a template:
    PHP code
    class ExampleController extends BaseDocumentController { public function transformContent() { $FileTemplate = &$this->getTemplate('file'); $mediaStreamTag = &$this->getMediaStreamTagByID('FileIconID', $FileTemplate); $mediaStreamTag->setAttribute('extension', 'png'); $mediaStreamTag->setAttribute('filebody', 'dateinameOhneEndung'); } private function &getMediaStreamTagByID($id, TemplateTag &$template) { $children = &$template->getChildren(); foreach ($children as $objectId => $DUMMY) { if (get_class($children[$objectId]) == 'MediaInclusionTag' && $children[$objectId]->getAttribute('id') == $id ) { return $children[$objectId]; } } throw new InvalidArgumentException('No media stream tag contained within the current template "' . $template->getAttribute('name') . '"!'); } }

Since release 1.14 the front controller action that is used to deliver the media resources (StreamMediaAction) includes the possibility to explicitly configure allowed file extensions along with their MIME types. Thus, you can add or remove extensions. Within the default setup, the following types are allowed:

  • png or image/png respectively
  • jpeg or image/jpg respectively
  • jpg or image/jpg respectively
  • gif or image/gif respectively
  • css or text/css respectively
  • js or text/javascript respectively

In order to re-define the existing values the configuration file {ENVIRONMENT}_allowed_extensions.ini must be present under tools::media::{CONTEXT}. Within there, you can specify the allowed file extensions as follows:

APF configuration
[Default] jpg = "image/jpg" xml = "text/xml" psd = "application/psd"

3. Generic importdesign tag

Within more complex applications it is often necessary to fill the views - defined with the <*:importdesign /> tags - dynamically. In many cases, the developer thus wants to use model information of the application. To be able, to use the business layer as a real control layer, the framework features a generic importdesign tag, that allows you to retrieve the name of the template to include as well as the template's namespace from the desired application model dynamically.

The tag's signature looks like this:
APF template
<generic:importdesign modelnamespace="" modelfile="" modelclass="" modelmode="NORMAL|SINGLETON|SESSIONSINGLETON" namespaceparam="" templateparam="" [getmethod=""] [dependentactionnamespace="" dependentactionname="" [dependentactionparams=""]] />
The attributes have the following meaning:
  • modelnamespace: Namespace of the model class. (Allowed characters:: [A-Za-z0-9:])
  • modelfile: Name of the model class' file. (Allowed characters: [A-Za-z0-9_])
  • modelclass: Name of the model class. (Allowed characters: [A-Za-z0-9_])
  • modelmode: Creation mode of the model. (Allowed values: NORMAL|SINGLETON|SESSIONSINGLETON)
  • namespaceparam: Name of the model param, that returns the namespace of the template. (Allowed characters: [A-Za-z0-9_.-])
  • templateparam: Name of the model param, that returns the name of the template. (Allowed characters: [A-Za-z0-9_.-])
  • getmethod: Name of the model method, that should be used to query the template name and namespace of the template to include. Please note, that the method must expect one param that is given the value of the namespaceparam or templateparam attributes respectively and the tag expects that the function returns the value of the two parameters. By default, the getAttribute() function is used. (Allowed characters: [A-Za-z0-9_])
  • dependentactionnamespace / dependentactionname / dependentactionparams: These three options are intended to automatically register an action with the front controller. This functionality is helpful, if a module is included by the tag and a front controller action is used for navigation purposes.

    The attribute dependentactionnamespace defines the namespace of the action (e.g. sites::mysite::biz) and dependentactionname the name or the alias of the action (e.g. Navigate). dependentactionparams contains the params of the action like param1:value1|param2:value2. This format ist already known from the action configuration file layout.

In order to use the tag, you must first add the tag to the current scope by placing
APF template
<core:addtaglib namespace="tools::html::taglib" class="GenericImportTemplateTag" prefix="generic" name="importdesign" />
before the tag definition.

Notes:
  • As an real life application example the Behind the site can be used. This article describes, how this documentation page is implemented and which tools of the framework are used.
  • If a front controller action is used for navigation purposes, the action class must set the class variable $keepInURL to true. This causes the LinkGenerator to include the action and it's params to be included while url generation.
  • The registration of the action is only done, if the dependentactionnamespace and dependentactionname attributes are present in the tag definition and the action was not registered before. The action params attribute is optional.

4. core:appendnode tag

Within a discussion about reusable template fragments (e.g. forms), the idea occurred to design a taglib, that can import various content to the scope of the current document. Thanks to the generic DOM structure of the GUI elements of the framework, this task is quite easy.

In order to provide a generic and reusable function, the 1.8 branch now features the <core:appendnode /> tag, that can import any content from a defined template. To use the tag, you must provide two attributes similar to the importdesign tag: namespace and template.

As of version 1.12, the optional attribute includestatic is available. It can be used to include all the content defined in the included template by setting it's value to true. In case the value contains any other value or the optional attribute is not defined, only the DOM nodes (instances of taglibs) of the included template are re-located.

4.1. Inclusion of templates

To include reusable fragments, the following code must be placed within the desired template:

APF template
<core:appendnode namespace="..." template="..." [includestatic="true" ]/>

If you want to reuse a special template, that is ised to display a domain object of your application, it is suitable to define this tag within a seperate template file (namespace: sites::testsite::pres::templates::generic; template: generic_templates). The tag definition my look like this:

APF template
<html:template name="ReusableTemplate"> ... <template:placeholder name="DisplayName"> ... </html:template>

In order to use the html template within another template file, the fragment can be included using the following tag definitions:

APF template
<core:appendnode namespace="sites::testsite::pres::templates::generic" template="generic_templates" />

4.2. Usage of the imported elements

The usage of the elements imported by the <core:appendnode /> tag is identical to the previous approach. This is because the elements are directly appended to the current children list within the DOM tree. Especially, the document controller's methods (e.g. getTemplate()) can be used as well.

To address the template printed in chapter 4.1, the following code snippet can be used:

PHP code
$tmpl = &$this->getTemplate('ReusableTemplate');

4.3. Important notes

Due to the fact, that template parsing is done identically to the importdesign tag, the developer must care of the tags included in the special template. If necessary, tags have to be announced using the adequate core:addtaglib statements.

Further, the tag creates transformation marker tags within the origin template, to enable the transformOnPlace() feature of the included tags supporting this. Please be aware, that the sequence of definition is equal to the marker tag order!

In case you want to include static content of the included template such as

APF template
<div class="formattingContainer"> <html:template name="ReusableTemplate"> ... </html:template> </div>

includestatic must be set to true.

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.