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!

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:

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:

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:

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.

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:

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:

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:

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.

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

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.

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.

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:

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:

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