Forms

Forms are displayed using the tag.

The recommended way to call them is within the tag:

[compose
  components.body="product_info wishlist_add"
  forms.wishlist_add.name="wishlist_add"
]

In this example product_info refers to an existing component, while wishlist_add can be seen as virtual component which will be replace by the form specified in the second parameter of .

	Note
	Forms without matching virtual component will be ignored.

Form parts

Each form consists of one or multiple subforms, called parts. The parts are stored in the table form_series with the following fields:

name: Form name
part: Part name
label: Label displayed on top of the form (optional)
template: Template (optional)
profile: Profile to check input in this part (optional)
position: Position of part (1,2,3,...)

As example we are looking at the checkout form, with the following parts:

Shipping
Payment
Confirmation
Receipt

These are the corresponding entries in form_series:

mysql> select name,part,label,profile,position from form_series where name = 'checkout' order by position;
+----------+--------------+--------------+----------+----------+
| name     | part         | label        | profile  | position |
+----------+--------------+--------------+----------+----------+
| checkout | shipping     | Shipping     | shipping |        1 | 
| checkout | payment      | Payment      |          |        2 | 
| checkout | confirmation | Confirmation |          |        3 | 
| checkout | receipt      | Receipt      |          |        4 | 
+----------+--------------+--------------+----------+----------+

Form templates

Forms too are built from templates. The default template is located in templates/form. Alternative templates can be specified through form_series field as shown above.

The default template is:

{PREPEND}
{TOP}
<fieldset>
<legend>{TITLE}</legend>
{FIELDS}
{SUBMIT}
</fieldset>
{BOTTOM}

Explanations:

{PREPEND}: placeholder for form components
{TOP}: starts HTML form
{TITLE}: shows the label field from the form_series table
{FIELDS}: contains the regular form elements
{SUBMIT} contains the button form elements (as specified in form_elements table or default submit button)
{BOTTOM} ends the HTML form.

Form elements

The elements of a form (part) are stored in the form_elements table with the following fields:

code: Unique serial number
name: Name of form element
label: Label for form element
component: Part name
priority: Sort order (descending)
widget: Widget to display

The widget is passed by the form_element_field theme function to the [display] tag. Exceptions to that are explained below.

Special Form Widgets

A form element with the widget named "legend" just displays the label of the form_element. This is useful if you want to separate your form into separate visual parts.

Form elements with the widget named "button" are used to produce submit buttons. This is useful if you want to have multiple buttons in your form without changing your form template, like Preview or Delete.

Form attributes

Every form element can have a set of attributes, stored in the form_attributes table. They are working pretty much the same as the metadata table for the Interchange UI.

Attributes can be applied for every form element with a certain name or only for a certain form:

wellwell=> select * from form_attributes where name = 'country';
 code |  name   | component |  attribute   |                           value                            
------+---------+-----------+--------------+------------------------------------------------------------
   32 | country |           | lookup_query | SELECT code,name FROM country ORDER BY priority DESC, name



wellwell=> select * from form_attributes where component = 'content_edit';
 code | name |  component   | attribute | value 
------+------+--------------+-----------+-------
   30 | uri  | content_edit | width     | 200
   31 | body | content_edit | height    | 400

The form load hook can also be used to provide form atttributes:

Sub form_address_edit_load <<EOS
sub {
	my %attributes;

	# load shipping address
	$Tag->address({function => 'load',
				type => 'shipping'});

	# setup dropdown for country
	$attributes{country}->{lookup_query} = q{SELECT code,name FROM country ORDER BY priority DESC, name};

	return {attributes => \%attributes};
}
EOS

Form hooks

There are two hooks for forms: form_NAME_load (e.g. form_checkout_load) and form_NAME_save (e.g. form_checkout_save)

The first parameter for both hook subs is the part name.

Load hook

The load hook is called for the setup of a form part. It is not called if the profile check for the form part has failed. The return value of the load hook is either a false value or a hash reference where the following members are recognized:

page — loads the specified page through the $CGI->{mv_nextpage} mechanism
attributes — hash reference providing defaults for form attributes

Save hook

The save hook is called if the form part has been successfully submitted (e.g. profile check successful). The return value of the load hook is either a false value or a hash reference where the following members are recognized:

page — loads the specified page through the $CGI->{mv_nextpage} mechanism
redirect — redirects to the specified page if true

Form theming

Most aspects of a form can be 'themed': the title, elements (complete, label and field) and the submit button.

Currently, you can modify one of the existing theme functions:

theme_form_title
theme_form_element
theme_form_element_label
theme_form_element_field
theme_form_submit

Form components

Regular components can also included in forms. Examples are dynamic form parts and supplementary content.

They are stored in form_components table with the following fields:

name: Form name
part: Form part (empty if component applies to all parts of the form)
component: Component name
location: Placeholder used to place the component, e.g prepend for {PREPEND} placeholder
priority: Sort order in placeholder (descending)


Users, Roles and Permissions		Plugins