Form Decorator

Form Decorator (MWF 1.3)

Basic Usage

Creating a short form.

echo Site_Decorator::form('action' => 'save.php')
    ->set_padded()
    ->set_title('Form Title')
    ->add_submit('Save')
    ->render();

set_padded() sets the form to be padded. set_title() sets the text for the form title. add_submit() adds a primary submit button.

Form elements

Input Types

add_input($input_decorator) adds an input form element.

$input_decorator is, predictably, an Input Site Decorator. A simple text Input Site Decorator can be created like this:

Site_Decorator::input('text-1', 'Name');

The first parameter is the id for the resulting element. The second parameter is the label. Attributes for the resulting HTML element can be specified as an array passed as an optional third parameter.

The default input type is a text field, but you can specify other input types using the type_* methods.

Site_Decorator::input('textarea-20', 'Textarea')
    ->type_textarea();

Site_Decorator::input('checkbox-10', 'Checkbox')
    ->type_checkbox()

Site_Decorator::input('color-10', 'Color')
    ->type_color();

Site_Decorator::input('search-10', 'Search')
    ->type_search();

Site_Decorator::input('tel-10', 'Telephone')
    ->type_telephone();

Site_Decorator::input('url-10', 'URL')
    ->type_url();

Site_Decorator::input('email-10', 'Email')
    ->type_email();

Some useful methods to apply to Input Site Decorators include:

• required() marks input field as required
• disable() disables the input field
• set_placeholder($placeholder_text) puts placeholder text in the input field
• invalid($error_text) highlights the input and label field as an error field with error text displayed

Checkbox Groups and Radio Groups

Input groups (specifically, radio groups and checkbox groups) are handled like this:

echo Site_Decorator::form()
    ->add_checkbox_group('checkbox-group-1', 'Label for Checkbox Group', array(
        Site_Decorator::input('checkbox-1', 'One')->set_param('value', 1),
        Site_Decorator::input('checkbox-2', 'Two')->set_param('value', 2),
        Site_Decorator::input('checkbox-3', 'Three')->set_param('value', 3)
            )
    )
    ->add_radio_group('radio-group-1', 'Label for Radio Group', array(
        Site_Decorator::input('radio-1', 'One')->set_param('value', 1),
        Site_Decorator::input('radio-2', 'Two')->set_param('value', 2),
        Site_Decorator::input('radio-3', 'Three')->set_param('value', 3)
            )
    )
    ->render();

Select

Select (dropdowns and lists) can be generated like this:

$select_input = Site_Decorator::input('select-group-1', 'Label for Select')
    ->add_option('', 'Select...')
    ->add_option(1, 'One')
    ->add_option(2, 'Two')
    ->add_option(3, 'Three');

$select_input_multiple = Site_Decorator::input('select-group-2', 'Label for Multiple Select')
    ->multiple()
    ->add_option('hustle', 'The Hustle')
    ->add_option('mashedp', 'Mashed Potato')
    ->add_option('twist', 'The Twist')
    ->add_option('bunnyhop', 'Bunny Hop');

$select_input_sized = Site_Decorator::input('select-group-3', 'Label for Sized Select')
    ->set_size(5)
    ->add_option(1, 'Planet of the Apes')
    ->add_option(2, 'Beneath the Planet of the Apes')
    ->add_option(3, 'Escape from the Planet of the Apes')
    ->add_option(4, 'Conquest of the Planet of the Apes')
    ->add_option(5, 'Battle for the Planet of the Apes')
    ->add_option(6, 'Planet of the Apes (Tim Burton Reboot)')
    ->add_option(7, 'Rise of the Planet of the Apes');

echo Site_Decorator::form()
    ->set_padded()
    ->set_title('Select Form')
    ->add_input($select_input)
    ->add_input($select_input_multiple)
    ->add_input($select_input_sized)
    ->render();

multiple() can be used to make it possible to enter more than one item. This is often a better choice than a checkbox group. For one thing, using multiple() and required() on a select input is the only way, without resorting to JavaScript, to make an input that allows a user to choose as many items as they want but requiring that they choose at least one.

Number and Range

HTML5 input types number and range are similar to select/option. The method APIs are:

add_number($id, $label, $min, $max, $params)
add_range($id, $label, $min, $max, $params)

Optional parameters include:

• 'tooltip' => 'This is some help text' puts help text next to the label element
• 'disabled' => true marks the input field as disabled
• 'step' = 2 intervals between min and max (this case it's 2)
• 'selected' => 4 the default selected value (this case it's 4)
• 'invalid => 'Error text here' highlights the input and label field as an error field with error text displayed

Date/Time Input

Adds date/time input fields.

Date

add_date($id, $label, $min, $max, $params) adds three select inputs with month, day and year. $min, $max and $selected valid format is YYYY-MM-DD such as 2012-12-31.

Optional parameters include:

• 'tooltip' => 'This is some help text' puts help text next to the label element
• 'disabled' => true marks the input field as disabled
• 'selected' => '2012-12-31' the default selected date
• 'invalid => 'Error text here' highlights the input and label field as an error field with error text displayed

Month

add_month($id, $label, $min, $max, $params) adds two select inputs with month and year. $min, $max and $selected valid format is YYYY-MM such as 2012-12`.

Optional parameters include:

• 'tooltip' => 'This is some help text' puts help text next to the label element
• 'disabled' => true marks the input field as disabled
• 'selected' => '2012-12' the default selected month
• 'invalid => 'Error text here' highlights the input and label field as an error field with error text displayed

Week

add_week($id, $label, $min, $max, $params) adds two select inputs with week and year. $min, $max and $selected valid format is YYYY-WWW such as 2012-W15.

Optional parameters include:

• 'tooltip' => 'This is some help text' puts help text next to the label element
• 'disabled' => true marks the input field as disabled
• 'selected' => '2012-W15' the default selected week
• 'invalid => 'Error text here' highlights the input and label field as an error field with error text displayed

Datetime Local

add_datetime_local($id, $label, $min, $max, $params) adds six select inputs with month, day, year, hour, minute and second. $min, $max and $selected valid format is YYYY-MM-DD HH:MM:SS such as 2012-12-31 23:59:59.

Optional parameters include:

• 'tooltip' => 'This is some help text' puts help text next to the label element
• 'disabled' => true marks the input field as disabled
• 'selected' => '2012-12-31 23:59:59' the default selected datetime
• 'invalid => 'Error text here' highlights the input and label field as an error field with error text displayed

Time

add_time($id, $label, $min, $max, $params) adds three select inputs with hour, minute and seconds. $min, $max and $selected valid format is HH:MM:SS such as 23:59:59.

Optional parameters include:

• 'tooltip' => 'This is some help text' puts help text next to the label element
• 'disabled' => true marks the input field as disabled
• 'selected' => '23:59:59' the default selected time
• 'invalid => 'Error text here' highlights the input and label field as an error field with error text displayed

Button

Adds a submit or link button to the form. $value is the text label for the button.

add_submit($value, $params)
add_primary_button($value, $params)
add_secondary_button($value, $params)
add_button($value, $params)
add_primary_link_button($value, $params)
add_secondary_link_button($value, $params)
add_link_button($value, $params)

Subtitle

Adds a subtitle to the form.

add_subtitle($text)

Paragraph

Adds a paragraph to the form

add_paragraph($text)