Страница настроек модуля

Опубликовано Опубликовано в рубрике prestashop, Руководство разработчика PrestaShop, Русская документация PrestaShop 1.6, Создание модулей PrestaShop

Страница настроек модуля

Ваш модуль может получить ссылку «Настройка» в списке модулей бэк-офиса и, следовательно, позволить пользователю изменить некоторые настройки. Эта ссылка «Настроить» появляется с добавлением метода getContent() для вашего основного класса. Это стандартный метод PrestaShop: его единственное назначение отправить сообщение в бэк-офис, говоря: «В этом модуле есть страница конфигурации, отображающая ссылку конфигурации»,

Но имея публичный метод getContent()  в MyModule объект делает только ссылку «Настройка»; Он не создает страницу конфигурации из ниоткуда. Мы собираемся объяснить, как его создать, где мы сможем редактировать содержимое переменной MYMODULE_NAME , которую мы сохранили в таблице данных ps_configuration .

Метод getContent()

Во-первых, вот полный код для getContent() метода:

public function getContent()
{
    $output = null;
    if (Tools::isSubmit('submit'.$this->name))
    {
        $my_module_name = strval(Tools::getValue('MYMODULE_NAME'));
        if (!$my_module_name
          || empty($my_module_name)
          || !Validate::isGenericName($my_module_name))
            $output .= $this->displayError($this->l('Invalid Configuration value'));
        else
        {
            Configuration::updateValue('MYMODULE_NAME', $my_module_name);
            $output .= $this->displayConfirmation($this->l('Settings updated'));
        }
    }
    return $output.$this->displayForm();
}

getContent()Вызывается первым при загрузке страницы конфигурации. Поэтому мы используем его для первого обновления любого значения, которое могло быть отправлено формой, содержащейся на странице конфигурации.

Вот объяснение по строкам:

  1. Tools::isSubmit() Является специальным методом PrestaShop, который проверяет, была ли подтверждена указанная форма.
    В этом случае, если форма конфигурации еще не подтверждена, все if() блоки пропускаются, и PrestaShop будет использовать только последнюю строку, которая отображает конфигурацию с текущими значениями, генерируемую displayForm() методом.
  2. Tools:getValue() Является специальным методом PrestaShop, который извлекает содержимое POST  или GET  массива, чтобы получить значение указанной переменной.
    В этом случае мы получаем значение MYMODULE_NAME переменных формы превратив значения в текстовую строку, используя strval() метод и сохраняя его в $my_module_name PHP переменной.
  3. Затем мы проверяем наличие фактического содержимого в $my_module_name, включая использование Validate::isGenericName().
    ОбъектValidate содержит множество методов проверки достоверности данных, среди которых isGenericName(), метод, который поможет вам сохранить только строки, которые являются действительными именами PrestaShop — строки, которые не содержат специальных символов
  4. Если какая-либо из этих проверок завершится с ошибкой, конфигурация откроется с сообщением об ошибке, указывающим, что проверка формы не удалась.
    Переменная $output содержит окончательную версию HTML-кода, который отображает страницу конфигурации, таким образом начинающегося с сообщения об ошибке, созданного с использованием метода displayError() . Этот метод возвращает правильный HTML-код для нашей страницы, и поскольку этот код является первым в $output, это означает, что конфигурация откроется с этим сообщением.
  5. Если все эти проверки успешны, это означает, что мы можем сохранить значение в нашей базе данных.
    Как мы видели ранее в этом уроке объект Configuration имеет только метод, который нам нужен: updateValue() который  будет хранить новое значение для MYMODULE_NAME в таблице данных конфигурации.
    Для этого мы добавляем дружественное сообщение пользователю, указывая, что значение действительно было сохранено: мы используем PrestaShop’s displayConfirmation() метод для добавления этого сообщения в начале данных в переменной $output – и, следовательно, в верхней части страницы.
  6. Наконец, мы используем метод displayForm() (Которые мы собираемся создать и объяснить в следующем разделе), чтобы добавить контент в $output (Была ли форма отображена ​​или нет) и вернуть это содержимое на страницу.
    Обратите внимание, что мы могли бы включить код для displayForm() прямо внутри getContent(), но решили отделить для удобства чтения.

Этот код проверки формы не является чем-то новым для разработчиков PHP, но использует некоторые из методов PrestaShop, которые вы будете очень регулярно использовать.

Отображение формы

Сама форма конфигурации отображается с помощью displayForm() метод. Вот его код, который мы объясним позже:

public function displayForm()
{
    // Get default language
    $default_lang = (int)Configuration::get('PS_LANG_DEFAULT');
    
    // Init Fields form array
    $fields_form[0]['form'] = array(
        'legend' => array(
            'title' => $this->l('Settings'),
        ),
        'input' => array(
            array(
                'type' => 'text',
                'label' => $this->l('Configuration value'),
                'name' => 'MYMODULE_NAME',
                'size' => 20,
                'required' => true
            )
        ),
        'submit' => array(
            'title' => $this->l('Save'),
            'class' => 'btn btn-default pull-right'
        )
    );
    
    $helper = new HelperForm();
    
    // Module, token and currentIndex
    $helper->module = $this;
    $helper->name_controller = $this->name;
    $helper->token = Tools::getAdminTokenLite('AdminModules');
    $helper->currentIndex = AdminController::$currentIndex.'&configure='.$this->name;
    
    // Language
    $helper->default_form_language = $default_lang;
    $helper->allow_employee_form_lang = $default_lang;
    
    // Title and toolbar
    $helper->title = $this->displayName;
    $helper->show_toolbar = true;        // false -> remove toolbar
    $helper->toolbar_scroll = true;      // yes - > Toolbar is always visible on the top of the screen.
    $helper->submit_action = 'submit'.$this->name;
    $helper->toolbar_btn = array(
        'save' =>
        array(
            'desc' => $this->l('Save'),
            'href' => AdminController::$currentIndex.'&configure='.$this->name.'&save'.$this->name.
            '&token='.Tools::getAdminTokenLite('AdminModules'),
        ),
        'back' => array(
            'href' => AdminController::$currentIndex.'&token='.Tools::getAdminTokenLite('AdminModules'),
            'desc' => $this->l('Back to list')
        )
    );
    
    // Load current value
    $helper->fields_value['MYMODULE_NAME'] = Configuration::get('MYMODULE_NAME');
    
    return $helper->generateForm($fields_form);
}

Хотя это может показаться огромным блоком кода для изменения одного значения, этот блок фактически использует метод PrestaShop, чтобы упростить создание форм, в первую очередь HelperForm объекта.

Подробнее о displayForm()

Давайте рассмотрим этот метод:

  1. Используя метод Configuration::get(), мы извлекаем значение выбранного языка («PS_LANG_DEFAULT«). по соображениям безопасности мы передаем переменную в целое число, используя (int).
  2. При подготовке к генерации формы мы должны построить массив различных заголовков, текстовых полей и других данных формы.
    С этой целью мы создаем $fields_form переменную, которая будет содержать многомерный массив. Каждый из массивов, которые он содержит, содержит подробное описание тегов, которые должна содержать форма. Из этой переменной PrestaShop отобразит HTML-форму.
    В этом примере мы определяем три тега (<legend><input> and <submit>) и их атрибуты с использованием массивов. Формат довольно легко получить: легенда и массивы отправки просто содержат атрибуты для каждого тега, а вход содержит столько же <input> необходимых тегов, каждый из которых, в свою очередь, представляет собой массив, который содержит необходимые атрибуты. Например:

    'input' => array(
        array(
            'type' => 'text',
            'label' => $this->l('Configuration value'),
            'name' => 'MYMODULE_NAME',
            'size' => 20,
            'required' => true
        ))

    …генерирует следующие теги HTML:

    <label>Configuration value </label>
    <div class="margin-form">
      <input id="MYMODULE_NAME" class="" type="text" size="20" value="my friend" name="MYMODULE_NAME">
      <sup>*</sup>
    <div class="clear"></div>

    Как вы можете видеть, PrestaShop довольно умный и генерирует весь код, необходимый для получения формы.
    Обратите внимание, что значение основного массива фактически извлекается позже в коде генерации формы.

  3. Затем мы создаем экземпляр класса HelperForm . этот раздел кода объясняется в следующем разделе этой главы.
  4. Однажды HelperForm собрав все настройки на месте, мы генерируем форму, основанную на содержании переменной $fields_form

Использование HelperForm

HelperForm является одним из вспомогательных методов, которые были добавлены с PrestaShop 1.5, наряду с HelperOptionsHelperListHelperView и HelperHelpAccess. Они позволяют создавать стандартные элементы HTML для бэк-офиса, а также для страниц конфигурации модулей.
Вы можете получить дополнительную информацию о классах помощников в главе «Помощники» этого руководства по разработке, на странице, посвященной HelperForm.

Вот наш пример кода в качестве напоминания:

$helper = new HelperForm();
// Module, Token and currentIndex
$helper->module = $this;
$helper->name_controller = $this->name;
$helper->token = Tools::getAdminTokenLite('AdminModules');
$helper->currentIndex = AdminController::$currentIndex.'&configure='.$this->name;
// Language
$helper->default_form_language = $default_lang;
$helper->allow_employee_form_lang = $default_lang;
// title and Toolbar
$helper->title = $this->displayName;
$helper->show_toolbar = true;        // false -> remove toolbar
$helper->toolbar_scroll = true;      // yes - > Toolbar is always visible on the top of the screen.
$helper->submit_action = 'submit'.$this->name;
$helper->toolbar_btn = array(
    'save' =>
    array(
        'desc' => $this->l('Save'),
        'href' => AdminController::$currentIndex.'&configure='.$this->name.'&save'.$this->name.
        '&token='.Tools::getAdminTokenLite('AdminModules'),
    ),
    'back' => array(
        'href' => AdminController::$currentIndex.'&token='.Tools::getAdminTokenLite('AdminModules'),
        'desc' => $this->l('Back to list')
   )
);
// Load current value
$helper->fields_value['MYMODULE_NAME'] = Configuration::get('MYMODULE_NAME');
return $helper->generateForm($fields_form);

В нашем примере используется несколько атрибутов HelperForm: они должны быть установлены до того, как мы сгенерируем форму из переменной $fields_form :

  • $helper->module: Требуется экземпляр модуля, который будет использовать форму.
  • $helper->name_controller: Требуется имя модуля.
  • $helper->token: Требует уникальный токен для модуля getAdminTokenLite() Помогает его генерировать.
  • $helper->currentIndex:
  • $helper->default_form_language: Требуется язык по умолчанию для магазина.
  • $helper->allow_employee_form_lang: Требуется язык по умолчанию для магазина.
  • $helper->title: Требуется название для формы.
  • $helper->show_toolbar: Требует булевского значения — отображается ли панель инструментов или нет.
  • $helper->toolbar_scroll: Требует булевского значения — всегда ли панель инструментов отображается при прокрутке или нет.
  • $helper->submit_action: Требуется атрибут action для формы <submit> tag.
  • $helper->toolbar_btn: Требуется кнопки, которые отображаются на панели инструментов. В нашем примере нажмите кнопку «Сохранить» и кнопку «Назад».
  • $helper->fields_value[]: Здесь мы можем определить значение названного тега.

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

Вот представление формы, как она выглядит в настоящее время. Вы можете увидеть ее сами, нажав ссылку «Настроить» для модуля в бэк-офисе:

Измените значение в зависимости от того, что вам больше нравится, нажмите кнопку «Сохранить», а затем перегрузите домашнюю страницу: ваш модуль действительно обновляется новой строкой!