How to use the form widget in Concrete CMS 5.7

This is a community-contributed tutorial. This tutorial is over a year old and may not apply to your version of Concrete CMS.
May 6, 2015

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)
Recent Tutorials
Restoring deleted pages using advanced search
Jan 16, 2025
By myq.

How to recover deleted pages when there are more than a few to choose from.

How to Automate the Copyright Year
Dec 27, 2024

Learn how to keep your website's copyright year updated automatically in Concrete CMS.

How to change the path of a group of pages
Dec 23, 2024
By myq.

Change the canonical path without breaking things

Bi-directional Express associations
Dec 18, 2024
By myq.

Set up associations between Express entries in both directions

Display Express Data Across Multiple Sites
Dec 17, 2024
By myq.

A guide to configuring Express entities and the Express Entry List block to ensure proper data display across multiple sites.

Customize locale icons
Oct 29, 2024
By myq.

How to customize locale (language region) flags

Improvements?

Let us know by posting here.