mxDadata
Подсказки DaData и валидация адреса для MiniShop3 в MODX 3
Интеграция и сценарии
Поведение плагина, валидация заказа, кэш, лимиты и отладка. Плейсхолдеры и сценарии сопровождения — Для разработчиков.
Схемы потоков данных
Подсказки с витрины (без валидации Clean на стороне заказа — только Suggest/Party-эндпоинты, разрешённые в connector-web.php):
Оформление заказа (сервер: Clean, нормализация адреса, проверка FIAS/индекса при включённых опциях):
Кратко текстом, если диаграммы не отображаются: витрина — запросы из JS/сниппета в connector-web.php, затем ограничение частоты, кэш в mxdadata_cache, при промахе — HTTP к Suggest/Party. Заказ — плагин на msOnBeforeCreateOrder / msOnSubmitOrder вызывает OrderValidator и сервисы Clean/Party, а при успехе AddressMapper обновляет поля адреса.
Плагин mxDadata
| Событие | Назначение |
|---|---|
| OnWebPageInit | Плейсхолдеры веб-контекста (коннектор, флаги отладки) для шаблонов |
| msOnBeforeCreateOrder | Валидация и нормализация до создания заказа |
| msOnSubmitOrder | Та же цепочка на отправку заказа |
Если mxdadata_enabled = «Нет» или в настройках нет пары Token/Secret, обработка заказа по API DaData не выполняется (плагин выходит досрочно).
Валидация и нормализация
Класс OrderValidator использует Clean (телефон, email, адрес) и при необходимости Party, карту полей AddressMapper.
- При
mxdadata_block_order_on_error= «Да» и ошибках валидации в output события передаётся сообщение — заказ не создаётся - Сообщения для обязательного FIAS / индекса — из лексикона (
mxdadata_fias_required,mxdadata_index_requiredи т.д.) - Успешная нормализация обновляет объект
Addressзаказа перед сохранением
Кэш и rate limit
- Ответы кэшируются в
mxdadata_cacheс TTLmxdadata_cache_ttl - RateLimiter ограничивает частоту по
mxdadata_throttle_rpm
Логи
Записи в mxdadata_log. Просмотр и ротация — в админке. Уровень: mxdadata_log_level.
Отладка на витрине
- Системная настройка
mxdadata_debug_mode= «Да» - Параметр в URL:
?mxdadata_debug=1 - В консоли:
localStorage.setItem('mxdadata_web_debug', '1')(снять —removeItem)
Включён расширенный вывод в консоль при инициализации address-suggest.js / party-suggest.js / dadata-form.js.
Событие для других скриптов
После обновления адреса по подсказке (и связанного order/set) диспатчится mxdadata:order-address-updated на document. Его обрабатывает, в частности, msRussianPost для пересчёта тарифов.
Универсальная форма mxDadataForm
Сниппет mxDadataForm читает JSON: ключи — id или name полей внутри контейнера selector. Типы полей (type):
| Тип | Назначение |
|---|---|
| ADDRESS | Подсказка адреса. В subject задают соответствие полям ответа DaData. Поддерживаются bounds, from_bound, to_bound, locations, restrict_value, params, count, связь master с «главным» полем |
| NAME, EMAIL, BANK, PARTY | Подсказки по имени, почте, банку, организации (через connector-web.php) |
| GEOLOCATE | В конфиге элемент — кнопка. В объекте: latInput, lonInput (id/name полей широты/долготы), fillTarget (куда подставить выбранный адрес), опционально radius_meters, count |
| VERSION_INFO | Элемент с id (например div/pre) — в него выводится ответ Tools/Version (версия API DaData) |
Допустимые action в connector-web.php для веб-части: Suggest/Address, Suggest/Party, Suggest/Name, Suggest/Email, Suggest/Bank, Party/FindById, Geolocate/Address, Tools/Version (см. коннектор в пакете). Сложные схемы с вложенным subject и несколькими полями удобно задавать через suggestionsChunk с чанком, содержащим только JSON.