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
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.

Add-On Developers: Get Your Add-Ons Ready for Concrete CMS 9.0
Aug 6, 2021
By andrew.

Concrete CMS 9.0 is coming! But there are some changes in version 9 that might affected your add-ons and themes. This document aims to answer questions about the most common ways that your add-ons might need to be changed, and common problems you'll run into.

Permissions for editors in a multilingual site
Jun 2, 2021
By myq.

How to set up a multilingual Concrete CMS site for groups of language-specific editors

Getting Started with Doctrine in Concrete CMS
Jan 20, 2021
By linuxoid.

Doctrine is a very flexible, simple (once you get to know it better) and powerful PHP library for database interactions primarily focused on the ORM = Object Relational Mapping and DBAL = DataBase Abstraction Layer.

How To Upgrade PHP Using the MultiPHP Manager In cPanel
Nov 23, 2020

This article will explain how to upgrade your PHP version using cPanel.

How To Add Google Analytics To Your Website - The easy way
Oct 9, 2020

Adding analytics to your website is an important part of running your website. There’s no need to edit your theme or install a plugin to add a tracking code to Concrete CMS you can do it right from the CMS.

Was this information useful?
Thank you for your feedback.