Документация InstantCMS

для администраторов и разработчиков

Инструменты пользователя

Инструменты сайта


dev:controllers:backend:options

Стандартная форма опций в админке

Наиболее частая функция для админки компонента – это показ и обработка формы с опциями, которые влияют на работу компонента в пользовательской части.

Для того, чтобы облегчить реализацию этой типовой задачи, класс cmsBackend от которого наследуется контроллер админки уже содержит в себе описание экшена options. Этот экшен доступен по URL: /admin/controllers/edit/{компонент}/options и делает следующее:

  • Читает форму опций из файла;
  • Выводит форму на экран;
  • После отправки формы сохраняет опции в таблицу controllers.

Значения опций, сохраненные данным экшеном, затем доступны во фронтенде компонента в виде пар название → значение.

Ниже поэтапно рассмотрим как реализовать данный механизм.

Форма опций

Первым делом необходимо создать описание формы с опциями, т.е. то, какие поля она будет содержать.

Форма располагается в файле /system/controllers/{компонент}/backend/forms/form_options.php.

Класс формы должен иметь название form{НазваниеКомпонента}Options.

Пример формы опций для компонента comments:

//system/controllers/comments/backend/forms/form_options.php
class formCommentsOptions extends cmsForm {
 
    public function init() {
 
        return array(
 
            array(
                'type' => 'fieldset',
                'childs' => array(
 
                    new fieldCheckbox('is_guests', array(
                        'title' => LANG_COMMENTS_OPT_IS_GUESTS,
                        'hint' => LANG_COMMENTS_OPT_IS_GUESTS_HINT,
                    )),
 
                    new fieldNumber('guest_ip_delay', array(
                        'title' => LANG_COMMENTS_OPT_GUESTS_DELAY,
                        'units' => LANG_MINUTE10,
                    )),
 
                    new fieldText('restricted_ips', array(
                        'title' => LANG_COMMENTS_OPT_GUESTS_RESTRICTED_IPS,
                        'hint' => LANG_COMMENTS_OPT_GUESTS_RESTRICTED_IPS_HINT,
                    )),
                )
            ),
        );
    }
}

Структура файла формы и доступные типы полей подробно рассмотрены в соответствующем разделе.

Включение экшена опций

Для того, чтобы контроллер админки (backend.php) знал, что вы хотите использовать стандартный экшен опций, необходимо добавить в описание класса строчку:

public $useDefaultOptionsAction = true;

После этого экшен станет доступен по URL: /admin/controllers/edit/{компонент}/options.

Шаблон экшена опций

Для InstantCMS выше 2.4.0

Для версий InstantCMS выше 2.4.0 прямой необходимости в создании шаблона формы опций нет. По умолчанию будет использоваться шаблон /templates/default/controllers/admin/backend/controllers_options.tpl.php.

Обратите внимание, если необходимо показать ссылку на документацию, создайте в языковом файле контроллера константу LANG_HELP_URL_COM_ИМЯ-КОНТРОЛЛЕРА, где напишите URL справочной информации. В этом случае на странице опций появится ссылка на нее.

Для InstantCMS ниже 2.16.0 предусмотрен вызов колбэк-функции при сохранении формы, куда передается массив новых значений опций контроллера. Если вам это необходимо, определите в файле backend.php следующий метод:

    public function loadCallback() {
 
        $this->callbacks = array(
            'actionoptions'=>array(
                function($controller, $options){
                    // $controller - содержит объект текущего контроллера
                    // $options - массив новых опций
                    // вы можете выполнять здесь любые необходимые действия
                }
            )
        );
 
    }

Для InstantCMS, начиная с версии 2.16.0 подобный механизм реализуется через события (трейт /system/traits/eventDispatcher.php). Для реагирования на событие сохранения формы в конструкторе бэкенда (в файле backend.php) вашего контроллера подпишитесь на событие:

public function __construct(cmsRequest $request) {
 
    parent::__construct($request);
 
    // Пример из контроллера activity
    $this->addEventListener('controller_save_options', function ($controller, $options) {
 
        $controller->model->enableTypes($options['types']);
    });
}

Если вам по каким-то причинам необходима своя форма опций, об этом ниже.

Для InstantCMS 2.4.0 и ниже

До версии 2.4.0 включительно, шаблон необходимо создавать в обязательном порядке.

Шаблон вывода опций

Если вам необходим свой шаблон формы опций – создайте файл /templates/default/controllers/{компонент}/backend/options.tpl.php как минимум со следующим содержимым:

<?php
 
    $this->addBreadcrumb(LANG_OPTIONS);
 
    $this->addToolButton([
        'class' => 'save',
        'title' => LANG_SAVE,
        'href'  => 'javascript:icms.forms.submit()'
    ]);
 
    $this->renderForm($form, $options, [
        'action' => '',
        'method' => 'post'
    ], $errors);
 

Вы можете модифицировать этот файл под собственные нужды.

Добавление экшена опций в меню админки

Если кроме опций в админке вашего компонента будут и другие разделы, то имеет смысл создать меню админки.

Для этого в контроллере админки (backend.php) добавьте метод getBackendMenu():

public function getBackendMenu(){
    return [
        // ссылка на экшен "Опции"
        [
            'title' => LANG_OPTIONS,
            'url' => href_to($this->root_url, 'options')
        ],
 
        // ... здесь добавьте ссылки на другие разделы админки ...
 
    ];
}

Переадресация на экшен опций

При переходе к настройкам компонента, админка по-умолчанию отправляет пользователя на экшен index вашего контроллера админки. Поэтому, если в вашей админке такой экшен не нужен, то вы можете из него делать автоматический редирект на другой экшен.

Пример переадресации из экшена index на экшен options (в компоненте auth):

class backendAuth extends cmsBackend{
 
    public $useDefaultOptionsAction = true;
 
    public function actionIndex(){
        $this->redirectToAction('options');
    }
 
}

Использование опций в контроллере

Для того, чтобы фронтенд и бэкенд (и их экшены) могли использовать опции, заданные в админке компонента, необходимо добавить следующее свойство в классе фронтенда (frontend.php) и в класс бэкенда (backend.php):

protected $useOptions = true;

После этого значение любой опции в любом экшене можно получить так:

$option_value = $this->options['option_name'];

Наличие значения опции можно проверить так:

if (!empty($this->options['option_name'])) { ... }

В шаблонах обратиться к опции можно так:

$this->controller->options['option_name']

Автоматические SEO параметры

Для InstantCMS выше 2.5.1

В форму опций можно включить автоматическое добавление полей с SEO параметрами для главной страницы компонента (экшен index). Для этого в файлах фронтэнда и бэкенда необходимо задать следующее свойство:

public $useSeoOptions = true;

Если в вашем контроллере админки форма опций формируется не автоматически, то в файле бэкенда ставить это свойство необязательно. Достаточно в экшене настроек компонента, после получения формы, пропустить её через специальный метод:

// получаем форму
$form = $this->getForm('options');
 
// автоматически добавляем в форму поля с SEO параметрами
$form = $this->addControllerSeoOptions($form);

Значения этих полей будут находиться в опциях контроллера:

$this->options['seo_keys']; // ключевые слова
$this->options['seo_desc']; // описание

Вернуться к разделу "Админка компонента"

dev/controllers/backend/options.txt · Последнее изменение: 12.02.2023 20:13 — fuze