Модуль Nova Poshta Popular Cities для OkayCMS

Дозволяє додавати та відображати популярні міста на сторінці оформлення замовлення.
Це спрощує процес вибору міста доставки для користувачів, дозволяючи швидко вибрати місто одним кліком.

Можливості

• Управління списком популярних міст Нової Пошти в адмін-панелі.
• Зміна порядку відображення в адмін-панелі.
• Швидкий вибір міста одним кліком для користувачів.
• Визначення міста за IP адресою клієнта — автоматичне визначення міста користувача за його IP адресою та додавання його до списку популярних міст для швидкого вибору.

Вимоги

• OkayCMS v4.5.2
• Модуль OkayCMS\NovaposhtaCost

Встановлення

Варіант 1: Скачування з GitHub

1. Скачайте останню версію модуля з останнього релізу на GitHub.
2. Розпакуйте архів на сервері в каталог: {OkayCMS_root}/Okay/Modules/

Варіант 2: Встановлення через Git

1. Виконайте команду в директорії {OkayCMS_root}/Okay/Modules/Sviat:

   git clone https://github.com/devSviat/NovaPoshtaPopularCities-OkayCMS.git NovaPoshtaPopularCities

Результат встановлення

Шлях до модуля має бути таким:

{OkayCMS_root}/Okay/Modules/Sviat/NovaPoshtaPopularCities/

Використання

Адмін-панель

1. Перейдіть в розділ "Nova Poshta Popular Cities" в адмін-панелі
2. Введіть назву міста в поле пошуку та виберіть місто зі списку автодоповнення
3. Натисніть кнопку "Додати" для додавання міста до списку

Оновлення бази міст через API Нової Пошти

Для коректної роботи модуля, особливо функції визначення міста за IP, необхідно оновити базу міст:

1. У розділі "Налаштування" натисніть кнопку "Оновити міста з API"
2. Модуль автоматично завантажить всі доступні міста та населені пункти через API Нової Пошти
3. Дані зберігаються в базу даних модуля з полями:
   • Назва міста (українською)
   • Транслітерація назви міста (для визначення за IP)
   • Референс міста в системі Нової Пошти
4. Рекомендується періодично оновлювати базу міст для отримання актуальної інформації

Важливо: Без оновленої бази міст функція визначення міста за IP адресою не працюватиме коректно, оскільки модуль шукає місто в базі за транслітерацією назви.

Налаштування визначення міста за IP

Модуль підтримує автоматичне визначення міста користувача за його IP адресою:

1. Спочатку оновіть базу міст через кнопку "Оновити міста з API" (див. вище)
2. У розділі "Налаштування" увімкніть опцію "Визначати місто за IP адресою клієнта"
3. Після увімкнення модуль автоматично:
   • Визначає IP адресу клієнта
   • Визначає місто за IP через зовнішні API (ip-api.com, ipinfo.io)
   • Шукає відповідне місто в базі (завантаженій через API Нової Пошти)
   • Якщо визначене місто вже є в списку популярних міст (додано вручну в адмін-панелі), то воно автоматично переміщується на першу позицію у списку
   • Якщо визначене місто відсутнє в списку популярних міст, воно додається до списку та відображається першим
   • Зберігає визначене місто в localStorage браузера для швидшого завантаження при наступних відвідуваннях

Примітка: Визначення міста за IP працює тільки для реальних IP адрес. Локальні адреси (127.0.0.1, ::1) ігноруються.

Фронтенд

Модуль додає блок з популярними містами на сторінку оформлення замовлення в розділі вибору доставки Нової Пошти. Користувачі можуть швидко вибрати популярне місто, натиснувши на відповідну кнопку.

Якщо увімкнено визначення міста за IP:

• Модуль автоматично визначає місто користувача за його IP адресою
• Якщо визначене місто вже є в списку популярних міст (додано вручну в адмін-панелі), воно автоматично переміщується на першу позицію у списку
• Якщо визначене місто відсутнє в списку популярних міст, воно додається до списку та відображається першим
• При натисканні на визначене місто воно автоматично вибирається як місто доставки
• Визначене місто зберігається в браузері для швидшого завантаження при наступних відвідуваннях

Ліцензія

Модуль розповсюджується за вільною ліцензією MIT