Contact form

1. Introduction

The present chapter gives another application of the form tag libs and the <core:importdesign /> tag. The contact form described in the following text gives the opportunity to prevent e-mail addresses from beeing grabbed by bots. Moreover, the recipient list is configurable and extensible. The module can be included in any page controller compliant application by using the <core:importdesign /> tag.

2. Basics

This tutorial includes technics that were already used in the previous tutorials. The author assumes, that you have read chapter 2 of the comment function tutorial carefully. This chapter describes the separation of a single software into three different layers, that contain different functionality. Beyond, the section depicts how domain objects are used as an agent of communication and which role is dedicated to the MVC pattern.

2.1. Configuration

To be able to integrate the contact form module in various projects the project specific parts must be outsourced to application configuration files. Configuration is necessary in two flavours: first of all the recipients must be configured, second the texts of the form tag libs (validators) must be defined per project.

At this point of the tutorial we're going to do a little excurse to functionality of the form validation included in the framework:
The tags

• <form:validate />
• <valgroup:validate />

need a language dependent configuration file for the validation messages to display. The configuration file required for the taglibs is expected to be storend in {CONTEXT} is meant to be a place holder for the context of the current application and the value for {ENVIRONMENT} must be read from the registry. In case of the presend documentation page the file must be named like As described in the Standard taglibs article in section 2.3.16 and 2.3.17 these tags can be configured using the additional attributes

• msginputreq=""
• msginputwrg=""

These attributs define the configuration key that contains a language dependent text to be shown, if the desired field is not filled correctly. This makes it possible to define a single set of validation texts for an entire application. Moreover, it is easy to translate these texts, becaues they are stored in simple text files.

Example:
In order to display the message if a form control was not filled and to print the text if the field was not filled with a correct e-mail address, the validator must be configured as follows: The attribute button defines the name of the button, that should initiate validation, field indicates the field, that should be checked and type explains the type of the validator. The keys contained in the two attributes msginputreq and msginputwrg were prefixed with "Contact.EMail." to indicate, that these configuration keys belong to the contact form application and are intended to declare the validation texts of the e-mail field. This convention is common to be able to differentiate between the various configuration keys provided within one configuration file. Besides, it is useful to place some comments in the configuration file.

A configuration file intended to be a basis for a multilanguage application may have the following content:

2.2. Multilanguage applications

The adventure php framework features several options to create multilangual applications or modules. At first, the language is stored within every single DOM node or service layer and hence can be used to display language dependent texts within a document controller. Further the framework provides the XML tags

• <html:getstring />
• <template:getstring />
• <form:getstring />

that display language dependent texts from configuration files. In case of the present module both possibilities are used. As a basis, the configuration file is used to store the texts to be displayed in the module. The file is filled with the following values: The values stored there can be displayed by using the follwing XML tags:

• <html:getstring namespace="modules::kontakt4" config="language" entry="form.person" />,
• <template:getstring namespace="modules::kontakt4" config="language" entry="form.person" /> oder
• <form:getstring namespace="modules::kontakt4" config="language" entry="form.person" />

The second possibility of of displaying language dependent texts can be used to label form controls like buttons. In this case the labelling must be done within a document controller. The following code shows how to achieve this:

2.3. Structure of the module

According to the structure described in the comment module tutorial the structure of the kontakt4 module looks like this: The biz folder serves the business components (two domain objects and one manager), data contains the mapper class, that reads the recipients, and the pres folder stores the controller and template files needed by the presentation layer. Considered as a whole, the contact form consists of the following files:

• /modules/kontakt4/pres/templates/kontakt.html:
  The file kontakt.html contains the main design and coordinated the output of the form or the thank-you-page with a <core:importdesign /> tag.
• /modules/kontakt4/pres/templates/formular.html:
  This file contains the definition of the form view.
• /modules/kontakt4/pres/templates/meldung.html:
  In the file meldung.html the content of the thank-you-page is defined.
• /modules/kontakt4/pres/documentcontroller/kontakt_v2_controller.php:
  To fill the form view with dynamically generated content a document controller is needed. The file kontakt_v2_controller.php contains the document controller class definition.
• /modules/kontakt4/biz/contactManager.php:
  contactManager.php is the home of the business component class, that coordinates the workflow of the application.
• /modules/kontakt4/biz/oRecipient.php:
  oRecipient.php contains the definition of the recipient domain object.
• /modules/kontakt4/biz/oFormData.php:
  oFormData.php contains the definition of the form data domain object.
• /modules/kontakt4/data/contactMapper.php:
  The file contactMapper.php is used to define the data layer component, that loads the recipients out of the configuration file and presents them as domain objects.

As already mentioned the following configuration files must be provided:

• /config/modules/kontakt4/{CONTEXT}/{ENVIRONMENT}_empfaenger.ini:
  Configuration of the recipients.
• /config/tools/form/taglib/{CONTEXT}/{ENVIRONMENT}_formconfig.ini:
  Texts for the validator form tags.
• /config/modules/kontakt4/{CONTEXT}/{ENVIRONMENT}_language.ini:
  Language dependent labels.

The syntax of the configuration files was already described above but the content of these files is discussed later on.

3. Implementation of the module

This tutorial uses the TOP-DOWN approach once again. The current chapter therefore describes the files mentioned above starting with the presentation layer and in the given order:

3.1. File kontakt.html

The template file kontakt.html defines the structure of the module. It contains the headline, that is displayed by use of the <html:getstring /> tag and a <core:importdesign /> tag, that defines the view that either displays the form (default behaviour) of the thank-you-page: Note: Within this template file, the <core:importdesign /> tag is used with the pagepart option. This means, that the name of the template can be influenced by the URL parameter pagepart. If the parameter is not present in the request string, the name of the template is taken from the XML tag definition. In this case the form is displayed.

3.2. File formular.html

This template file contains four essential blocks:

• Definition of the document controller (Line 1)
  Here the document controller (MVC controller of the current DOM node) that is taken for transformation is defined.
• Inclusion of external tag libs: (Lines 2-3)
  To be able to use the "html:form" or "html:getstring" tag libraries they must be introduced by using the "core:addtaglib" tag.
• Definition of the HTML content: (Lines 5-9)
  The lines 5 to 9 define the HTML frame of the form view. This view features notices, that are included using the <html:getstring /> tag and a <html:placeholder /> tag that is filled with the output of the form within the document controller.
• Form: (Lines 11-43)
  The lines 11 to 43 define the form. It contains a validator group, that is used to display validation messages. The labeling of the form controls is done by the <form:getstring /> tag.

3.3. File meldung.html

Within the file meldung.html the thank-you message is defined, that is displayed on submission of the form. Merely this message contains a sentence that describes, that the recipient will send an answer soon. In this case, the message is taken from a configuration file, that contains the multilanguage texts of the module. Due to the fact, that these texts are statical no more document controller is necessary.

3.4. Document controller kontakt_v4_controller

The document controller kontakt_v4_controller inherits from the abstract document controller base_controller (interface). Because of the DOM structure of the framework each document controller must inherit from the base document controller. The rest of th class can be defined freely. The developer can define own class methods or load classes via import() each time he wants to. In case of the contact form the method __buildForm() is used to build the form. To control the output of the form the abstract method transformContent() is implemented. This function describes, that the form is diplayed as long as the form is not filled as desired by the programmer (see line 60). In case of correct values the business layer is created to send the form and to display the thank-you-page (template file meldung.html). Taking a closer look to the source code, you can see, that the controller class uses two more components: the RequestHandler and the contactManager. The first class is a class integrated in the framework, that registers request variables in a locally used array and fills this offsets with default values if not present in the request. Details on this class can be seen on the class reference page. The second component is the business layer class of the contact form. This class provides interfaces to load recipients or to submit the form.

3.4.1. Method transformContent()

The method transformContent() takes over the generation of the view. For this reason a reference on the form object is fetched to check, wheather the form is sent and filled correctly. If not, the form is displayed in the current view. Is the user input considered ok, a form data domain object is created and filled. After that the business component is created by use of the __getServiceObject() method. The function sendContactForm() called with the domain object oFormData as an argument then sends the data of the form via mail. The submission and the redirection to the thank-you-message is completely done by the business layer.

3.4.2. Method __buildForm()

The function __buildForm() is often called a "helper function", due to the fact that this private method only encapsulates the form generation. __buildForm() is in charge of these three tasks: at first, the action attribute of the form must be filled with a URL fitting the module's URL structure, second the URL of the validator group's warning image must be set and last but not least the select field must be filled with recipients. Moreover, the button of the form must be labeled with a language dependent text.

Set the action attribute:
As each object inherits from "APFObject", the form method features the function setAttribute(). With aid of this method the attribut action can be set.

Configuration of the validator group:
To set the validator group's place holder "WarnBild" and "WarnText" the programmer at first gets a reference on the validator group. Within the internal DOM the validator group is a child object of the form DOM node. In order to get a reference the developer needs to have a valid pointer on the form object. The method getFormElementByName() and getFormElementByID() is intended to return a reference on a form child object identified by name or ID. The validator group class offers the setPlaceHolder() function, concerning the API documentation. This method can be taken to set the place holder of the validator group.

In case of the place holders "WarnImage" and "WarnText" the language dependent configuration file is used. The image and the corresponding text are located in thge configuration file in the section [en] (for englisch language) and the under the configuration key To get the lanuage dependent value out of the configuration file the section is choosen by the internal member $this->__Language, that allways contains the current language selected on page controller or front controller startup or during front controller action execution. The member variable contains a two letter ISO country code. Within the current document controller this task is done by the following source code:
At the end of the method the form object is transformed and returnd to the calling method.

3.5. Class contactManager

The contactManager class is an implementation of the business layer. It encapsulates the business logic of the application and communicates with lower tiers. In this case the business layer is in charge of sending the form or loading recipients. Therefore the current layer defines two API methods: sendContactForm() to send the form and loadRecipients() to provide a list of recipients. The interface between the presentation and business layer is formed by the two domain objects oFormData and oRecipient. In the first two lines twoe more framework components are included to assist mail delivery (mailSender) and link generation (LinkHandler).
Within the method sendContactForm() two service layers are instanciated, that are necessary for the delivery of the form data: the data layer to load the choosen recipient object and the mailSender to send confirmation and notification mails.
The function loadRecipients() is a service function for the presentation layer, that loads recipient domain objects.

4. Class contactMapper

The contactMapper is a data mapper pattern implementation. It is used as a data provider by the business layer. For this reason the mapper loads the configuraton file, that contains the recipients and maps this data into recipient domain object (oRecipient). The configuration file itself is separated into several sections: Each section is mapped into on domain object (oRecipient). loadRecipients() returns a list if oRecipient objects. Every recipient can be identified by an unique ID (see section name) and can thus the loaded by the method loadRecipientById().
If you intend to read the recipients from a database instead of a configuration file, only the implementation of the data layer methods must be changed to read the domain objects from a database.

Comments

QUICKNAVI

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

• 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 © 2009 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.