Параметры модуля

Параметры — настройки, которые администратор задаёт в панели для каждого экземпляра модуля: текст, количество записей, переключатели. Код остаётся одним, а два модуля mod_hello в разных позициях могут выглядеть по-разному.

Где описывают

Поля настроек описывают в манифесте модуля, в разделе config. Откройте modules/mod_hello/mod_hello.xml и добавьте раздел перед закрывающим тегом extension:

<config>
    <fields name="params">
        <fieldset name="basic">
            <field name="greeting" type="text" label="Текст приветствия" default="Привет!" />
        </fieldset>
    </fields>
</config>

Переустанавливать модуль не нужно: Joomla читает этот раздел каждый раз, когда открывается форма модуля. Откройте «Содержимое → Модули сайта → Приветствие» — на вкладке «Модуль» появилось поле «Текст приветствия».

Чтение параметра

Настройки приходят в диспетчер объектом $data['params']. Значение читают методом get():

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

Первый аргумент — имя поля, второй — значение на случай, если параметр ещё не сохранён. Введите в панели «Добро пожаловать», сохраните модуль и обновите сайт — текст в блоке изменится.

Несколько полей

Добавим количество статей и переключатель даты:

<fieldset name="basic">
    <field name="greeting" type="text" label="Текст приветствия" default="Привет!" />
 
    <field name="count" type="number" label="Сколько статей" default="5" min="1" max="20" />
 
    <field name="show_date" type="radio" label="Показывать дату" default="1"
           layout="joomla.form.field.radio.switcher">
        <option value="0">JNO</option>
        <option value="1">JYES</option>
    </field>
</fieldset>

JNO и JYES — готовые ключи перевода «Нет» и «Да». Атрибут layout превращает пару радиокнопок в переключатель.

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

В макете дату выводят с проверкой:

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

Теперь количество статей и показ даты управляются из панели.

Частые типы полей

Вкладки

Каждый fieldset — отдельная группа полей. Имя basic попадает на первую вкладку, advanced — на вкладку «Дополнительно». Туда обычно кладут служебные поля: выбор макета, класс CSS, кеширование.

Частая ошибка

Имя группы полей должно быть именно params: fields name="params". С другим именем поля покажутся в форме, но значения не сохранятся в настройки модуля, и $params->get() всегда будет возвращать значение по умолчанию.