HelperForm fields

HelperForm builds a back office form from a describing array. In the previous lesson the form had one text field. This lesson covers the other field types and how to check the input.

Describing a field

Every field is an array inside the input key in the renderForm() method of the main class:

// modules/acmehello/acmehello.php
[
    'type' => 'text',
    'label' => $this->trans('Greeting text', [], 'Modules.Acmehello.Admin'),
    'name' => 'ACMEHELLO_GREETING',
    'desc' => $this->trans('Shown on the home page.', [], 'Modules.Acmehello.Admin'),
    'required' => true,
],

Key	What it sets
`type`	The field type
`label`	The caption on the left
`name`	The field name in the request and the key in `fields_value`
`desc`	The hint under the field
`required`	An asterisk next to the caption. The check itself is written by you

A switch

A yes/no field for the "show the greeting" setting:

[
    'type' => 'switch',
    'label' => $this->trans('Show the greeting', [], 'Modules.Acmehello.Admin'),
    'name' => 'ACMEHELLO_ENABLED',
    'is_bool' => true,
    'values' => [
        ['id' => 'enabled_on', 'value' => 1, 'label' => $this->trans('Yes', [], 'Admin.Global')],
        ['id' => 'enabled_off', 'value' => 0, 'label' => $this->trans('No', [], 'Admin.Global')],
    ],
],

Add the array to input — a switch appears in the form. values always has two options with unique id values.

A select

How many reviews to show on the product page:

[
    'type' => 'select',
    'label' => $this->trans('Reviews on the product page', [], 'Modules.Acmehello.Admin'),
    'name' => 'ACMEHELLO_LIMIT',
    'options' => [
        'query' => [
            ['id' => 3, 'name' => '3'],
            ['id' => 5, 'name' => '5'],
            ['id' => 10, 'name' => '10'],
        ],
        'id' => 'id',
        'name' => 'name',
    ],
],

query is the list of options, while id and name say which keys hold the value and the caption.

Field types

`type`	Field
`text`	A single line
`textarea`	Multi-line text
`switch`	A yes/no switch
`select`	A drop-down list
`checkbox`, `radio`	Checkboxes and radio buttons
`color`	A colour picker
`file`	A file upload
`hidden`	A hidden field

Field values

Every field must have a value in fields_value, otherwise the back office shows a warning:

$helper->fields_value = [
    'ACMEHELLO_GREETING' => Tools::getValue('ACMEHELLO_GREETING', Configuration::get('ACMEHELLO_GREETING')),
    'ACMEHELLO_ENABLED' => (int) Configuration::get('ACMEHELLO_ENABLED'),
    'ACMEHELLO_LIMIT' => (int) Configuration::get('ACMEHELLO_LIMIT'),
];

The second argument of Tools::getValue() is the value used when the field is not in the request. This way, after an error the field keeps what the person typed rather than the old value from the database.

Saving the new fields

In getContent(), after the greeting check, add:

Configuration::updateValue('ACMEHELLO_ENABLED', (int) Tools::getValue('ACMEHELLO_ENABLED'));
Configuration::updateValue('ACMEHELLO_LIMIT', (int) Tools::getValue('ACMEHELLO_LIMIT'));

Write the defaults for the new keys in install() and delete them in uninstall(). Now the setting can be used — for example, return an empty string from hookDisplayHome() when ACMEHELLO_ENABLED is zero.

Checking values

The Validate class holds ready checks. Each returns true or false.

Method	What it checks
`isUnsignedInt()`	An integer from zero up
`isEmail()`	An email address
`isUrl()`	A site address
`isGenericName()`	A string without the characters `<>={}`
`isCleanHtml()`	HTML without scripts
`isPrice()`	A price

$limit = Tools::getValue('ACMEHELLO_LIMIT');
 
if (!Validate::isUnsignedInt($limit) || (int) $limit > 50) {
    $output .= $this->displayError($this->trans('Wrong number of reviews.', [], 'Modules.Acmehello.Admin'));
}

With a wrong number an error is shown above the form and the value is not saved.

Common mistake

A field is added to input but forgotten in fields_value. In debug mode the settings page shows a warning about an undefined key, and the field stays empty even after saving. Every name from the form description must have a key in fields_value.

Thanks for reading!