A closer look at Open Power Forms

Zyx — Sun, 06 Sep 2009 09:20:00 +0200

After releasing the first stable version of Open Power Template, we gained an opportunity to focus on other Invenzzia projects as well. One of the new enterprises is a form processing library which has been given a name Open Power Forms. In the last days, I managed to implement the basic functionality and run the first test files and I would like to introduce you in the new project. From this entry, you are going to get to know, what OPF actually is, what are its benefits and main goals and what has been implemented so far.

Open Power Forms

Open Power Forms is a form processing library. It manages the logic behind the forms and allows the programmer to create them with a set of simpler rules. He simply defines what he would like to see there and waits for the input data. The complete task list of a form processor can be found below:

Providing a system to define the content of a form and its behaviour: validation rules, data filters, information messages etc.
Rendering the form in the HTML format.
Validating the input data and filtering them in order to prepare them to be processed by the application logic layer.
Validation error handling and informing the user about the problems.
Managing the form layout.

As you can see, form processors play an important role in a web application. Most of the communications between the user and the script passes through forms and having a good management system for this element should be necessary. We get the unified set of rules and behaviours which speeds up the development process and eases the mainternance.

The goal

The web frameworks usually introduce their own form processing system, but sometimes is too simplified to satisfy the requirements. An example of such framework is Kohana, where we have validators, view helpers and nothing more - it is our task to build and implement the whole logic, using these elementary blocks. The other ones provide a convenient API, but lack of the more advanced features, such as multi-page forms or offer a limited choice of widgets, validators and filters. In this group the best example is Zend_Form, a part of Zend Framework. The last important problem concerns the rendering system. It is very easy to display a form, but hard to customize it. Zend_Form forces us to use massive OOP and design patterns in order to customize the HTML code which can easily break the MVC pattern by moving the view tasks to the logic or controller layer. At the same time, sfForm from Symfony provides a concept of template templates, small files written in PHP that are compiled by the extra compiler to build the form layout. Anyway, if we want to customize the look, we have to be prepared to lots of coding in PHP. The main disadvantage is that the developers of freamework-based solutions usually have no time to provide a more generalized solution which leads to wheel reinvention and the problems with code refactoring.

And we want to create a general-purpose form processing library free of those disadvantages.

OPF features

The key features of Open Power Forms are the form management logical model and the rendering algorithm. We begin with focusing on the first issue. Most of the form processors treat the form as a list of atomic fields, sometimes grouped. It is very easy to implement such a form processor, but it cannot handle more advanced forms. Let's imagine the column insertion form in phpMyAdmin. It allows the administrator to add several columns at the same time by multiplying the same form several times in the table rows. Other web applications may use multi-step forms, where the user fills the form called "Step 1", then goes to "Step 2" and so on. The entire data are processed after filling in the final step. What is more, some steps may be activated only if the user made a certain choice in the previous ones. The better model to represent such situations is to unify the concepts of a form and a form field. Open Power Forms formally makes no difference between them. We are allowed to append one form as a field of the other form, guaranteed the library will recognize our intentions.

If we are talking about not-reinventing-the-wheel in the form rendering issue, we must throw away all the ideas that do not work in the other libraries. They rely on PHP and they fail, but we already have a great template language provided by Open Power Template. It offers us some brilliant features, very useful in the form rendering, that is components and snippets. The component system has been designed especially for forms - we work there with components, which are various form widgets, such as input fields, select lists, radio buttons etc. Components separate the field logic (managing the labels, IDs, attributes, errors etc.) from their presentation. The field logic is implemented in a PHP class, and the presentation with a component port in a template. A sample port looks like this:

<opt:inputComponent name="foo">
  <div>
    <label parse:for="$system.component.id">{$system.component.label}</label>
    <opt:display />
    <opt:onEvent name="error">
       <p class="error">{$system.component.error}</p>
    </opt:onEvent>
  </div>
</opt:inputComponent>

In the example above, we create a statically deployed port, where the template automatically creates a component object for it, using the tag name (opt:inputComponent). But we have also standalone ports, where we load the component from a template variable, and the component itself may be created with a script. In both cases, the content of the XML tag remains the same. What is more, we can use snippets to save the form layout in one place and simply insert it in all the ports of all the forms we have:

<opt:snippet name="fieldLayout">
  <div>
    <label parse:for="$system.component.id">{$system.component.label}</label>
    <opt:display />
    <opt:onEvent name="error">
       <p class="error">{$system.component.error}</p>
    </opt:onEvent>
  </div>
</opt:snippet>

<opt:component from="$variable" template="fieldLayout">
  <!-- we can set some attributes here -->
</opt:component>

At any time, we may decide, whether to implement a field-specific layout for particular components or use the default ones. Moreover, we operate on simple HTML with some extra tags without the need to create hundreds of files and deal with the implementation details, as OPT hides the unncecessary logic from us.

Open Power Forms is going to provide a set of OPT-compatible components integrated with the form processing system, plus some extra tags, data formats and functions for designing forms and managing their layouts. Below, we can see a working template that uses the new features:

<?xml version="1.0" ?>
<opt:extend file="base.tpl">
  <opt:snippet name="title">Situation 1</opt:snippet>
  
  <opt:snippet name="content">
	<!-- configure CSS styles for the elements -->
	{$design.form.valid is 'form'}
	{$design.field.valid is 'row'}
	{$design.field.invalid is 'row row-error'}
	{$design.input is 'inputText'}
	
	<!-- display a form -->
	<opf:form name="form1">
		<div class="errors" opt:if="not $system.form.valid"><p>The form is invalid.</p></div>
	 
	 	<!-- load the components assigned to the "default" placeholders -->
		<opt:section name="default">
 			<opt:component from="$default.component" template="widget">
			</opt:component>
		</opt:section
		
		<!-- some final stuff -->
		<input type="submit" value="Submit" />
	</opf:form>
  </opt:snippet>
</opt:extend>

And here is the PHP part of the form:

class My_Form extends Opf_Form
{
	// An event
	public function onInit()
	{
		$item = $this->itemFactory('title');
		$item->setRequired(true);
		$item->addValidator(new Opf_Validator_Length(5), 'The length is invalid');
		$item->setWidget(new Opf_Widget_Input)
			->setLabel('Title');

		$item = $this->itemFactory('countries');
		$item->setRequired(true);
		$item->addValidator(new Opf_Validator_Type(Opf_Validator_Type::INTEGER), 'The field type is invalid.');
		$item->setWidget(new Opf_Widget_Select)
			->setLabel('Countries');
	} // end onInit();

	// An event
	public function onRender()
	{
		$view = $this->getView();
		
		$item = $this->itemFactory('countries');
		$item->getWidget()->setOptions(array(0 =>
			'China',
			'France',
			'Germany',
			'Great Britain',
			'Poland',
			'Russia',
			'Spain',
			'United States'
		));
	} // end onRender();

	// An event
	public function onAccept()
	{
		$view = $this->getView();
		$view->setTemplate('results.tpl');
		$results = array();
		foreach($this->getValue() as $name => $value)
		{
			$results[] = array('name' => $name, 'value' => $value);
		}
		$view->results = $results;
	} // end onAccept();
} // end MyForm;

The list of core features:

Flexible design - the forms can be constructed either by extending the base form class or by configuring the bare form object and responding on the events.
Event listeners - they can be used to implement the logic of common form parts by extending the initialization or rendering events. The concept is similar to event listeners and behaviours in Doctrine ORM.
AJAX support - the AJAX requests could be implemented as ordinary form events and the library will set up the entire communication process.
Huge (and useful) set of widgets, validators and filters.
Web Forms 2.0 support.
CSRF attack protection.
Support for complex forms: multi-step forms or forms built of smaller forms.
Doctrine ORM support out-of-the-box.
Full integration with Open Power Template library.
Internationalization support.
Integration with Zend Framework thanks to the already available OPL port for Zend Framework.

Current status

The library currently implements the most important core features, such as data validation, error reporting and form rendering and is able to process simple forms. We are currently working on extending the logical model in order to support more complex forms and their proper rendering. In the very near future, the first development version will be released. We would appreciate any suggestions and ideas.

Conclusion