Локатор точек сети на Яндекс.Картах для MODX Revolution 3.

На странице: карта с маркерами, список, поиск по адресу, «Моё местоположение», бейджи «Открыто» / «Закрыто». Плюс REST API v1 для headless, CSV в CMP и карта самовывоза на карточке MiniShop3. Одна точка = один опубликованный ресурс с TV.

Зависимость при установке.

Сначала поставьте пакет YandexMapsLocator, затем Pro. Без базового пакета Pro не установится.

Кому подойдёт: сеть магазинов, ПВЗ или филиалов на MODX 3, где нужна витрина на карте, headless API, массовый импорт точек или самовывоз по товару в MiniShop3.

Назначение

• карта Яндекса со списком точек (на телефоне — табы «Список» / «Карта»);
• поиск по адресу, геолокация, сортировка по расстоянию, маршрут в Навигатор;
• фильтр «только открытые», бейджи по расписанию;
• REST для SPA на другом origin (CORS, Bearer);
• CSV import/export в менеджере;
• на карточке товара MiniShop3 — только точки, где товар доступен.

Как это работает

1. Установите YandexMapsLocator, затем YandexMapsLocatorPro.
2. Создаёте контейнер и дочерние ресурсы-точки, заполняете TV адреса и координат.
3. В форме ресурса можно нажать кнопку геокода (нужен API-ключ Яндекса).
4. На странице вызываете сниппет YandexMapsLocator с parents = ID контейнера.
5. Чанки на Fenom (pdoTools) отдают HTML. При включённом api_enabled UI ходит в REST api.php, иначе в search.php.

Возможности

1. Локатор. Сниппет YandexMapsLocator: форма, список, карта. Параметры parents, limit, radius, sortby, category, filters, context, return, productId.
2. Режимы вывода. chunks (HTML), data (плейсхолдеры), json для своего шаблона на том же origin. Headless с другого хоста — через REST.
3. Геолокация и поиск. «Моё местоположение», HTTP Геокодер Яндекса, радиус и сортировка по distance.
4. Карточка и балун. Адрес, телефон, часы, маршрут, balloon image, custom marker icon, бейджи открытости.
5. TV и геокод в mgr. Набор TV ставится с базовым пакетом. Имена задаёте через yandexmapslocator_tv_*. Для MiniShop3 на точке — ms3_product_id.
6. UI. Mobile-first, BEM yml-*, атрибуты data-yml-*, CSS-переменные на .yml-locator.
7. Multi-context. Параметр context, настройки default_context и allowed_contexts.
8. REST API v1. api.php?route=api/v1/locations (список, деталь, geostrong). CORS, Bearer (api_token), whitelist fields/include, kill switch api_enabled. Pro API.
9. «Открыто сейчас». Фильтр working_now, поля is_open_now / working_hours_schedule, бейджи, кнопка «Только открытые». Таймзона: yandexmapslocator_timezone (IANA). В TV часов для фильтра нужен JSON. открыто сейчас.
10. CSV в CMP. Компоненты → YandexMapsLocator Pro: импорт и экспорт по ID контейнера. Менеджер Pro.
11. MiniShop3. TV ms3_product_id + productId и фильтр minishop_product. MiniShop3.

Пустой api_token на стенде открывает REST без токена. На production задайте Bearer. Если api_enabled выключен, REST отвечает 503, локатор на странице остаётся на search.php.

Пример вызова

{'!YandexMapsLocator' | snippet : [
    'parents' => 123,
    'radius' => 50,
    'sortby' => 'distance'
]}

Ближайшие от координат

{'!YandexMapsLocator' | snippet : [
    'parents' => 42,
    'latitude' => 55.03,
    'longitude' => 82.92,
    'radius' => 30,
    'sortby' => 'distance',
    'limit' => 20
]}

Фильтр по категории

{'!YandexMapsLocator' | snippet : [
    'parents' => 42,
    'category' => 'аптека',
    'filters' => 'category'
]}

JSON для своего фронта (same-origin)

{'!YandexMapsLocator' | snippet : [
    'parents' => 42,
    'return' => 'json'
]}

Для SPA на другом origin используйте REST api.php?route=api/v1/locations, не return=json.

Только открытые сейчас

{'!YandexMapsLocator' | snippet : [
    'parents' => 42,
    'filters' => 'working_now'
]}

Задайте yandexmapslocator_timezone (IANA). Для фильтра в TV часов нужен JSON. Текст без JSON показывается в карточке, но «открыто» для него не считается.

Точки с товаром (MiniShop3)

{'!YandexMapsLocator' | snippet : [
    'parents' => $storesParent,
    'productId' => $_modx->resource.id,
    'filters' => 'minishop_product'
]}

TV по умолчанию

Ставятся при установке базового пакета YandexMapsLocator. Имена можно сменить через yandexmapslocator_tv_*.

• yandexmaps_address — адрес точки (поиск, балун, карточка). По нему же работает кнопка геокода в mgr.
• yandexmaps_latitude / yandexmaps_longitude — координаты маркера и сортировки по distance.
• yandexmaps_phone — телефон в карточке и балуне (ссылка tel:).
• yandexmaps_email — email точки (Store / REST при запросе поля).
• yandexmaps_working_hours — часы: текст для показа или JSON для фильтра «открыто сейчас» и бейджей.
• yandexmaps_category — категория. Фильтр: filters=category + параметр category.
• yandexmaps_balloon_image — картинка в балуне (fallback: default_balloon_image).
• yandexmaps_marker_icon — своя иконка маркера. Размер: yandexmapslocator_marker_icon_size.
• ms3_product_id — ID товара MiniShop3 на точке (для productId).

Установка

1. Установите YandexMapsLocator, затем YandexMapsLocatorPro. См. быстрый старт.
2. Укажите yandexmapslocator_api_key (JS API и HTTP Геокодер в кабинете Яндекса). Список ключей: настройки.
3. Создайте контейнер и дочерние точки, заполните TV.
4. Вызовите сниппет на странице (нужен pdoTools). Параметры: сниппет YandexMapsLocator.

Требования:

• MODX Revolution 3.x,
• PHP 8.2+,
• MySQL/MariaDB,
• пакет YandexMapsLocator ≥1.0.0
• pdoTools
• ключ Яндекс.Карт.