HTML Form Generation Methods (htmlform)

Uses properties from a DataMapper object to quickly generate forms. This method is highly customizable, both in a broad sense, and on a field-by-field basis. When combined with the Associative Array Conversion Methods, this extension can make creating simple content mangement tools very easy.

Load-Time Options

Set these when loading the extension, to change the default behavior.

Getting Started

HTML Form was designed to be highly flexible, while still allowing the simplest cases to require very little coding.

HTML Form Uses the Validation Array

HTML Form can use information already stored in the validation array to significantly automate form generation. The following elements are used as described. Some of these elements are not defined for standard DataMapper usage. All can be overridden on a per-form and per-field basis.

* Not a standard DataMapper validation field.

For the most simple forms, all that is need is:

1. Ensure that every field and related field has a label.
2. Add type to all non-single line text fields. Relationship fields will automatically be generated as a dropdown or checkbox list.
3. Create an array of field names to edit, in the order you want them to appear. Don't forget id if you are editing an item!
4. Pass this array into $object->render_form, along with the submit url if it is not the current url.
5. Echo the result of the method out.

That's all that is needed to render out a complete form with inputs for text, textareas, even single and multiple relationships! The form will also include a block of errors if any occurred while saving.

Note: If you are outputting related fields, you need to implement __toString on your related classes. The result of __toString is used to determine the name to show for dropdowns, checkboxes, and radio buttons.

Relationship fields can only be used with checkbox, radio, or dropdown input types.

Continue reading on for more details of how to enhance this output.

Methods

All of the power of this class can be accessed through these three methods.

render_form($fields, $url, $options, $template, $row_template)

• $fields: An array containing the instructions for the renderers. (Details below.)
• $url: (Optional) The url to submit the form to. Defaults to the current URL. The default template will automatically call $CI->config->site_url() on it.
• $options: (Optional) An associative array of options for the form renderer only.
• $template: (Optional) Override the default form template for just this form.
• $row_template: (Optional) Override the default row template for just this form.
• Returns: A string containing the form rendered out.

Takes a collection of fields, text, and custom inputs and converts them into a submittable form.

Default Form Template Options

The default form template can take these options. If you customize the template, you can accept any options you want.

render_row($field, $type, $options, $row_template)

• $field: The name of the field or relationship (or the id of a non-field) to render.
• $type: (Optional) The type of field to render (such as text or dropdown).
• $options: (Optional) An associative array of options for the renderer. Most will be passed directly to render_field.
• $row_template: (Optional) Override the default row template for just this row.
• Returns: A string containing the row rendered out.

Takes a field (or set of options) and converts it into an HTML form input widget, wrapped in a template containing the field label and more. This method isn't called directly very often; instead use render_form.

It is this method that determines whether to render rows with input fields, section headers, or output the content directly.

Default Row Template Options

The default row template can take these options. If you customize the template, you can accept any options you want. ($id is the id of the field.)

render_field($field, $type, $options)

• $field: The name of the field or relationship (or the id of a non-field) to render.
• $type: (Optional) The type of field to render (such as text or dropdown).
• $options: (Optional) An associative array of options for the renderer.
• Returns: The rendered html form input string.

Takes a field (or set of options) and converts it into an HTML form input widget. This function is the meat of the automation. The method outputs different information based on whether the field is a $has_one or $has_many relationship, a DataMapper field, or none of the above.

• If the field is a $has_one, the default output is a dropdown box listing every item of a given type in the database.
• For $has_many, the default output is a list of checkboxes if there are 6 or less items, or a multiple-selection dropdown box for more items.
• For fields, the default is a text, except for id which defaults to hidden.
• For all others, there is no default, you have to specify the type.

Common Input Field Options

These are common options for input fields. Anything not explicitly defined here is output directly to the html as $name="$value".

class User extends DataMapper {

    // ...

    function get_htmlform_list($object, $field)
    {
        // Only return enabled users
        $this->where('disabled', FALSE)->get();
    }
}

Types

Different types of input help shape what the user is allowed to submit. You can use one of the built-in types, or create your own type renderers.

Built-In Types

All of the built-in functions will update based on the validation rules. They also will accept almost any key/value pair in the options array, and output them as HTML.

For the examples below:

• $id: The field name ('firstname')
• $value: The current value of the field ('Bob')
• $listkey#: The key from a list of possible values.
• $listvalue#: The value from a list of possible values.

Single-Value Types

These input types only accept a single value, and the user can enter input as text.

Limited-Selection Single-Value Types

These input types only accept a single value. The options the user can select are limited by the values validation property, the list property, or auto-generated for related items.

You will need to implement the __toString PHP method on related models, to get a label for these.

Limited-Selection Multiple-Value Types

These input types accept multiple values. The options the user can select are limited by the values validation property, the list property, or auto-generated for related items.

You will need to implement the __toString PHP method on related models, to get a label for these.

Custom Types

HTML Form includes several types (listed below). You can also add any type by simply creating a helper function to render it.

The helper function must be named input_{$type}, and must take these arguments:

• $object: The DataMapper object being rendered.
• $field: The field, related field, or id to be rendered.
• $value: The current value for the field. This is updated automatically based on what was submitted.
• $options: An associative array of options for the field.

Example

// Render a JavaScript Calendar
function input_calendar($object, $field, $value, $options)
{
    return "<input type=\"text\" id=\"$field\" name=\"$field\" value=\"$value\" onFocus=\"showCalendar(this);\" onBlur=\"hideCalendar(this);\" />";
}

Then simply set the type of any object to calendar to use this input type.

Custom Templates

It is easy to customize the templates in use. A template is simply a view, and all $options are passed into it directly as variables. There are three default templates:

• The form template is expected to wrap the $rows with a form element, as well as provide the submit button.
• The row template lays out the [$label: $content] structure, where $content is one or more fields. It is called for every row.
• The section template is used specifically for labeling form sections. It usually only uses the $content attribute.

You can easily override or specify different templates in several ways:

• You can override the default templates globally by specifying them in the options.
• You can override the default form and row template when calling render_form.
• You can override a row or section template within the $fields array for render_form.
• You can override the row template when calling it manually.

Code Examples

For all examples, assume $u is a User.

Basic Form

This outputs a complete, ready-to-use HTML form including grouping the fields, and errors messages.

echo $u->render_form(array(
        'id',
        // Section header
        'Contact Information' => 'section',
        'name',
        'email',
        'phone',

        // Section header
        'Login Information' => 'section',
        'username',
        'password',
        'confirm_password',

        // Since user can only have one group, this will render out as a standard drop-down of all Groups.
        'group'
    ),
    'users/save' // form submit URL
);

Overriding the Default Type

A simple change converts the name into a multi-line textarea.

echo $u->render_form(array(
        'id',
        // Section header
        'Contact Information' => 'section',
        'name' => 'textarea',
        'email',
        'phone',

        // Section header
        'Login Information' => 'section',
        'username',
        'password',
        'confirm_password',

        'group'
    ),
    'users/save' // form submit URL
);

Customizing the Output

Changing the label, field-level styling, changing options on a dropdown, and custom button labels are shown below.

$g = new Group();
// Don't include groups that only admins can see
$g->where('admin_only', FALSE)->get();

echo $u->render_form(array(
        'id',
        // Section header
        'Contact Information' => 'section',

        // Override label and size, add custom styling
        'name' => array(
            'label' => 'Your Name',
            'size' => '40',
            'style' => 'color: Green; font-weight: bold;'
        ),
        'email',
        'phone',

        // Section header
        'Login Information' => 'section',
        'username',
        'password',
        'confirm_password',

        // We want to limit the groups visible
        'group' => array(
            'list' => $g
        )
    ),
    'users/save', // form submit URL
    // Customize the form
    array('save_button' => 'Save this form NOW', 'reset_button' => 'Clear')
);

Multi-Field Row

Use this format to place more than one field on a line.

echo $u->render_form(array(
        'id',
        // output:
        // Name: [firstname] [middlename] [lastname]
        array(
            'row_options' => array(
                'label' => 'Name' // the row's Label
            ),
            'firstname',
            'middlename',
            'lastname'
        ),
        'email',
        // ...

Previous Topic:      ·   Top of Page   ·   User Guide Home    ·   Next Topic: