Skip to content
This repository has been archived by the owner on Sep 14, 2022. It is now read-only.

Form Decorator

Jump to bottom
Trott edited this page Apr 6, 2012 · 13 revisions

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 can be generated like this:

$number_input = Site_Decorator::input('number-10', 'Number')
    ->type_number()
    ->required()
    ->set_param('min', 0)
    ->set_param('max', 10)
    ->set_param('step', 2)
    ->set_value(4);

$range_input = Site_Decorator::input('range-10', 'Range')
    ->type_range()
    ->set_param('min', 0)
    ->set_param('max', 100)
    ->set_param('step', 10)
    ->set_value(40);

echo Site_Decorator::form()
    ->add_input($number_input)
    ->add_input($range_input)
    ->add_input($submit)
    ->render();

Date/Time Input

$now = new DateTime('now');
$five_years_ago = new DateTime("5 years ago");
$five_years_from_now = new DateTime("5 years");
$date_input = Site_Decorator::input('date-10', 'Date')
    ->type_date()
    ->required()
    ->set_param('min', $five_years_ago->format('Y-m-d'))
    ->set_param('max', $five_years_from_now->format('Y-m-d'))
    ->set_value($now->format('Y-m-d'));
$month_input = Site_Decorator::input('month-10', 'Month')
    ->type_month()
    ->required()
    ->set_param('min', $five_years_ago->format('Y-m'))
    ->set_param('max', $five_years_from_now->format('Y-m'))
    ->set_value($now->format('Y-m'));
$week_input = Site_Decorator::input('week-10', 'Week')
    ->type_week()
    ->required()
    ->set_param('min', $five_years_ago->format('Y-\WW'))
    ->set_param('max', $five_years_from_now->format('Y-\WW'))
    ->set_value($now->format('Y-\WW'));

$datetime_local_input = Site_Decorator::input('datetime-10', 'Datetime Local')
    ->type_datetime_local()
    ->required()
    ->set_param('min', $five_years_ago->format('Y-m-d\TH:i'))
    ->set_param('max', $five_years_from_now->format('Y-m-d\TH:i'))
    ->set_value($now->format('Y-m-d\TH:i'));

$time_input = Site_Decorator::input('time-10', 'Time')
    ->type_time()
    ->required()
    ->set_param('min', $five_years_ago->format('H:i'))
    ->set_param('max', $five_years_from_now->format('H:i'))
    ->set_value($now->format('H:i'));

echo Site_Decorator::form()
    ->add_input($date_input)
    ->add_input($month_input)
    ->add_input($week_input)
    ->add_input($datetime_local_input)
    ->add_input($time_input)
    ->add_input($submit)
    ->render();

For browsers that do not implement the date, time, and datetime-local input types, you can override the default behavior of using a simple text box by including the polyfill library with add_js_handler_library():

echo Site_Decorator::head()
    ->set_title('Forms With Polyfills')
    ->add_js_handler_library('full_libs', 'formsPolyfills')
    ->render();

This will cause a calendar to appear when date or datetime-local input types are selected. For time and (and the time portion of datetime-local), buttons will allow the time to be incremented or decremented.

Button

echo Site_Decorator::form()
    ->add_input(Site_Decorator::input()->type_button()->primary()->set_param('value', 'Primary Button'))
    ->add_input(Site_Decorator::input()->type_button()->secondary()->set_param('value', 'Secondary Button'))
    ->add_input(Site_Decorator::input()->type_button()->set_param('value', 'Neutral Button'))
    ->add_link_button_primary('Primary Link', 'http://www.example.com/')
    ->add_link_button_secondary('Secondary Link', 'http://www.example.org/')
    ->add_link_button_neutral('Neutral Link', 'http://www.example.net/')
    ->add_input(Site_Decorator::input()->type_submit()->set_param('value', 'I Am The Walru...er, I mean, Submit Button')
    ->render();

Subtitle

Adds a subtitle to the form.

add_subtitle($text)

Paragraph

Adds a paragraph to the form

add_paragraph($text)
Clone this wiki locally