Usage of forms

The adventure PHP framework contains a comprehensive form support based on the taglib concept. The basics of forms and the available taglibs are described in the Forms chapter. This section now discusses the usage of forms, dynamic form generation, and implementation of custon form taglibs in detail.

1. Forms & controller

Forms are kind of template fragments, that exist within the APF DOM tree, but are not displayed at transformation. To display a form, a document controller is needed. The reason for it is simple: nearly every form is attached to operations which should be executed with sending the form (e.g. save data).

In order to display a form, the following controller code can be used:

Thereby, the $form variable contains a reference on the HtmlFormTag instance, that encapsulates an APF form with all it's child elements. Having this reference, the form can be manipulated, filled, displayed, or adapted. Details can be taken from the subsequent chapters.

2. API of the form taglibs

As described within the preceeding section, a form can be referenced within a document controller easily. This section deals with the API of the form taglibs, that gives you an idea if the functionality included.

The basic form element is defined within the AbstractFormControl class. There, the structure is defined as well as the basic functionality is included. Due to the fact, that all taglibs underly the page controller lifecycle each form element must implement the methods, a "normal" taglib must implement, too.

Class AbstractFormControl implements the following methods:

• isValid(): The function enables you to query the validity status from inside the form as well as from the outside.
• markAsInvalid(): Marks a form element as invalid.
• markAsValid(): Marks a form element as valid (since 1.17).
• markAsSent(): Marks an element as sent (only relevant for forms and buttons).
• isSent(): Checks, whether a form was sent or not.
• isChecked(): Returns true, in case a checkbox is checked and false otherwise.
• check(): Enables a checkbox.
• uncheck(): Deactivates a checkbox.
• getValue(): Returns the input of an element. Normally, this is just the content of the value attribute, except in special cases, as, for example, text areas, which store the user input as content of the tag (since 1.14).
• setValue(): Sets the input of an element. Normally, this is just the content of the value attribute, except in special cases as for example text areas which store the user input as content of the tag (since 1.14).
• isFilled(): Returns true in case a text field or text area was filled with text and false otherwise. This works only for text fields and text areas (form:text and form:area) (since 1.15).
• isSelected(): Returns true in case something was selected in a single or multi select and false otherwise. If something was selected which returns "" the method returns false too. This works only with single select or multi select (form:select and form:multiselect) (since 1.15).
• isVisible(): Returns the visibility status of the present form control. true indicates that the control is visable, false marks form controls that are not included to be displayed during the form generation (since 1.17).
• hide(): Hides a form control from the form output (since 1.17).
• show(): Sets the visibility status of a form control to true (since 1.17).
• addFilter(): Adds a filter to the current form control.
• addValidator(): Adds a validator to the current form control.
• addAttribute(): Can be used to add content to an existing attribute. This is used when notifying invalid form elements.
• notifyValidationListeners(): Notifies all listeners of a form element, that it is invalid.
• presetValue(): This method provides presetting for form text fields. It can be directly used or overwritten for custom form elements.
• setPlaceHolder(): This method implements a generic method to set place holder tags within sub tags of the form tag. Please note, that place holder tags must be named *:placeholder to be able to use the method.
• addAttributeToWhitelist(): Adds the attribute applied to the method to the white list of the current form control. This causes the attribute to be included into the HTML source code.

Using this methods, the developer is supported to implement custom form taglibs as described in chapter 7.

3. Validation

Validation is executed via the form:addvalidator, that attaches a validator to the desired form control. The validator is executed, when the click event of a form button is fired. Having a look at the timing, validation is executed within the onAfterAppend() method of each taglib. This is after the analysis phase (at this time, the onParseTime() of each taglib is executed) and the DOM tree is fully created by the page controller.

Within the onAfterAppend() method of the form:addvalidator tag, the validator is created and initialized with the necessary information (button and target form control) and given to the target element. The element itself executes the validator in case it is active and checks the result. In case of errors, the notify() method of the validator is called.

3.1. Validation status query

Since each form element knows about it's validation status within the new implementation, the form's isValid() method must query the status of each form element. Using a document controller, you can get the form status as follows: Further, you can ask a single form element to return it's status using the subsequent PHP code: To decide, whether a button has been clicked, use the following code:

3.2. Display of validation messages

Introducin form validation, the fields containing wrong data are often marked with red borders and the user is presented a validation message. To achieve this, the taglibs <form:error /> (used for global error messages) and <form:listener /> can be used. As an alternative, you may use place holders, that are filled with the appropriate error messages within the controller code.

3.2.1. Form error

The <form:error /> displays it's content, in case the form is not valid - regardless which field is invalid. For this reason, the tag queries the form's status at transformation time:

Template: Controller:

Within the <form:error /> tag, you may define further tags for formatting or content generation purposes as described in chapter display of form errors.

3.2.2. Listener

The <form:listener /> tag is aimed to display field specific errors. As noted in the introduction chapter, the notify() method is called, when a form control is considered invalid. This method then notifies all listener tags, that have registered on this event to display their content at transformation time.

In the below, field specific messages are displayed in case a desired field is marked invaluid:

Template: Controller:

Within the <form:listener /> tag, you may define further tags for formatting or content generation purposes as described in chapter listener.

3.3. Manual validation within the document controller

In some kind of situation it may be easier or faster to do form validation within a document controller instead of writing a validator. In order to allow marking form controls a new form control method was introduced in Version 1.14.

As an example, the form field searchterm contained in the subsequent form should be validated using a custom rule within a document controller:

The corresponding controller contains the following code to invalidate the search term field in case it contains an e:

Sending the form including any word that contains the letter e the searchterm field is technically and optically marked as invalid. The latter is done by adding the default validation marker css class. In case you want to apply your own css class you can do this by applying a hard-coded class name or by taking it from the form control's attribute list (e.g. valmarkerclass).

4. Handle form content

A frequent job with the handling of forms is the readout of values. To support this, the following methods can be used in the document controller:

• getFormElementByID(): Returns a form element selected by id (Attribute: id).
• getFormElementByName(): Returns a form element selected by name (Attribute: name).
• getFormElementsByTagName(): Returns a list of form elements selected by tag name (z.B. form:text).
• getFormElementsByObjectID(): Returns a form element selected by the APF DOM id. This can be used generating dynamic forms.

4.1. Select by name

Are you faced with the task to gather the values of the form described in chapter 3.2.2., you can use the subsequent controller code:
Due to the fact, that an APF form is a DOM subtree containing form taglibs, a place holder within an error tag can be addressed with two steps. First, get the instance of the error tag, and second get the place holder's instance from the error tag. To have a dedicated example, consider the following form definition: To fill the place holder within the <form:error /> tag use the following controller code:

4.2. Selection by tag

In some cases, it may be useful to select form elements by it's tag name. For this application case, the getFormElementsByTagName() method is available. It returns a list of form controls filtered by the given tag name.

In combination with the Generic OR mapper the method can be used to read the content of the form elements and directly map them to a GenericDomainObject. Achieving this, you can use the following code: Please note, that the method returns only those elements which exist as direct child nodes in all cases.

5. Manipulation of forms

The implementation of the form taglibs of the framework included several opportunities to manipulate form elements or their values. The next chapters thus describe solutions for the most frequent tasks.

5.1. Form presetting

To preset form controls (e.g. within an edit dialog) the

• getFormElementByName(),
• getFormElementByTagName(),
• getFormElementByID() oder
• getFormElementByObjectID()

methods can be used to gather an instance of the desired form control. After that, you can take one of the standard method

• getAttribute()

or

• setAttribute()

respectively to retrieve or fill the content.

The subsequent code box defines a form, that is filled using the php code below:

Template: Controller:

5.2. Prefilling of form controls

Treatment of select and multi select fields is a bit different to normal form controls. But, the framework provides methods to ease prefilling of select fields. The subsequent code is used to prefill a form, that contains select fields in addition to normal text fields: The below controller code prefills the form:
The following code box gives presents an example taken from the User management module. The controller code first fills the select field and then preselects the desired option.

5.3. Readout of form controls

Readout of form controls is similar to prefilling. Please note, that simple and multi select fields are handled a little bit different. The following code example shows how the values can be read out from the form described in chapter 3.1:

In order to get the selected options of simple and multi select fields, getSelectedOption() and getSelectedOptions() can be used. The subsequent code box describes how:

6. Dynamic forms

In some cases it is necessary to generate forms dynamically. For this reason, the form taglib (HtmlFormTag) features the methods

• addFormElement()
• addFormContent()

and as of release 1.7

• addFormContentBeforeMarker()
• addFormContentAfterMarker()
• addFormElementBeforeMarker()
• addFormElementAfterMarker()

The first two functions can be used to add content (i.e. plain text or html) or form elements at the end of the form. The latter ones are intended to add content or form at certain positions. For this reason, the <form:marker /> tag was introduced. The tag itself does not generate any output, but can be used for positioning purposes along with the "addForm*[Before|After]Marker()" methods.

The following chapters describe, how a dynamic form can be generated displaying form coordinate fields (triangle, square, ...). Depending on the type, the corresponding fields are displayed. If the type is set to "square", four fields are displayed ...



... in case of "triangle" three fields are presented:

6.1. Form definition

As already mentioned, the dynamic definition can be done in two flavours. While using addFormElement() and/or addFormContent(), no marker is needed. Instead, the following example uses marker, because the form already contains structural elements (e.g. table).

The following code box shows the form definition needed to display the form denoted above. To keep things simple, no CSS was added. Taking a closer look at the definition, you can see, that the form consists of a static select field, that defines the types available and a marker tag for positioning. Further, a document controller is specified, to add the desired form elements in front of the marker:

6.2. Controller

The document controller is responsible for generating the form field, that depends on the type of the geometrical shape. For this reason, the constructor contains a definition of the form fields that should be displayed for a concrete type. Afterwards, the typ is read from the select field and the form is enhanced with additional content and fields. The following code box presents the implementation of the document controller needed for this functionality:

6.3. Dynamic filters and validators

As of release Release 1.11 the filter and validation comcept was completely redesigned. This does also effect the dynamic form filters and validators.

As described in chapter construction of validators and construction of filters validators and filters are attached to a form control as an Observer. Using dynamic forms, this can be simulated by imitating the <form:addvalidator /> and <form:addfilter /> tags. This means, that you can add a filter or validator using the addValidator() and addFilter() method respectively. The following code sample describes this approach in detail:

6.4. Notes

A APF form element does need information about the name of itself already at creation time. If the element doesn't know it's own name, presetting and validation cannot be enabled. In order to use presetting and validation in combination with dynamic form elements, the addFormElement(), addFormElementBeforeMarker() and addFormElementBeforeMarker() functions possess a third parameter. This parameter expects an associative list of tag attributes, that are applied to the form object on creation time. Creating dynamic form elements, it is thus recommended to at least apply the name of the tag to the third argument: Please note, that the tag attributes are also interesting for addressing the form objects after appending them to the form via the getFormElementByName() or getFormElementByID() methods.

7. Enhancement of form controls

The concept of the APF's page controller allows you to write own taglibs to create reusable elements. This also continues with forms. Custom form controls can be added using the <form:addtaglib /> tag. This tag acts similar to the <core:addtaglib />, but is restricted to forms.

The difference between a normal taglib and a form taglib is the fact, that each form taglib implements the abstract AbstractFormControl class. Hence, the form control inherits an advanced tag definition and some more functionality to enable the <html:form /> tag to handle the control. The extra functionality mentioned in the last sentence merely consists of validation and filter handling code.

The next three chapters describe the creation of custom form controls, validators and filters. Besiders, implementation examples are presented.

7.1. Form controls

As mentioned above, an APF form control is defined by the abstract class AbstractFormControl. In order to implement a custom form element, the class' functionality must be enhanced.

As an example, a form element should be discussed that generates a hidden input field in order to protect a form. In the next chapter, we are going to implement the appropriate validator. In case, the control is filled, we consider the field invalid and assume, that it was filled by automated scripts. Otherwise, the field is defined to be valid. In various blog entries this kind of fields are also as called honeypot fields.

Let's start with the basics of the element. As described in the last sentence, the tag should generate a hidden text input field. To achieve this, the taglib must return the desired source code:

Due to the fact, that validation and filter attachment as well as the method returning the validity status of the tag is already included in the AbstractFormControl class, the code printed above is all that you need by now.

In order to use the newly created form control, the <form:addtaglib /> tag can be used to announce the tag to the form:

The real functionality is now included in the honepot field validator. See the next chapter for details.

7.2. Validators

Validators are defined separately and are attached as observer since release 1.11. In order to support this mechanism, a form control must be aware of validators. In case of the honey pot field, the functionality is already included in the tag, because it extends the base class AbstractFormControl. Thus, the validator is applied the content of the value attribute and is thus able to act as descibed in the introduction.

For convenience, we call the validator HoneypotValidator. In common sense, it is a text field validator and can thus use the TextFieldValidator class as a basis. This class derives from AbstractFormValidator, what is the bas class for all validators.

Each validator must implement the validate() method, that is applied the content to validate. In case of the HoneypotValidator the content of the text field must be empty to consider the control valid. If not, the field is marked as invalid. The following code can be used to implement the descibed functionality: Due to the fact, that TextFieldValidator already contains the functionality that is necessary to notify a "real" text field and mark it with a special css class in case of errors. As of this application case, we do not need this functionality and though we have to suppress it. For this reason, we are going to overwrite the notify() method (defined within TextFieldValidator), that is called when a field failed validation: In contrast to the implementation of the TextFieldValidator class, the line TextFieldValidator die Zeile is not included. This disables the optical marking of the form element using a custom css class.

The following code box describes the application of the validator together with the above honeypot field: Thanks to the independent definition and implementation of the validator, it can also be applied to other text fields. These are all text fields and text areas shipped with the APF release.

7.3. Filter

Applying the honeypot field no filter is needed. Hence, this chapter describes a filter, that substitutes German umlauts with their phoneme equivalents (e.g. ä -> ae).

The GermanUmlautsFilter thus implements the AbstractFormFilter class that is the base class for all form filters just as the AbstractFormValidator is for validators. The abstract form filter class defines the interface for all concrete form filter implementations.

Further, each form filter implements filter() method. The function takes the content to filter as an argument and returns the filtered content.

The skeleton of the filter is as follows: The functionality of the filter is a simple string replace call using the PHP standard function str_replace(): The application of the filter using a text field or a text area can be taken from the below code box:

7.4. MultiFileUpload

With release of APF version 1.16 you can use a new tool for creating uploads offered with preview function as well as percentage progress indicator: the MultiFileUpload. For detailed information about this tool refer the documentation in the Wiki (German only): MultiFileUpload im Wiki.

8. Visibility of form controls

Release 1.17 introduces a visibility status of form controls. This status is used during the transformation to decide whether a form control is displayed or not. This allows you to show or hide form controls within a (Document-)Controller.

In addition to the visibility status dependent form controls can be defined by each control. In case the control is requested to hide from the output the dependent fields will do so as well. Using this feature, you may create dynamic forms - with some limitation.

The following chapters describe the use cases and the respective implementation.

8.1. Manipulation of the visibility via controller

In 1.17 the AbstractFormControl class has been added the

• hide()
• show()
• isVisible()

methods. Since all form controls are derived from this class, the visibility feature is theoretically present for all form controls. Please note the list of supported controls in chapter 8.3.

isVisible() can be used to query the current visibility status within a document controller or within a tag. show() defines the control as visible, hide() sets the form control to invisible.

For our further examples, we will use the following log-in form:

As you can take from the code bos the form contains one field for the user name, one for the password, as well as one field that notifies the underlying application to create a permanent log-in.

In order to hide the checkbox for the permanent log-in you may use the following controller code:

When the form is displayed the checkbox is not visible anymore and users cannot interact with it.

Please note the hints in chapter 8.4 on the implementation of custom form controls respecting the visibility definition.

8.2. Hiding dependent controls

One problem of the code described in chapter 8.1. is: the label element describing the checkbox' meaning is still present. You can avoid that by defining the label as an APF form tag. It can then be referred to as a dependent control within the checkbox' tag definition using the dependent-controls attribute. In case you hide the checkbox the label tag will be hidden, too.

The tag definition of the form is now as follows:

Defining dependent tags can be done recursively. In case you define the password field as a dependent control of the label tag, both the checkbox and the label plus the password field are hidden.

To define multiple fields as dependent controls, please specify a pipe-separated list (|) of control names. Example:

8.3. Supported controls

Defining the visibility state is not supported by all form control types. This is because elements like the <form:hidden /> tag do not generate visible output - even before 1.17 - and for elements such as the <form:error /> tag it doesn't make sense from a business requirements perspective.

Please note the following list of tags supporting the visibility definition:

• <form:button />
• <form:imagebutton />
• <form:reset />
• <form:checkbox />
• <form:file />
• <form:label />
• <form:multiselect />
• <form:select />
• <form:password />
• <form:radio />
• <form:text />
• <form:area />
• <form:date />
• <form:time />

8.4. Implementation of custom controls

The definition of the visibility definition is structurally defined within the AbstractFormControl class and is thus present to all form controls. As the behaviour of what should happen when a form control is marked hidden is managed by each form control individually you must take care of the visibility status implementing custom form controls - either respect the state or consciously ignore it.

The visibility status is held with the AbstractFormControl::$isVisible class variable. true means that the control is visible, false inidcates that the controls listed in chapter 8.3. are not displayed.

To respect the visibility status with custom form controls, the subsequent code can be used as a template:

Another use case implementing custom form controls is hiding adjacent form controls directly within the tag code. This may be necessary when one control type defines a direct dependency to another type.

Hiding all check boxes within a given form can be implemented like this within a custom form tag:

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.