SVRegions

SVRegions определяет регион по текущему домену или поддомену и выводит связанные с ним данные через плейсхолдеры MODX.

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

Например:

text

example.ru
spb.example.ru
kazan.example.ru
samara.example.ru

При открытии spb.example.ru компонент выбирает запись Санкт-Петербурга, а при открытии kazan.example.ru — запись Казани.

Для добавления нового региона не требуется создавать отдельный контекст или копировать ресурсы сайта. Достаточно направить поддомен на текущую установку MODX и добавить региональную запись.

Также поддерживаются отдельные домены, если они обслуживаются той же установкой MODX из одного корневого каталога.

Возможности

определение региона по текущему домену или поддомену;
одна установка MODX для основного сайта и региональных доменов;
общие ресурсы, шаблоны и чанки;
добавление нового региона одной записью;
централизованное управление региональными данными;
включение и выключение регионов непосредственно в таблице;
наследование пустых значений от основного региона;
поддержка поддоменов третьего уровня и отдельных доменов;
отсутствие зависимости от GeoIP;
экспериментальные импорт и экспорт CSV через MIGX.

Требования

MODX Revolution 2.6.0–2.8.x;
MIGX 2.13.0 или новее;
PHP и MySQL, совместимые с установленной версией MODX.

Важно.
MODX Revolution 3 текущей версией не поддерживается, поскольку компонент использует MIGX/MIGXdb для ветки MODX 2.

Установка

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

Обычная установка коммерческой версии выполняется из репозитория Modstore через менеджер пакетов MODX.

Убедитесь, что поставщик Modstore добавлен в менеджер пакетов MODX и доступен.
Найдите SVRegions в репозитории Modstore и загрузите пакет.
Установите MIGX, если менеджер пакетов предложит это сделать.
Запустите установку SVRegions.
Укажите основной домен без протокола и пути.
После установки очистите кэш MODX.

При чистой установке демонстрационная запись основного региона создаётся только в том случае, если запись для указанного домена ещё отсутствует.

Демонстрационная запись содержит пример данных Москвы и ВДНХ. Перед публикацией сайта замените город, адрес, телефоны, карту, отзывы и остальные значения своими.

Настройка доменов

SVRegions не создаёт домены и поддомены и не настраивает DNS, веб-сервер или SSL-сертификаты.

До настройки компонента необходимо:

создать домен или поддомен;
направить его DNS-запись на сервер сайта;
добавить домен в конфигурацию хостинга или веб-сервера;
направить его на корневой каталог текущей установки MODX;
выпустить и подключить SSL-сертификат;
проверить, что домен открывает тот же сайт MODX.

Все региональные домены должны обслуживаться одной установкой MODX из одного корневого каталога.

В записи региона указывается точное имя домена без:

http:// или https://;
пути;
порта;
завершающего слеша.

Правильно:

text

spb.example.ru

Неправильно:

text

https://spb.example.ru/
spb.example.ru/catalog/
spb.example.ru:443

Основной домен

Основной домен задаётся при установке компонента.

Позднее его можно изменить в свойстве defaultHost плагина SVRegions. В качестве резервного значения используется системная настройка svregions.default_host.

Значение указывается без протокола, пути, порта и завершающего слеша:

text

example.ru

Запись основного региона должна быть включена.

Основной регион используется:

для основного домена;
если включённая запись текущего домена не найдена;
если запись текущего домена выключена;
как источник значений для пустых полей других регионов.

Как определяется регион

При обработке запроса SVRegions получает текущее имя хоста из HTTP_HOST.

Затем компонент:

ищет включённую запись с соответствующим доменом;
загружает запись основного региона;
заполняет пустые поля текущего региона значениями основного региона;
устанавливает плейсхолдеры MODX с префиксом region.

Компонент использует только записи, у которых:

text

published = 1
deleted = 0

Если запись текущего домена отсутствует или выключена, используются данные основного региона.

Управление регионами

После установки в главном меню MODX появляется раздел «Регионы», реализованный на MIGX/MIGXdb.

Список регионов в SVRegions

В разделе можно:

добавлять и редактировать региональные записи;
изменять домены и региональные данные;
включать и временно выключать регионы;
физически удалять ненужные записи.

Включение и выключение

Состояние региона можно изменить непосредственно в таблице кликом по значку в колонке «Активен»:

зелёная галочка означает, что регион включён;
красный крестик означает, что регион выключен.

Для каждой записи также доступно контекстное меню:

«Редактировать»;
«Опубликовать»;
«Снять с публикации»;
«Удалить».

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

Если запись текущего домена выключена, SVRegions использует данные основного региона.

Удаление записи

Действие «Удалить» физически удаляет региональную запись из базы данных.

Важно.
Физически удалённую запись нельзя восстановить средствами SVRegions. Перед удалением важных данных создайте резервную копию.

Поля региона

Стандартная конфигурация содержит следующие поля:

Форма редактирования региона

Поле	Назначение
Домен	Точный домен или поддомен региона
Город	Название города
Предложный падеж	Форма для выражений «в Москве», «в Казани»
Родительный падеж	Форма для выражений «из Москвы», «для Казани»
Почтовый индекс	Индекс регионального офиса
Адрес	Адрес офиса или представительства
Основной телефон	Телефон в отображаемом формате
Ссылка основного телефона	Номер для атрибута `tel:`
Дополнительный телефон	Второй телефон в отображаемом формате
Ссылка дополнительного телефона	Второй номер для атрибута `tel:`
Ссылка на Яндекс Карты	URL карточки организации или точки на карте
Код карты Яндекса	HTML-код встроенной карты
Виджет отзывов Яндекса	HTML-код виджета отзывов
Активен	Управляет полем `published`

Наследование значений

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

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

город;
адрес;
почтовый индекс;
карту;
отзывы;

но оставить пустыми телефоны. В этом случае телефоны будут взяты из записи основного региона.

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

Плейсхолдеры

После определения региона компонент устанавливает следующие плейсхолдеры:

Данные	Плейсхолдер
Домен	`[[+region.domain]]`
Город	`[[+region.city]]`
Предложный падеж	`[[+region.locative]]`
Родительный падеж	`[[+region.genitive]]`
Почтовый индекс	`[[+region.index]]`
Адрес	`[[+region.address]]`
Основной телефон	`[[+region.phone]]`
Телефон для ссылки `tel:`	`[[+region.phone_link]]`
Дополнительный телефон	`[[+region.phone_2]]`
Дополнительный телефон для ссылки `tel:`	`[[+region.phone_2_link]]`
Ссылка на Яндекс Карты	`[[+region.yandex_link]]`
Код карты Яндекса	`[[+region.yandex_map]]`
Виджет отзывов Яндекса	`[[+region.yandex_review]]`
Идентификатор записи	`[[+region.id]]`
Дата создания	`[[+region.createdon]]`
Дата изменения	`[[+region.editedon]]`

Служебные поля published и deleted в плейсхолдеры не выводятся.

Использование плейсхолдеров

Плейсхолдеры размещаются в обычных шаблонах и чанках MODX.

Пример:

html

<h1>Контакты в [[+region.locative]]</h1>

<p>
  [[+region.index]], [[+region.address]]
</p>

<p>
  <a href="tel:[[+region.phone_link]]">
    [[+region.phone]]
  </a>
</p>

Один и тот же шаблон на spb.example.ru выводит данные Санкт-Петербурга, а на kazan.example.ru — данные Казани.

Структура страницы и основной контент остаются общими. Меняются только региональные значения.

Пример основного региона

Пример вывода данных основного региона

Пример регионального домена

Пример вывода данных регионального домена

Демонстрационный чанк

В комплект входит чанк SVRegionExample с готовыми примерами использования региональных плейсхолдеров.

Его можно:

временно подключить к тестовой странице;
использовать как справочник;
скопировать и адаптировать под собственную вёрстку.

Сам чанк не подключается к страницам автоматически.

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

SVRegions поддерживает базовый импорт и экспорт региональных записей через MIGX.

Функция имеет экспериментальный статус.

Перед импортом:

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

Важно.
Импорт может изменять существующие региональные записи. Не запускайте его на рабочем сайте без резервной копии.

Кэширование

SVRegions устанавливает плейсхолдеры при обработке запроса.

Если после изменения региональных данных на сайте продолжают отображаться старые значения:

очистите кэш MODX;
очистите кэш шаблонизатора или стороннего компонента, если он используется;
очистите серверный кэш или CDN;
проверьте страницу в режиме инкогнито.

При использовании полного кэширования HTML необходимо учитывать домен в ключе кэша. Иначе один домен может получить сохранённую страницу с данными другого региона.

Отличие от контекстов

SVRegions не заменяет контексты MODX и мультиязычные компоненты.

Контексты и мультиязычные решения нужны, когда различаются:

структура сайта;
дерево ресурсов;
шаблоны;
языковые версии;
права доступа;
настройки отдельных разделов.

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

Ограничения

SVRegions:

не создаёт домены и поддомены;
не настраивает DNS;
не изменяет конфигурацию веб-сервера;
не выпускает SSL-сертификаты;
не определяет местоположение посетителя по IP;
не переключает город автоматически;
не создаёт отдельные страницы для регионов;
не заменяет SEO-настройку региональных доменов.

Деинсталляция

При штатной деинсталляции удаляются:

плагин SVRegions и его связи с событиями;
чанк SVRegionExample;
пункт меню;
MIGX-конфигурация;
системные настройки;
пространство имён компонента;
файлы компонента;
категория SVRegions, если после удаления элементов она пуста.

Таблица регионов и созданные региональные записи сохраняются.

После повторной установки компонента сохранённые данные снова становятся доступны.

Для полного удаления данных таблицу SVRegions необходимо удалить отдельно после создания резервной копии.

Совместимость

MODX Revolution 2.6.0–2.8.x;
MIGX 2.13.0 или новее;
MODX Revolution 3 не поддерживается;
разработка и основное тестирование выполнялись на MODX Revolution 2.8.8.

Автор

Александр Палочкин

handyShop

Утилиты

Настройки

Утилиты

События

Backend API