How to use the form widget in Concrete CMS 5.7

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
Updating Concrete Themes from Version 8 to Version 9
Nov 24, 2022

This tutorial covers commonly encountered issues when upgrading a Concrete CMS theme from version 8 to version 9

Transferring ownership of an add-on and a theme
Nov 15, 2022
By katzueno.

If you encounter a Concrete CMS add-on or theme that you love but not being maintained, you may want to ask the author to help or take over the add-on or theme. Here is the quick step-by-step guide of how to transfer the ownership.

How to update Add-Ons if not on the Update Add-Ons Menu item
Jul 4, 2022

How to manually download an add-on and update it when your site's core versions isn't considered compatible with the add-on version.

Generate a report with author information and form summaries in Concrete CMS.
May 9, 2022

In Concrete CMS, you can use a form to initiate contact between logged-in users and then create helpful reports. After form submissions are collected, they can be searched, sorted, and exported as a spreadsheet. This tutorial will detail how to add author information to a report using the advanced search.

How to clone and customize Atomik theme
Feb 14, 2022
By linuxoid.

How to clone and customize Atomik theme

Update jQuery to 3.5 on Concrete CMS version 8.5.x
Dec 1, 2021
By hissy.

If you have to take some time to fix your site to work with version 9 and want to update jQuery immediately, you can override it.

Was this information useful?
Thank you for your feedback.