Локатор точек на Яндекс.Картах для MODX Revolution 3. На сайте: карта, список, поиск по адресу, «Моё местоположение», бейджи «Открыто» / «Закрыто». Для интеграций: REST API v1 (в том числе /meta), CSV в CMP, карта самовывоза на карточке MiniShop3. Одна точка = один опубликованный ресурс с TV.

Зависимость при установке. Сначала поставьте пакет YandexMapsLocator (≥1.0.0-pl7 <2.0.0), затем Pro. Без базового пакета Pro не установится.

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

Назначение

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

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

1. Установите YandexMapsLocator, затем YandexMapsLocatorPro.
2. Создаёте контейнер и дочерние ресурсы-точки, заполняете TV адреса и координат.
3. На вкладке TV: «Получить координаты» под адресом, «Проверить расписание» под часами (для геокода нужен 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. На мобильном после locate открывается вкладка «Карта».
4. Карточка и балун. Адрес, телефон, часы, маршрут, balloon image, custom marker icon, бейджи открытости. Хуки JS: balloon:build, marker:options, store:click. Балун не обрезает кнопку маршрута (balloonMaxWidth 360).
5. TV и helpers в mgr. Базовые TV ставит Free. Имена задаёте через yandexmapslocator_tv_*. «Получить координаты» под адресом, «Проверить расписание» под часами. Для MiniShop3 на точке: ms3_product_ids (или legacy ms3_product_id).
6. UI. Mobile layout, BEM yml-*, атрибуты data-yml-*, CSS-переменные на .yml-locator, empty state (tplEmpty).
7. Multi-context. Параметр context / ctx, настройки default_context и allowed_contexts.
8. Extension API. Pro подключает capability pro к Extension API Free (фильтры, поля API, feature providers).
9. REST API v1. api.php?route=api/v1/locations (список, деталь, geocode) и ?route=api/v1/meta (capabilities, fields, filters, endpoints). CORS, Bearer (api_token), rate limits, whitelist fields/include, kill switch api_enabled. URL через query route= (PATH_INFO на многих хостингах даёт HTML 404). Pro API.
10. «Открыто сейчас». Фильтр working_now, поля is_open_now, status_hint, closes_at, next_open_at, working_hours_schedule, бейджи, кнопка «Только открытые» (фильтр сохраняется при поиске и locate). TZ на точке: TV yandexmaps_timezone. Иначе сеть yandexmapslocator_timezone (IANA). В TV часов для фильтра нужен JSON. открыто сейчас.
11. Фильтры amenity / brand. TV yandexmaps_amenities, yandexmaps_brand. Параметры amenity / amenities и brand в сниппете, search.php и REST (можно без явного filters=).
12. CSV в CMP. Компоненты → YandexMapsLocator Pro: импорт и экспорт по ID контейнера (14 колонок: id, pagetitle, address, lat/lng, phone, email, category, working_hours, timezone, ms3_product_id(s), amenities, brand), bulk geocode точек без координат, опция geocode при импорте если latitude/longitude пустые. Экспорт в контексте default_context (не mgr), UTF-8 с BOM. Импорт: base64 и ремонт double-UTF-8. Менеджер Pro.
13. MiniShop3. TV ms3_product_ids (несколько ID через запятую или JSON) или legacy ms3_product_id + параметр productId / product_id. Явный filters=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'
]}

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

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

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

Фильтр по удобствам и бренду
Точки с Wi‑Fi и оплатой картой у бренда «Омск» (параметры amenity / brand, без обязательного filters=):

{'!YandexMapsLocator' | snippet : [
    'parents' => 42,
    'amenity' => 'wifi,card',
    'brand' => 'Омск'
]}

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

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

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

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

Для SPA на другом origin используйте REST api.php?route=api/v1/locations, не return=json. Режим return=data кладёт точки в плейсхолдеры yandexmapslocator.stores / count без своего JSON-ответа.

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

Базовые TV ставит пакет YandexMapsLocator. Имена можно сменить через yandexmapslocator_tv_*. Pro добавляет timezone, amenities, brand, ms3 product ids.

• 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.
• yandexmaps_timezone: IANA-таймзона точки (Pro).
• yandexmaps_amenities / yandexmaps_brand: удобства и бренд (Pro).
• ms3_product_ids: ID товаров через запятую или JSON (Pro). Legacy: ms3_product_id.

Скриншоты

















Установка

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-pl7 <2.0.0, pdoTools, ключ Яндекс.Карт.