controlling layout in clonefish, smarty integration, dynamic attached error messages
Layout overview
Generating forms is an automatic process, which is quite comfortable from the programmer's perspective - though it's no doubt that the client won't care about the beauty of a rock solid form generating method. In fact, the clients will only care about two things:
- does it all work?
- how does it look like?
The answer for the first answer is clonefish itself, being built to create well working forms, so let's focus on the second question: the layout.
Good news: speaking of form design there's nothing that couldn't be done using clonefish. For very complicated and "deeply designed" forms it can be tricky for the first time to "re-create" all the bells'n whistles of a beautiful form that your web designer colleague created - that's why it's important to get an overview of the layout options you have with clonefish.
in general
In clonefish, there are predefined settings that can be used to precisely override the default layouts. These settings are:
- properties of the clonefish class itself:
-
they define the form layout itself and the default container of all the elements. These settings are required, in case they're not defined well, your form will look/behave strange.
-
- there are also settings on the elements' level, placed in the configuration array:
- you can either override the form-level element container settings (the layout/alignment of the entire element row)
- or customize the default layout of the element control itself (eg. alignment of radio buttons)
- However, when you'd like to customize the layout of and element (eg. a radio button group), you'll need the element level settings: these can be different for every element.
examples, use cases
level 1 - adding a class to an input field
In case you'd like to add special parameters in the tag for an element, you can use the 'html' setting for any element, for example:
<?php
$config = Array(
'name' => Array(
'displayname' => 'Your name:',
'type' => 'inputText',
'html' => 'class="nameclass"',
)
);
?>
This is also the perfect way to add event handlers, special parameters to form elements (rows=N, cols=M for a textarea, multiple="multiple" for a select and so on)
level 2 - customizing elements
There are elements that are "rendered" themselves: for example inputRadio (radio button group) has a container containing multiple items, each item having a radio button and its label. That's why inputRadio has two layout settings:
'layout'is the layout for the container. For example, if your layout looks like<ul>%s</ul>, the items will be inserted between <ul> and </ul>'itemlayout'is the layout for the items. Assuming the above example, you should setitemlayoutto<li> %radio% %label% </li>. The%radio%and%label%are the placeholders for the button itself and the corresponding value.
level 3 - element row with a different layout
Imagine you have a form that uses tables - the table structure is defined at form level, it's a simple 2 column layout (one for the input name and one for the input itself).
Let's say we need a very large textarea spanning both columns - in this case you can use the 'rowlayout' setting for this element. This setting overrides the form-level 'element' setting which was defined under $form->layouts: you can freely reuse all the %placeholders% here.
level 4 - templating
Templating is the most powerful method Clonefish provides for reorganizing elements in a form. In Clonefish, templating means the usage of the template element type. This type has one important attribute: the value. In value you can use placeholders derived from the form you're creating: for example, if you have an element called login being a textfield, you can use %login% in the template, where the login element's row will be displayed.
Furthermore in most cases
- you don't want to show the original element: this is achieved by setting
display => falsefor that element - and most likely you'll want to use some different row layout than the original: that's the
rowlayoutsetting is good for those elements
Let's see an entire example:
<?php
$config = Array(
'login' => Array(
'type' => 'inputText',
'displayname' => 'Login',
'display' => 0,
'rowlayout' => '%prefix%%element%%postfix%',
),
'password' => Array(
'type' => 'inputText',
'displayname' => 'Password',
'display' => 0,
'rowlayout' => '%prefix%%element%%postfix%',
),
'logintemplate' => Array(
'type' => 'template',
'value' => '
<table>
<tr>
<td>%login%</td>
<td>%password%</td>
</tr>
</table>
'
)
);
?>
The above configuration will display a form with two fields next to each other thanks to the table used in the template. The original elements will not be displayed above the tepmlate elements thanks to the display => false setting, and as we did not use %displayname% in the rowlayout parameters, no field labels will be shown (naturally you could still include or exclude any placeholder available in the form layout arrays). Though we did not use the displayname here, there's still one advantage of using it: when using a validation for such elements, the error message will use it to refer to input elements.
level 5 - using variables in a template engine
When you are about to build forms with complex layouts, it's handy to build the structure of the form in template engines like Smarty. Clonefish supports such templating simply by exporting the parts of the form in an array you can assign to your choice of template engine like this:
$smarty->assign( 'form', $clonefish->getVars() );
This way you'll get an array with the following indexes: fields, formopen, formclose, script, messages, messageslayout of which fields and messages are arrays of the form elements and the validation error messages (these values are described under the getVars() method).
When using this method you can make use of the rowlayout setting for any element to redefine the layout of a single element row, and also the $clonefish->layouts array which includes the default settings.
form validation for developers!
clonefish is a proven, mature form generator class that helps PHP developers to create, validate and process secure, flexible and easy-to-maintain formslearn more
