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
Setting addon/theme version compatibility in the marketplace
Jan 9, 2024

For developers worn out with setting the latest addon or theme version manually across too many core versions, here is a JavaScript bookmarklet to do it for you.

How to get the locale of a page
Jan 8, 2024
By mandako.

Now, why don't we just have a getLocale() method on Page objects beats me, but here's how you work around it

Using a Redis Server
Jun 16, 2023
By mlocati.

How to configure Concrete to use one or more Redis servers to persist the cache.

Using the Concrete Migration Tool Addon
Apr 27, 2023

How to use the Concrete CMS Migration Tool

How To Add Page Last Updated To Your Concrete CMS Pages
Mar 7, 2023

Concrete CMS has a page attribute you can add to a global area called "Page Date Modified." Here's how to add it

How To Exclude Subpages from Navigation
Dec 24, 2022

How to exclude subpages from navigation - useful for a news or blog link in your main navigation where you don't want all the subpages to appear in a drop down menu.

Improvements?

Let us know by posting here.