Developer Area/Core Subsystems/Form API (Pieforms)/Form APIForm Array

http://old.eduforge.org/wiki/wiki/mahara/wiki?pagename=FormAPIElements http://mahara.eduforge.org/api/ http://old.eduforge.org/wiki/wiki/mahara/wiki?pagename=FormAPIElements The biggest part about creating a form is describing it using the $form array. This array can tend to get quite large when many elements are involved, so here is a breakdown of its format.

Form metadata

The $form array must contain a "name" index, and should also contain some other indexes to define the overall behaviour of the form. These are as follows:

• name: Must be specified, and must be a string such that a PHP function with it's name could be called. The value "form" is not allowed as this conflicts with the form API itself (this limitation may be removed in future, but you should really be giving your forms a better name). This name is used to call the validation/submission functions, so choose it appropriately.
• method: Optionally defines the method that the form will be posted as. It defaults to "get" (as normal HTML forms do), and you can set it to "post". An invalid value here will default to 'get'.
• action: Optionally defines the page where the form will be submitted to. It's important to note that the submitting page should also call the "form" function with the same form definition! Most of the time you can leave this blank or not set it at all, since that will submit it to the same page.
• tabindex: Optionally defines an explicit tabindex for all of the form elements. If this is not specified, the first form on the page will have tabindex 1, and the second 2 etc.
• iscancellable: Optionally defines whether the form is able to be cancelled or not. Generally you would never set this option, unless your form happened to be like the Mahara login form, which passes on form data from other forms, and so must not cancel if the passed data included a "cancel" message.
• validate: Optionally defines whether the form should be validated or not. Forms that are not validated are not submitted. This is useful if you just want to draw a form and not validate it. This defaults to true.
• submit: Optionally defines whether the form should be submitted or not. Use in combination with the 'validate' flag to make a form that is validated but does not actually handle a submit. Defaults to true.
• renderer: Optionally defines a different renderer for the form. Valid values are 'div' and 'table', with 'table' being the default. Using the table renderer puts form elements in a standard HTML table, with the title in the left column, the element in the right, and the description and errors below both of them. The div renderer will do a similar layout, but using
  s which you can float around the place.
• autofocus: Either true or an element name, this specifies which element will get the keyboard focus on page load. If this is set to anything other than false, then when errors occur the form field with the first error will be focussed. This defaults to false (although for the Mahara project later it will default to true).

The "elements" index

This section is the largest part of the $form array. It specifies what elements are on the form, and in what order they appear.

The section is an array of arrays, each one describing a form element. Form elements roughly correspond to HTML form elements, but they are not necessarily the same. For example, while there are "text", "select" and "radio" elements, there are also "fieldset" elements (which can contain other elements), "wysiwyg" elements (which are textareas with special javascript to turn them into WYSIWYG boxes), and later there may also be others such as "checkboxgroup", "autocomplete" and more.

The element types are pluggable, and can be found in lib/form/elements/*.php. They are documented on the FormAPIElements page.

Here is an example element:

'name' => array(
            'type' => 'text',
            'title' => 'my title',
            'description' => 'my description',
            'help' => 'help text'
        ),


This describes a standard

element. The title will be rendered next to the element, the description in a smaller font below it, and the help text will display in a box that pops up when a question mark to the right of the element is hovered over.

The following list is that of all of the allowed indexes in this array.

• type: The type of element. Types are installed in lib/form/elements/*.php. There are types for most of the standard form widgets, and also extra types for customised versions. This is not required, however if the type is not specified then "markup" is assumed, which will simply insert whatever is in the "value" index straight into the form. More on the allowed types is below.
• title: The title that will be displayed to the left of the element. This is not required, and defaults to the empty string, however most of the time you will want to specify this.
• description: The description that will be displayed on the page for the element (i.e., it will always be visible, unlike the "help" index). This is optional, and should be a short sentence describing how you expect the element to be filled out.
• help: The help text that will be displayed when a user hovers over the small question mark that appears next to the form element. This is optional, and can be more verbose than the description.
• rules: The rules that are to apply to the element. This is an optional array of rulename => ruledata. The default is for no rules to apply. More on rules is below.
• value: The value that the element will always have, even if the form is submitted and the field is changed. Sometimes useful for some elements, but very useful for 'submit' and 'cancel' buttons.
• defaultvalue: The value that the element will have if the form has not been submitted.

The following options are passed directly as attributes to the form widget (for most basic form widgets, and in theory for other more complicated ones where they apply):

• accesskey
• class
• dir
• id
• lang
• name
• size
• style
• tabindex

If you have a rule for maximum length of a field, it will automatically be set.

You can also pass 'disabled' => true and 'readonly' => true, which will set the disabled/readonly attributes respectively.

Element types

The canonical list of element types is in the source code. Please consult the form-element package in the File:Http.pngAPI documentation for the list. However, most of them are documented on the FormAPIElements page.

• text: A simple text line input
• password: A password input field
• select: A drop down box. Supports multiselect and 'size'
• checkbox: A simple checkbox
• radio: A list of radio items
• submit: A submit button
• cancel: A cancel button. Rendered as a submit button, but on submit no validation is performed and a different submission callback function is called.
• submitcancel: Combines the above two on one line
• textarea: A simple textarea
• wysiwyg: A WYSIWYG textarea
• hidden: A hidden element
• file: A file upload field

In addition, there are two special types:

• markup: For raw HTML. Use sparingly, and think whether you could create a re-usable form element first.
• fieldset: Fieldsets contain other elements, by specifying an 'elements' index for them too. You cannot nest fieldsets (you can't do this in the HTML spec anyway).

Rule types

The following rule types are supported:

• required: if set to true, the field must contain a value on submission. The field is not trimmed before this check is performed at this time, as support for filters will be added that will allow you to do this.
• minlength: if set to a number, the field must have at least this many characters.
• maxlength: if set to a number, the field must have at most this many characters.
• email: if set to true, the field must match a valid e-mail address.

More rules can be added by adding them to form/rules, and you are encouraged to add rules that may see more than a passing usage.