How to use the form widget in Concrete CMS 5.7

Available input types:

button
checkbox
email (HTML5)
file
hidden
number (HTML5)
password
radio
search (HTML5)
select
select multiple
submit
telephone (HTML5)
text
textarea
url (HTML5)

An explanation and demonstration of HTML5 input types
http://html5doctor.com/html5-forms-input-types/

HTML5 input type browser support
http://caniuse.com/#feat=forms

HTML5 input types fall back to the text input type in browsers that don't support them.

Adding input attributes:

The fields/miscFields array argument of the form widget is an associative array. The associative array is made of key value pairs.
- the key is the attribute name
- the value is the attribute value

Example:

$form->text('text_example', $text_example, array('style' => 'text-align: center;', 'maxlength' => '4', 'class' => 'validation'))

attributes added:
- style="text-align: center"
- maxlength="4"
- class="validation"

Label

label( string $field, string $name, mixed $miscFields = array() )

Example:

$form->label('input_id', t('Label Text'))

Button

button( string $name, string $value, array $fields = array(), mixed $additionalClasses = '' )

Examples:

$form->button('button_example', 'Button')

-- default

$form->button('button_example', 'Button', array(), 'btn-primary')

-- the class .btn-primary is added

$form->button('button_example', 'Button', array('style' => 'width: 125px;'), 'btn-primary')

-- class .btn-primary is added
-- attribute style="width: 125px" is added

Checkbox

checkbox( string $key, string $value, string $isChecked = false, array $miscFields = array() )

Example:

$form->checkbox('checkbox_example', 1, $checkbox_example)  

The checkbox value can be a string or integer, but only the $_POST array key for "checkbox_example" is checked, not the value. If $checkbox_example is true, checked="checked" will be added to the checkbox input.

Checkbox values are set in the save() method in controller.php.

Example:

public function save($args)
{
    $args['checkbox_example'] = isset($args['checkbox_example']) ? 1 : 0;
    parent::save($args);
}

$args is the POST array.
-- if checkbox_example is set, then checkbox_example is given the value of 1
-- if checkbox_example is not set, then checkbox_example is given the value of 0
-- checkbox values are not limited to only 1 and 0, they can be set to other values

Email

email( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->email('email_example', $email_example)

File

file( string $key )

Example:

$form->file('file_example')

Hidden

hidden( string $key, string $value = null )

Example:

$form->hidden('hidden_example', $hidden_example)

Number

number( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->number('number_example', $number_example)

Password

password( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->password('password_example', $password_example)

Radio

radio( string $key, string $value, string $valueOrArray = false, mixed $miscFields = array() )

The form widget handles setting the checked attribute.

Examples:

$form->radio('radio_example', 0, $radio_example, array('id' => 'radio_example1'))
$form->label('radio_example1', t('One'))
$form->radio('radio_example', 1, $radio_example, array('id' => 'radio_example2'))
$form->label('radio_example2', t('Two'))

-- the radio button ID can be set manually

Search

search( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->search('search_example', $search_example)

Select

select( string $key, mixed $optionValues, mixed $valueOrArray = false, mixed $miscFields = array() )

The form widget handles setting the selected attribute.

Example:

$form->select('select_example', array('acorn' => t('acorn'), 'lemon' => t('lemon'), 'turnip' => t('turnip')), $select_example, array('style' => 'width: 125px;'))

-- attribute style="width: 125px" is added

Select Multiple

selectMultiple( string $key, array $optionValues, array|string $defaultValues = false, array $miscFields = array() )

The form widget handles setting the selected attribute.

Example:

$form->selectMultiple('selectmultiple_example', array('acorn' => t('acorn'), 'lemon' => t('lemon'), 'turnip' => t('turnip')), $selectmultiple_example, array('style' => 'width: 125px;'))

-- attribute style="width: 125px" is added

selectMultiple()
- the input values are saved as an array
- some information, like arrays, cannot be saved to the database as is
- one approach to saving arrays to the database is with serialize()
- serialize() generates a storable representation of the array, the array is serialized in the controller.php save() method using serialize()
- to use the array after it is read from the database, it must be unserialized and set in the controller.php edit() and view() methods using unserialize()

Example:

public function edit()
{
    $this->set('selectmultiple_example', unserialize($this->selectmultiple_example));
}

public function view()
{
    $this->set('selectmultiple_example', unserialize($this->selectmultiple_example));
}

public function save($args)
{
    $args['selectmultiple_example'] = serialize($args['selectmultiple_example']);
    parent::save($args);
}

Example: array before and after serialize()

before

array ( 0 => 'acorn', 1 => 'lemon', 2 => 'turnip' )

after

a:3:{i:0;s:5:"acorn";i:1;s:5:"lemon";i:2;s:6:"turnip";}

Submit

submit( string $name, string $value, array $fields = array(), mixed $additionalClasses = '' )

Example:

$form->submit('submit_example', $submit_example)

Telephone

telephone( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->telephone('telephone_example', $telephone_example)

Text

text( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->text('text_example', $text_example)

Text Area

textarea( string $key )

Example:

$form->textarea('textarea_example', $textarea_example, array('style' => 'height: 200px;'))

-- attribute style="height: 200px" is added
-- textarea() also accepts a $miscFields array as a second argument

URL

url( string $key, string|array $valueOrArray = false, array $miscFields = array() )

Example:

$form->url('url_example', $url_example)