Quicknavi |
|
Builtin modules
The release package of the adventure php framework contains several full featured modules based on
the framework's components. The modules come from applications which are already used in web pages
and are given to the release as an addition or other applications to ease development or to give
more code examples. These are the modules available:
- comment function
- contact form
- guestbook
- pager
- social bookmarking
- CAPTCHA taglib to use within forms
1. Comment function
The comment function modul is a modul that can be configured and included in each web page by adding
an XML tag:
<core:importdesign
namespace="modules::comments::pres::templates"
template="comment"
categorykey="{CAT_KEY}"
/>
The value "{CAT_KEY}" must be changed to something useful. A detailed description on the
function of this modul can be found in the tutorials section under
comment function.
2. Contact form
Contact form is the most often modul found within a web page. This module offers a complete software
stack, that must be configured to meet the needs. The modul can be added to a website by providing
the XML tag
<core:importdesign
namespace="modules::kontakt4::pres::templates"
template="kontakt"
/>
A detailed description on the function of this modul can be found in the tutorials section
under contact form.
3. Guestbook
Similar to the comment function the guestbook module can be added to your site out-of-the-box, too.
The only thing to do is to set up the database by executing the init script located in the module's
data directory. To integrate the module into a web page just add the XML tag
<core:importdesign
namespace="modules::guestbook::pres::templates"
template="guestbook"
guestbookid="{GB_ID}"
/>
The value of the parameter "{GB_ID}" must be set to the guestbook ID, that wants to be
displayed on the desired page. A detailed description on the function of this modul can be found in
the tutorials section under guestbook.
4. Pager
The pager component is a backend tool, that can be used to control the loading of database objects.
To provide paging functionality, the pager is included in the modules comment function and
guestbook. Below the intent and the functionalities are described in detail.
4.1. Usage
The pager merely consists of a business component (pagerManager), a presentation
layer component that generates the HTML code of the pager widget (DocumentController
pager_2_v1_controller.php) and a data layer module that gathers information that are
needed in the busines tier. To use the pager, it must be created by using the
pagerManagerFabric.
4.2. Configuration
To be able to use a pagerManager for loading database objects it must be configured properly. Therefore
the developer must create one configuration file and at two statement files. The config file envelops
the following parameters:
[<SectionName>]
Pager.EntriesPerPage = "<Objects per page>"
Pager.ParameterStartName = "<URL parameter for the start parameter>"
Pager.ParameterCountName = "<URL parameter for the count parameter>"
Pager.StatementNamespace = "<Statement namespace>"
Pager.CountStatement = "<Load-Entries-Count statement>"
Pager.CountStatement.Params = "<Statement parameter>"
Pager.EntriesStatement = "<Statement parameter>"
Pager.EntriesStatement.Params = "<Load-Entry statement>"
Pager.DesignNamespace = "<Namespace of the pres template>"
Pager.DesignTemplate = "<Template name>"
Both of the statement files must contain a set of parameters, that can be filled by the pagerManager.
Within the Load-Entries-Count statements various parameters can be used to delimit the result
set. These can be defined by the Pager.CountStatement.Params directive or while
creating the pagerManager with the pagerManagerFabric. The result of the query is
expected in the result offset EntriesCount. Hence, the statement must contain a
SELECT COUNT(row) AS EntriesCount ...
The Load-Entry statement must always contain the LIMIT clause
LIMIT [Start],[EntriesCount]
Further, the pager expects the result of the Load-Entry statement to be stored in the offset
DB_ID. Therefore the sql query must contain an alias definition like this:
SELECT row AS DB_ID ...
Other parameters must be configured using the Pager.EntriesStatement.Params directive
or while creating the pagerManager with the pagerManagerFabric.
4.3. Example of use
A detailed description on the function of this modul and its usage can be found in the
tutorials section under comment function.
Besides, the API of the PagerManagers is used as follows:
Load the relevant object IDs:
// generate pagerManager
$pMF = &$this->__getServiceObject('modules::pager::biz','pagerManagerFabric');
$pM = &$pMF->getPagerManager('{CONFIG_SECTION}',array('AddParams' => 'Value'));
// load IDs
$IDs = $pM->loadEntries();
// load data
$M = &$this->__getServiceObject('namespace::to::data::component','DataMapper');
$List = array();
for($i = 0; $i < count($IDs); $i++){
$List[] = $M->loadDomainObjectByID($IDs[$i]);
// end for
}
Load the business objects with the pagerManager:
// generate pagerManager
$pMF = &$this->__getServiceObject('modules::pager::biz','pagerManagerFabric');
$pM = &$pMF->getPagerManager('{CONFIG_SECTION}',array('AddParams' => 'Value'));
// load data
$M = &$this->__getServiceObject('namespace::to::data::component','DataMapper');
$List = $pM->loadEntriesByAppDataComponent($M,'loadDomainObjectByID');
5. Socialbookmarking
The buzzword Web 2.0 summarizes all functions that improve interaction with the
website visitor. This includes the division of "Socialbookmarking" offered on sites like
http://del.icio.us/, http://www.mister-wong.de/ or
http://www.technorati.com/ as a free internet service. To make it easy for the website user
to bookmark your web page the module was created. The output of this module can be seen on the top
of the page near the printer symbol.
5.1. Configuration
To use this module shipped with the release package at first no configured must be created. To
include the module into a web page two configuration files must be adopted:
More configuration files are not necessary.
5.2. Appliance
There are two flavours to display the previously configured bookmark services: usage of the
socialBookmarkManager or the taglib. The socialBookmarkManager must be
created as a service object.
//
// get socialBookmarkManager
//
$sBM = &$this->__getServiceObject('modules::socialbookmark::biz','socialBookmarkManager');
//
// configure params (optional)
//
$sBM->set('Width','20'); // Breite der Bookmark-Icons
$sBM->set('Height','20'); // Höhe der Bookmark-Icons
$sBM->set('URL','http://www.example.com'); // URL der zum Bookmarking angebotenen Seite
$sBM->set('Title','Titel der Seite'); // Titel der zum Bookmarking angebotenen Seite
$sBM->set('Target','_blank'); // Ziel-Fenster der Bookmarking-Links
//
// generate bookmark HTML code
//
$BookmarkServices = $sBM->getBookmarkCode();
Dealing with the taglib is more easy. This tag needs to have the attributes width
and height. To use the tag it must be announced using the
<core:addtaglib /> directive:
<core:addtaglib namespace="modules::socialbookmark::pres::taglib" prefix="social" class="bookmark" />
<social:bookmark [width=""] [height=""] [url=""] [title=""] [target=""] />
6. CAPTCHA-Taglib - an addition to forms
The modul captcha enables the developer to easily integrate CAPTCHA functionality
into existent forms. For this reason, the taglib included in the captcha module must be placed within
the desired form and the front controller action used to deliver the captcha image needs to be
configured. Moreover, the taglib implemenation gives you an example of how the
<form:addtaglib /> tag can be used to extend form functionality.
The following chapters describe how to include the captcha tag into your form.
6.1. Configuration of the front controller action
As mentioned above, the delivery of the captcha image is done by a front controller action included
in the module. To make sure, that the image is served correctly, the project must be configured using
the front controller. If your project uses the page controller, the bootstrap file must be adapted.
In case, your index.php contains
include_once('./apps/core/pagecontroller/pagecontroller.php');
$Page = new Page('apfdemo');
$Page->loadDesign('sites::demosite','pres/templates/website');
echo $Page->transform();
these lines must be changed to
include_once('./apps/core/pagecontroller/pagecontroller.php');
import('core::frontcontroller','Frontcontroller');
$fC = &Singleton::getInstance('Frontcontroller');
$fC->set('Context','sites::demosite');
$fC->start('sites::demosite::pres::templates','website');
The context of your application and the path and the name of the initial template must be set as
desired in your project.
After this change is done, the front controller action must be configured. For this reason, the
front controller expects the configuration file
/config/modules/captcha/biz/<CONTEXT>/<Environment>_actionconfig.ini
containing the action configuration when calling the image url
/?modules_captcha_biz-action:showCaptcha=name:...
or in case of url rewriting activated, the url
/~/modules_captcha_biz-action/showCaptcha/name/...
(see source code of the taglib). Context and Environment must be
replaced with the correct values from your project. For details on configuration, please refer to
basics, chapter 3.3 bzw.
configuration, chapter 2.
The content of the action configuration file can be copied from the template file
/config/modules/captcha/biz/actions/EXAMPLE_actionconfig.ini included in the
adventure-configpack-* release files.
6.2. Inclusion of the tag
In order to use the captcha tag, it must be announced within the desired form. This can be achieved
using the <form:addtaglib /> tag, whose functionality is nearly the same as
the <core:addtaglib />. After that, the tag can be placed within the form.
The following code box shows a typical example including the commonly used attributes of the tag:
<html:form name="MyForm" action="post">
...
<form:addtaglib namespace="modules::captcha::pres::taglib" prefix="form" class="captcha" />
<form:captcha
text_class="input_field"
text_style="width: 318px;"
validate="true"
button="CreateGuestbookEntryButton"
/>
...
</html:form>
Looking at the output of the form, the tag creates a captcha image and a text field, that can be used
to fill in the captcha string. The list displayed afterwards describes the attributes of the captcha
tag:
- image_style: CSS styles of the captcha image
- image_class: CSS classes of the captcha image
- text_style: CSS styles of the text field
- text_class: CSS classes of the text field
- validate: Activation of the validation
- button: Name of the button of the form
6.3. Functionality of the tag
By means of directly integrating the captcha tag into a form, the tag can influence the form's
valiation. If the captcha string was correctly filled in the text field provided, the form's state
is set to "valid". If not, the tag lib implementation marks the form as "invalid" and the user
cannot finally submit the form. To ensure, that the form cannot be sent on wrong captcha string input,
the form must be checked having the isSent and isValid event in
the cooresponding controller. For security reasons, the captcha image is regenerated with each request.
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.
|
