RSS Мои друзья Контакты

Magento конфигурация от А до Я: system.xml

В Magento существует очень много настроек. Все они находятся в System -> Configuration. Любой модуль может добавить туда специфические параметры. Новые поля, группы и табы - все это делается при помощи конфигурационного файла system.xml.

Структура файла

Все system.xml конфигурационные файлы состоят из нескольких основных частей: табы -> секции -> группы -> поля. В пользовательском интерфейсе это все расположено как-то так

Magento configuration structure

Все настройки в Magento могут иметь одну из трех областей действия (scope): default, website, store. Настройка заданная в скоупе store переопределяет значения заданные в default и website. Аналогично параметр заданный в скоупе website переопределяет значение по умолчанию, т.е. скоуп default. В начале это может показаться очень сложным, но окажется очень юзабильным, когда у Вас под управлением одной Magento находится несколько сайтов. Область видимости (скоуп) можно переключать при помощи выпадающего списка в верхнем левом углу на странице конфигурации.

Конфигурационный файл выглядит так

<config>
    <tabs>............</tabs>
    <sections>........</sections>
</config>

Чтобы создать таб достаточно просто задать ему имя и порядок сортировки. Например, открыв Mage_Core модуль можно увидеть

<config>
    <tabs>
        <general translate="label" module="core">
            <label>General</label>
            <sort_order>100</sort_order>
        </general>
        <service translate="label" module="core">
            <label>Services</label>
            <sort_order>99999</sort_order>
        </service>
        <advanced translate="label" module="core">
            <label>Advanced</label>
            <sort_order>999999</sort_order>
        </advanced>
    </tabs>
............................................................
</config>

В этом файле определено 3 таба. При создании таба основным его параметром является код - имя тега. Он понадобится в дальнейшем, чтобы указать секции к какому табу она принадлежит. Например в том же файле

<sections>
    <advanced translate="label" module="core">
        <label>Advanced</label>
        <tab>advanced</tab>
<sort_order>910</sort_order> <show_in_default>1</show_in_default> <show_in_website>1</show_in_website> <show_in_store>1</show_in_store> <groups>.......</groups> </advanced> </sections>

можно определить по тегу tab, что секция Advanced относится к табу Advanced. Секция определяется следующими тегами:

  • label - название секции
  • tab - таб к которому она относится (необязательный)
  • class - задает css класс для ссылки секции, как пример секция PayPal-а (необязательный)
  • header_css - задает css класс для тега h3, на странице редактирования секции. В качестве примера - тот же PayPal (необязательный)
  • sort_order - порядковый номер
  • groups - группы, которые относятся к этой секции
  • show_in_default - показывать в дефолтном скоупе
  • show_in_website - показывать в скоупе вебсайта
  • show_in_store - показывать в скоупе стора

Атрибут translate указывает (через пробел), содержимое каких тегов является мультиязычным. Атрибут module указывает, какой модуль ответственный за данную секцию, в основном используется, чтобы создать объект хелпера этого модуля.

Секция содержит в себе группы, например в advanced

<modules_disable_output translate="label">
    <label>Disable Modules Output</label>
    <frontend_model>adminhtml/system_config_form_fieldset_modules_disableOutput</frontend_model>
    <sort_order>2</sort_order>
    <show_in_default>1</show_in_default>
    <show_in_website>1</show_in_website>
    <show_in_store>1</show_in_store>
</modules_disable_output>

Эта группа отвечает за отключение вывода блоков определенного модуля. Посмотрим на ее UI

Magento disable module output

Обычно в группе задаются поля, но также можно указать frontend_model. Она отвечает за вывод всех полей и должна реализовать интерфейс Varien_Data_Form_Element_Renderer_Interface. В контексте Magento - это на самом деле блок, а не модель.

Группа задается следующими тегами

  • label - название группы
  • sort_order - порядковый номер
  • frontend_model - блок, отвечающий за вывод группы (необязательный)
  • expanded - указывает открыта ли группа по умолчанию
  • comment - комментарий к группе
  • fields - структура полей
  • show_in_default - показывать в дефолтном скоупе
  • show_in_website - показывать в скоупе вебсайта
  • show_in_store - показывать в скоупе стора

Если посмотреть в секцию design, то увидим, что ее группы имеют тег fields, в котором задаются параметры для полей. Например, группа package

<package translate="label">
    <label>Package</label>
    <sort_order>1</sort_order>
    <show_in_default>1</show_in_default>
    <show_in_website>1</show_in_website>
    <show_in_store>1</show_in_store>
    <fields>.........</fields>
</package>

Для задания поля нужно указать следующие теги

  • label - название поля
  • sort_order - порядковый номер
  • frontend_model - блок, отвечающий за вывод поля (необязательный)
  • frontend_type - тип поля (необязательный, по умолчанию text)
  • backend_model - модель отвечающая за валидацию поля на сервере, должна быть объектом класса Mage_Core_Model_Config_Data. Ей передаются определенные данные: path, value, website_code, store_code. Должна реализовать метод _beforeSave (вызывается перед сохранением поля). Также можно реализовать методы afterLoad или getValue, которые вызываются перед тем как отобразить поле. Это нужно, если например в базе поле сохранено как сериализированный массив, т.е. строка, а для его отображения нужно, чтобы оно было массивом (необязательный)
  • comment - комментарий под полем (необязательный)
  • sort_fields - указывает как сортировать поля (необязательный, по умолчанию сортирует по sort_order)
    • by - имя тега по-которому нужно отсортировать
    • direction_desc - указывает сортировать обратном порядке (по умолчанию сортировка А-Я)
  • config_path - указывает специфический путь для параметра, например package/name (необязательный, если не указан, то путь будет %SECION_NAME% / %GROUP_NAME% / %FIELD_NAME%, где *_NAME - имена тегов)
  • validate - задает класс полю, благодаря, которому можно будет валидировать поле на клиенте с помощью JavaScript и varienForm класса
  • source_model - задает модель-источник, используется для типов полей select и multiselect. Если модель является объектом Varien_Object, то ей устанавливается путь к полю (доступ можно получить при помощи метода getPath()). Например, группа debug из секции dev имеет поле profiler, в котором задана сорс модель adminhtml/system_config_source_yesno. По умолчанию модель должна реализовать метод toOptionArray, который возвращает массив с опциями. Если Вы хотите использовать специфический метод, то в конце имени ставите 2 раза двоеточие и потом имя метода, например adminhtml/system_config_source_yesno::myMethoName.
  • depends - указывает поля зависимые от значения данного поля. Пример можно посмотреть в секции каталог, группа Layered Navigation поле Price Navigation Step Calculation
  • tooltip - всплывающая подсказка может быть как просто текстом, так и Magento путем к блоку
  • show_in_default - показывать в дефолтном скоупе
  • show_in_website - показывать в скоупе вебсайта
  • show_in_store - показывать в скоупе стора

В большинстве случает source, backend и frontend модели писать не прийдется. Нужно просто пройтись по всем настройкам, посмотреть есть ли то что нужно, потом открыть конфигурационный файл и скопировать уже готовые директивы.

Тег frontend_type может содержать любое значение из полей формы, которые определены в lib/Varien/Data/Form/Element/ директории.

Создание своих настроек

Чтобы создать свои настройки для начала нужно написать модуль. В модуле в директории etc создаем файл system.xml. Создадим свой таб и секцию, а также добавим новое поле в секцию Каталог, группу Layered Navigation.

Так как Magento объединяет все конфиг файлы в один большой XML, то чтобы добавить новый таб нужно всего лишь написать

<config>
    <tabs>
        <my_tab>
            <label>Freaks Tab</label>
            <sort_order>100000</sort_order>
        </my_tab>
    </tabs>
    <sections>
        <my_section translate="label">
            <label>My Section</label>
            <tab>my_tab</tab>
            <frontend_type></frontend_type>
            <sort_order>910</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
            <groups>
                <test_group translate="label">
                    <label>Test Group</label>
                    <sort_order>4</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>1</show_in_website>
                    <show_in_store>1</show_in_store>
                    <fields>
                        <email translate="label">
                            <label>Sender Email</label>
                            <frontend_type>text</frontend_type>
                            <backend_model>adminhtml/system_config_backend_email_address</backend_model>
                            <validate>validate-email</validate>
                            <sort_order>2</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                        </email>
                        <name translate="label">
                            <label>Sender Name</label>
                            <frontend_type>text</frontend_type>
                            <backend_model>adminhtml/system_config_backend_email_sender</backend_model>
                            <validate>validate-emailSender</validate>
                            <sort_order>1</sort_order>
                            <show_in_default>1</show_in_default>
                            <show_in_website>1</show_in_website>
                            <show_in_store>1</show_in_store>
                        </name>
                    </fields>
                </test_group>
            </groups>
        </my_section>
    </sections>
</config>

Теперь, чтобы это заработало нужно очистить кэш, а также создать права доступа для этих параметров (ACL) иначе будете попадать на 404 страницу. В нашем случае добавим ACL только для одной секции my_section. Добавляем информацию об этом в конфиг модуля (config.xml)

<adminhtml>
    <acl>
        <resources>
            <admin>
                <children>
                    <system>
                        <children>
                            <config>
                                <children>
                                    <my_section>
                                        <title>My Section</title>
                                    </my_section>
                                </children>
                            </config>
                        </children>
                    </system>
                </children>
            </admin>
        </resources>
    </acl>
</adminhtml>

Более детально об ACL можно прочитать здесь.

Выходим из админки, чтобы сессия очистилась, заходим обратно и вот что видим

Magento own configuration

Все настройки сохраняются в базу в таблицу core_config_data. Чтобы получить доступ к настройкам используется конструкция

$config = Mage::getStoreConfig('path/to/config'[, $storeId]);

// in our situation
$email = Mage::getStoreConfig('my_section/test_group/email');
$name  = Mage::getStoreConfig('my_section/test_group/name');

Теперь добавим новое поле в уже существующую группу. На самом деле все делается по аналогии и довольно таки просто. Сначала откроем файл system.xml модуля Mage_Catalog. Найдем там группу которая отвечает за Layered Navigation, чтобы скопировать ее код. И потом добавляем новую XML структуру в тег sections

<catalog>
    <groups>
        <layered_navigation>
            <fields>
                <test_field>
                    <label>Test Field</label>
                    <frontend_type>text</frontend_type>
                    <sort_order>100</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>1</show_in_website>
                    <show_in_store>1</show_in_store>
                </test_field>
            </fields>
        </layered_navigation>
    </groups>
</catalog>

Чистим кэш и заходим через админку в секцию Каталог, группу Layered Navigation

Magento custom config field

P.S.: по ходу изучения моделей в следующих статьях мы вернемся к конфигурации и таким понятиям, как реврайты моделей и как обходится без них при помощи событий.

Добавить комментарий

Комментариев: 5

  • Дима
    Ответить 29 декабря 2011 г., 10:43
    Спасибо за труды и с наступающим =)
  • Rush
    Ответить 31 августа 2012 г., 14:36
    спасибо, помогло
  • Юлий
    Ответить 16 января 2013 г., 18:26
    миллион статей в интете о том, как добавить твои табсы в админку и нигде не написано, как пользоваться translate="label"
    неужели это настолько очевидная вещь?
    • Сергей (Администратор)
      Ответить 17 января 2013 г., 22:15
      Что значит "как пользоваться"? Опишите суть проблемы: что Вы делаете и что не получается.
      В translate атрибуте нужно указать какие теги нужно перевести (если указан label - это значит что содержимое тега label будет меняться в зависимости от локали, в том случае, если у Вас есть переводы для выбранного языка). Переводы лежат в отдельных csv файлах: либо в "app/locale", либо непосредственно в теме, либо в базе (таблица "core_translate")
  • Роман
    Ответить 25 февраля 2013 г., 18:20
    Огромное спасибо.
    <миллион статей в интете о том, как добавить твои табсы в админку...>
    Я только недавно начал изучать Magento, но нигде не нашел такого доходчигого и понятного объяснения вопроса. Так держат, очень полезная статья. Не мог нигде найти толком что и для чего system.xml. Теперь все ясно!!!