Special-taglibs

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

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:

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 attribut 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])

To use the tag it must be announced using the

directive.

The following code fragment shows, how to use the iterator 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.

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

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

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:

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_.-])

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 example_controller 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 example_controller 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:

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

4.1. Inclusion of templates

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

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:

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

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:

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

includestatic must be set to true.

Comments

QUICKNAVI

• All releases
• Roadmap
• Subversion repository
• Bugtracking
• Why APF?
• Articles
• Wiki
• RPM Installation HOWTO
• Partner sites
• APF auf SourceForge.net

• Team
• Imprint
• Contact
• Privacy policy
• Legal notice
• Security
• License

Adventure PHP Framework (APF) is a product developed by the APF Developer Team. It's released under the GNU Lesser General Public License (LGPGL)
Commercial use is permitted.

Copyright © 2004 - 2012 Adventure PHP Framework
All textual content on this site is protected by Copyright Law and may be used under the Terms of the GNU Free Documentation License (GNU FDL) See Legal notice for more information.