Module parameters

Parameters are settings the administrator sets in the panel for each module instance: a text, a number of items, switches. The code stays the same, while two mod_hello modules in different positions can look different.

Where they are described

Setting fields are described in the module manifest, in the config section. Open modules/mod_hello/mod_hello.xml and add the section before the closing extension tag:

<config>
    <fields name="params">
        <fieldset name="basic">
            <field name="greeting" type="text" label="Greeting text" default="Hello!" />
        </fieldset>
    </fields>
</config>

There is no need to reinstall the module: Joomla reads this section every time the module form opens. Open Content → Site Modules → Greeting — the Module tab now has a "Greeting text" field.

Reading a parameter

The settings arrive in the dispatcher as the $data['params'] object. A value is read with get():

// modules/mod_hello/src/Dispatcher/Dispatcher.php
protected function getLayoutData(): array
{
    $data = parent::getLayoutData();
 
    $data['greeting'] = $data['params']->get('greeting', 'Hello!');
 
    return $data;
}

The first argument is the field name, the second is the value used when the parameter has not been saved yet. Type "Welcome" in the panel, save the module and reload the site — the text in the block changes.

Several fields

Let us add the number of articles and a date switch:

<fieldset name="basic">
    <field name="greeting" type="text" label="Greeting text" default="Hello!" />
 
    <field name="count" type="number" label="Number of articles" default="5" min="1" max="20" />
 
    <field name="show_date" type="radio" label="Show date" default="1"
           layout="joomla.form.field.radio.switcher">
        <option value="0">JNO</option>
        <option value="1">JYES</option>
    </field>
</fieldset>

JNO and JYES are ready-made translation keys for "No" and "Yes". The layout attribute turns a pair of radio buttons into a switch.

// modules/mod_hello/src/Dispatcher/Dispatcher.php
$params = $data['params'];
 
$data['greeting'] = $params->get('greeting', 'Hello!');
$data['today'] = $params->get('show_date', 1) ? date('Y-m-d') : null;
$data['articles'] = $this->getHelperFactory()
    ->getHelper('HelloHelper')
    ->getArticles((int) $params->get('count', 5));

In the layout the date is printed with a check:

<!-- modules/mod_hello/tmpl/default.php -->
<?php if ($today) : ?>
    <small><?php echo $today; ?></small>
<?php endif; ?>

Now the number of articles and the date are controlled from the panel.

Common field types

Tabs

Each fieldset is a separate group of fields. The name basic goes to the first tab, advanced to the Advanced tab. Service fields usually go there: layout choice, a CSS class, caching.

Common mistake

The field group must be named exactly params: fields name="params". With another name the fields show up in the form, but the values are not saved into the module settings, and $params->get() always returns the default.