ClientConfig

Пакет ClientConfig, позволяет вам создавать ваши собственные настройки, работающие согласно синтаксиса System Settings. Настройки производятся на отдельной странице, поэтому изменять их гораздо удобнее, чем Системные настройки. Кроме этого, доступны различные типы переменных Input.

Что такое ClientConfig?

ClientConfig — компонент MODX, который позволяет создавать свои собственные группы настроек и управлять: контактами, адресами, почтой, ссылками на соцсети и т.п.

Проще говоря: это личная панель управления всем, что маркетологам/контентщикам не нужно искать в шаблонах или базе данных.

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

Зачем он нужен?

1) Чтобы не держать данные в шаблонах, чанках и TV

Это типичная ошибка: <a href="tel:+78005553535">8 (800) 555-35-35</a>

Поменять телефон → нужно искать по всему сайту.

А если 40 шаблонов? Или 300 чанкoв?

С ClientConfig: [[++phone]]

А для тех кто использует Феном, есть 2 способа:

1. Через config:
   {$_modx->config.cc_phone}
   или короче:
   {'cc_phone' | config}
2. Сохранить в переменной:
   {set $phone = 'cc_phone' | config}, а затем в любом месте вывести ее
   <a href="tel:{$phone}">{$phone}</a>.

2) Чтобы контентщики могли менять данные без разработчика

Вместо системных настроек с огромным списком и ненужными параметрами — видят только то, что относится к их задаче.

3) Чтобы держать данные по проекту в одном месте

Группы:

• Контакты
• Компания
• SEO по умолчанию
• Соцсети
• Брендинг
• Интеграции (API-ключи)
• Email-настройки

Установка

ClientConfig можно загрузить через менеджер пакетов из основного репозитория и репозитория modstore.

Также вы можете скачать транспортный пакет из репозитория MODX здесь: https://extras.modx.com/package/ClientConfig.

Сообщить об ошибках можно здесь: https://github.com/modmore/ClientConfig

При установке Клиент Конфиг спросит вас какой режим выбрать:

Global mode (по умолчанию) — 90% что нужно оставить этот режим, в нем пользователи могут управлять настройками, влияющими на весь веб-сайт .

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

Работа с ClientConfig

После активации дополнения, в разделе Пакеты появится раздел Конфигурация, перейдите в него.

Создание групп и настроек

На открывшейся странице нажмите на кнопку «Администрирование».

Переходим во вкладку Группы и создаем группу или несколько групп, например: контакты и соц. сети.

<?xml version="1.0" encoding="UTF-8"?>
<data package="clientconfig" total="1">
<cgGroup>
	<id>1</id>
	<label><![CDATA[Название группы]]></label>
	<description><![CDATA[]]></description>
	<sortorder>0</sortorder>
</cgGroup>
</data>

<?xml version="1.0" encoding="UTF-8"?>
<data package="clientconfig" total="3">
<cgGroup>
	<id>1</id>
	<label><![CDATA[Контакты]]></label>
	<description><![CDATA[Используется в формах обратной связи и на странице контакты и частично в базовых шаблонах.]]></description>
	<sortorder>0</sortorder>
</cgGroup>
<cgGroup>
	<id>2</id>
	<label><![CDATA[Социальные сети]]></label>
	<description><![CDATA[Социальные сети, которые выводятся на сайте]]></description>
	<sortorder>0</sortorder>
</cgGroup>
<cgGroup>
	<id>3</id>
	<label><![CDATA[Политика конфиденциальности]]></label>
	<description><![CDATA[Данные для страницы политика конфиденциальности]]></description>
	<sortorder>0</sortorder>
</cgGroup>
</data>

После создания групп, переходим на вкладку Настройки и добавляем настройки:

В сплывающем кошке обязательно заполняем:

• Ключ, на en без пробелов, в качестве разделителя (если он нужен) лучше указывать нижнее подчеркивание, пример: company_name.
• Название: Любое — показывается при заполнении, например: Название компании
• Тип поля: по умолчанию Текст — подходит в 90% случаев.

Так же можно заполнить при необходимости другие необязательные поля поля:

• Описание, показывается под полем при заполнении, я обычно указываю вывод поля: [[++name_polya]] или если работаем с Fenom, то {$_modx->config.phone}.
• Группа: группа, в которой должно отображаться это поле
• Настройка обязательна: если поле обязательно должно иметь значение, поставьте галочку.
• Значение по умолчанию: задайте если знаете (либо укажите любое — чтобы можно было сразу вывести в код).
• Опции: доступно только для подмножества типов полей (см. типы полей).

<?xml version="1.0" encoding="UTF-8"?>
<data package="clientconfig" total="2">
<cgSetting>
	<id>1</id>
	<key><![CDATA[logotip]]></key>
	<label><![CDATA[Логотип сайта]]></label>
	<xtype><![CDATA[modx-panel-tv-image]]></xtype>
	<description><![CDATA[[[++logotip]]
{$_modx->config.logotip}]]></description>
	<is_required></is_required>
	<sortorder>0</sortorder>
	<value><![CDATA[site/logo-default-slim.png]]></value>
	<default><![CDATA[]]></default>
	<group>2</group>
	<options><![CDATA[]]></options>
	<process_options></process_options>
	<source>0</source>
</cgSetting>
<cgSetting>
	<id>2</id>
	<key><![CDATA[phone]]></key>
	<label><![CDATA[Телефон]]></label>
	<xtype><![CDATA[textfield]]></xtype>
	<description><![CDATA[[[++phone]]
{$_modx->config.phone}]]></description>
	<is_required></is_required>
	<sortorder>1</sortorder>
	<value><![CDATA[8 800 777 5555]]></value>
	<default><![CDATA[]]></default>
	<group>1</group>
	<options><![CDATA[]]></options>
	<process_options></process_options>
	<source>0</source>
</cgSetting>
</data>

Заполнение настроек

Выйдете из режима администрирования нажав на кнопку «Показать клиенту», и заполните поля данными (если не задали их значения по умолчанию при их создании) и сохраните.

Вывод настроек на сайте

После создания настроек и их можно вызвать в код вот так: [[++name_key]] / {$_modx->config.phone}.

Также настройки доступны через API: $modx->getOption('name_key') , что позволяет переопределять системные настройки.

Дополнительно

ClientConfig перезаписывает System Settings с теми же именами. Это позволяет легко заменить или изменить существующие Системные настройки.

Проверка на пустоту

Если разрабатываете сайт и не знаете будет ли клиент добавлять конкретные настройки или нет (к примеру кнопки на группы в соц. сетях), по можно выводить их вот таким конструкциями:

[[++name_key:!empty=`[[++name_key]`]] 
Fenom: {if $_modx->config.phone}{$_modx->config.phone}{/if}

Как изящно выводить соцсети (или любые параметры) без нагромождений

Часто в шаблонах большое количество соц сетей, пример:

<ul class="social">
     <li>
          <a href="https://www.instagram.com/" target="_blank" title="Instagram">
               <i class="fab fa-instagram"></i>
          </a>
     </li>
     <li>
           <a href="https://www.x.com/" target="_blank" title="X">
                <i class="fab fa-x"></i>
           </a>
     </li>
     <li>
           <a href="https://www.facebook.com/" target="_blank" title="Facebook">
                <i class="fab fa-facebook-f"></i>
           </a>
     </li>
...
</ul>

Да мы их конечно можем каждую проверить на пустоту и вывести, но так мы получаем большое количество условий, по этому кто работает с Феном, можно сделать все это более изящно.

Пример, если соцсети лежат как отдельные настройки:

cc_vk
cc_tg
cc_yt
cc_fb
cc_whatsapp
...


Тогда используем список ключей → foreach → config внутри цикла.

{set $keys = [
'cc_vk',
'cc_tg',
'cc_yt',
'cc_fb',
'cc_whatsapp',
'cc_ok',
'cc_inst',
'cc_twitter'
]}
<ul class="social">
{foreach $keys as $key}
{set $url = $key | config}
{if $url}
<li><a href="{$url}">{$key|replace:'cc_':''|upper}</a></li>
{/if}
{/foreach}
</ul>


Преимущества:

• вывод всегда одинаковый;
• если соцсеть пустая → просто не отображается;
• можно иметь хоть 30 соцсетей без нагромождений.

Да можно вообще поступить иначе: не создавать десяток настроек для отдельных соц, сетей? а просто создать 1 конфиг с Json массивом — об этом рассказано в практическом уроке.

Best Practices (профессиональные советы)

Создавай настройки с префиксом: cc_твойпроект_.

Например:

cc_finance_phone
cc_finance_email
cc_finance_address

Группируй по тематике:

• Контакты;
• SEO;
• Компания;
• API;
• Соцсети;
• Настройки магазина.

Не используй System Settings вместо ClientConfig, так как там слишком много шума и риск ошибиться.

Всегда давай понятные labels, контентщики должны понимать без тебя.

Импорт и экспорт

Один из самых мощных, но недооценённых инструментов ClientConfig — это импорт и экспорт настроек.

Что можно импортировать/экспортировать?

• вкладки (группы настроек)
• поля внутри вкладок
• их порядок
• типы полей
• значения по умолчанию

Зачем это нужно разработчику?

Работать в IDE, а не в админке

Если не хочешь «тыкать» форму настроек в панели MODX:

1. Просто создаёшь xml-файл, описываешь вкладки и поля
2. Импортируешь в ClientConfig
3. Готово.

Переносить настройки на другой сайт

Если ты делаешь несколько похожих проектов (например, сайты недвижимости, стоматологии, продаж услуг…):

1. Настраиваешь ClientConfig на одном проекте;
2. Делаешь экспорт;
3. Импортируешь на новом сайте;
4. За 10 секунд получаешь всю структуру настроек.

Использовать ClientConfig как «шаблонную сборку»

Когда создаёшь коммерческую сборку темы/сайта, где:

• контакты;
• соцсети;
• адреса;
• SEO-настройки;
• логотипы;
• API ключи.

Кэш-контроль

Пока ClientConfig Settings действуют под видом MODX System Settings, они имеют разный кэш. В отличии от System Settings, для обновления обрабатываемых настроек может появиться необходимость для очистки Resource Cache. По этой причине Client Config оснащен “умным кэшем”. По умолчанию, ClientConfig автоматически очищает нужную ячейку кэша при обновлении настроек. Отключение этой возможности есть в системных настройках.

Заключение

ClientConfig — это лучший способ организовать конфигурацию сайта, чтобы:

• не лазить в шаблоны;
• не искать данные по коду;
• давать контентщикам удобную панель управления;
• централизовать все настройки проекта;
• ускорять разработку и поддержку;
• автоматизировать SEO-настройки.

С ним любой MODX-проект становится структурированным и управляемым.