Компонент Map

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Опис компонента

Компонент Map (Мапа) дозволяє використовувати картографічні дані з різних картографічних сервісів, наприклад, OpenStreetMap та інших, а також додавати власні шари та дані геопросторових об’єктів.

Використовуйте Map з переліку Оновлених компонентів.

Налаштувати компонент Map можна у Кабінеті адміністратора регламентів, у розділі UI-форми.

  1. Створіть нову форму.

  2. Перейдіть на вкладку Конструктор.

  3. Відкрийте Компоненти > Оновлені, оберіть компонент Map та перетягніть його до панелі моделювання.

    map 01

  4. У налаштуваннях компонента відкрийте вкладку Display та у полі Label вкажіть бізнес-назву поля для вашої мапи. Наприклад, Map.

    map 1

  5. Перейдіть на вкладку Data та виконайте наступні налаштування:

    • У секції Base Layers вкажіть URL-адресу картографічного сервісу, наприклад, OpenStreetMap, та додаткову інформацію про цей сервіс. Зокрема, ви вказуєте назву шару (Name), максимальний масштаб (Max Zoom), на якому будуть відображені дані, а також URL-адресу для завантаження зображень плиток (tiles) із сервера OpenStreetMap (https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png).

    • Параметри Overlay Search Field та Search Zoom використовуються для пошуку геоданих на карті. Ви можете вказати назву поля для пошуку введеного користувачем значення та масштаб, на якому будуть показані результати пошуку.

    • У секції Overlay Layers ви можете вказати свої власні шари, які будуть накладатися на базовий шар OpenStreetMap. Наприклад, ви можете використовувати дані із власної бази даних, щоб показати місця розташування певних об’єктів на карті. У цьому випадку ви вказуєте URL-адресу GeoServer, де зберігаються ваші геодані, а також назви таблиці та представлення у БД для відображення геоданих на карті.

      URL-адресу геосервера можна вказати як відносну, так і повну:

      Якщо вказати повну адресу геосервера, то ви зможете переглядати точки та шукати об’єкти на мапі прямо у конструкторі UI-форм.

      map 2

      Поле Details Title Path використовується для відображення детальної інформації про геопросторові об’єкти, які ви показуєте на карті. Ви можете вказати шлях до поля у вашій базі даних, яке містить назву об’єкта (Name), щоб відобразити цю інформацію в детальному вікні при натисканні на об’єкт на карті. Параметр Address використовується для відображення адреси геопросторового об’єкта.

      map 2 1

  6. На вкладці Data налаштуйте геокодування:

    Що таке геокодування?

    Геокодування — це процес конвертації адреси або інших описів місць у географічні координати (широта та довгота). У нашому випадку, функціональність геокодування використовує сервіс Nominatim, який базується на даних OpenStreetMap.

    • Enable Geocode — активація геокодування та підключення Nominatim. Ця опція дозволяє увімкнути чи вимкнути функцію геокодування у додатку.

    • Geocode Search Placeholder — це текст, який відображається у полі пошуку геокодування за замовчуванням. У цьому випадку користувачів просять ввести адресу або місце для пошуку, використовуючи плейсхолдер Search.

    • Geocode Search Url — це URL-адреса, яка використовується для відправлення запитів на сервер Nominatim для геокодування:
      https://nominatim.openstreetmap.org/search?format=json&q={s}

      Змінна {s} замінюється на текст, введений користувачем у полі пошуку.

      Ви можете використати будь-який інший сервіс.

    • Geocode Search Zoom — це значення масштабування карти після успішного геокодування. Значення 12, наприклад, означає, що карта буде збільшена на середній рівень деталізації, забезпечуючи користувачам загальний огляд області.

    • Geocode Marker Radius — це радіус маркера на карті, який відображає результати геокодування. Значення 10, наприклад, вказує на середній розмір маркера, що допомагає користувачам легко його розгледіти на карті.

    map 4

  7. Перейдіть на вкладку API та у полі Property Name вкажіть назву властивості, яка буде використовуватися в API-запитах. Наприклад, entityLocation.

    map 3

  8. Натисніть Save, щоб зберегти зміни, та вийдіть із налаштувань компонента.

  9. Перевірте, чи працює мапа належним чином. Ви можете знайти певний об’єкт на карті вручну, а також скористатися опціями пошуку та геокодування.

    map 5

    map 6

    map 7

2. Основні функції

  • Display

  • Data

  • Validation

  • Api

  • Conditional

  • Label: назва компонента, яка відображається поряд з ним.

  • Label Position: визначає положення назви відносно компонента (верх, праворуч, зліва, або внизу).

    • Для опцій Left (Left-aligned), Left (Right-aligned), Right (Left-aligned), Right (Right-aligned).

      • Label Width: встановлює ширину яку займає Label у відсотках відносно input.

      • Label Margin: встановлює відступ між Label та input у відсотках.

  • Placeholder: це текст, який відображається у полі коли воно пусте (незаповнене).

  • Description: опис компонента, який може допомогти користувачам зрозуміти його призначення.

  • Tooltip: текст, який відображається при наведенні курсора на компонент.

  • Tab Index: html атрибут який дозволяє контролювати навігацію по полям вводу за допомогою клавіатури. Детальніше можна почитати про нього в документації по html наприклад тут.

  • Hidden: поля, які приховані від користувача, але все ще є частинами форми й будуть передані при відправленні форми. Не забудьте прибрати прапорець в Clear when hidden, інакше будь-яке значення цього компонента буде порожнім.

  • Disabled: забороняє редагування.

  • Table View: визначає, чи відображувати елемент в таблиці та в EditGrid.

  • Component mode: задає режим роботи компонента. Доступні для вибору 2 значення Edit та Select

    • Edit: режим редагування або створення об’єкта чи об’єктів на мапі

    • Select: режим вибору попередньо нанесених нанесених об’єктів (вимикає елементи редагування об’єктів)

  • Single value: контролює режимом одного об’єкту чи багатьох, які можуть обрані чи відредаговані

  • Base Layers: керує налаштуваннями шарів мапи. Шари для мапи поставляються картографічними сервісами, наприклад Open Street Map. Налаштовано може бути один або більше шарів. Для кожного шару, необхідно налаштувати такі параметри:

    • Url: адреса серверу плиток (tile) картографічного сервера

    • Name: назва шару, яку користувач буде бачити при виборі шару

    • Attribution: атрибути шару (необов’язковий параметр)

    • Max Zoom: максимальний зум, який може обрати користувач для цього шару

  • Overlay Search Field: поле в даних, по якому буде відбуватись пошук

  • Search Zoom: значення зуму, яке буде автоматично задане після переходу до результату пошуку

  • Overlay Layers: використовується для налаштування власних шарів для мапи, які будуть накладені на основний шар, налаштований в розділі Base Layers Для кожного налаштованого власного шару, потрібно задати наступні параметри

    • Name: ім’я шару, яке користувач буде бачити в меню налаштування шарів мапи

    • Url: адреса гео-сервера

    • Type: тип даних гео-сервера (ім’я набору даних)

    • Custom color: колір міток для об’єктів отриманих з гео-сервера (необов’язковий параметр)

    • Details Title Path: шлях в об’єкті даних гео-сервера, де зберігається назва об’єкту, яка буде відображена при натисканні на маркер об’єкту

    • Details Params: додаткові параметри в об’єкті даних гео-сервера, які можуть бути відображені при натисканні на маркер об’єкту

      • Title: назва для поля, яка буду відображена поруч з його значенням

      • Path: шлях в об’єкті даних гео-сервера, де зберігається значення для цього параметра

  • Enable Geocode: додає додаткову строку пошуку, в якій можна шукати об’єкти на карті шляхом геокодування

    • Geocode Search Placeholder: строка яка буде відображена в пустому полі пошуку

    • Geocode Search Url: url адреса сервера гео-кодування. Для прикладу і за замовчуванням використовується сервер від Open street map - https://nominatim.openstreetmap.org/search?format=json&q={s}. Де s, це значення, яке вводить користувач у поле пошуку. Це значення буде підставлене в url у відповідне місце, замість {s}

    • Geocode Search Zoom: значення масштабування після успішного пошуку

    • Geocode Marker Radius: задає розмір маркера для найденого об’єкту

    • Custom Radius: додає ще одне текстове поле, яке відображається між картою і полем пошуку, яке дозволяє задавати радіус маркера користувачу

    • Redraw On: перемальовує компонент, якщо інший компонент змінюється

  • Clear value when hidden: дозволяє налаштувати очищення значення компоненту, коли компонент стає прихованим на сторінці.

  • Custom default value: дозволяє налаштувати власне, користувацьке значення за замовчуванням для компонента. У цій функції використовується JS вставка. Детальніше про JS вставки.

    • JavaScript: налаштовуйте власне значення за до допомогою javascript

    • JSONLogic: налаштовуйте власне значення за до допомогою JSONLogic.

  • Calculated value: дозволяє обчислювати значення компонента на підставі інших даних або умов. На відміну від Custom default value, значення поля буде обчислюватись кожного разу, коли відбуваються будь-які зміни на формі - користувач вводить данні, завершуються за http запити. У цій функції використовується JS вставка. Детальніше про JS вставки.

    • JavaScript: налаштовуйте власне значення за до допомогою javascript

    • JSONLogic: налаштовуйте власне значення за до допомогою JSONLogic.

  • Allow manual override of calculated value: дозволяє користувачам вручну перевизначити обчислене значення компонента.

  • Required: поле обов’язкове для заповнення перед відправленням форми.

  • Custom error message: спеціальне повідомлення про помилку, яке відображається, коли дані не проходять валідацію.

  • Custom validation: власна валідація, яка дозволяє вам створити специфічні для ваших потреб перевірки на валідність. У цій функції використовується JS вставка. Детальніше про JS вставки.

  • Property Name: ім’я поля в структурі даних, яка буде відправлена при відправці даних форми. Також це ім’я поля в структурі даних яким предзаповнюється форма. Поточне значення цього поля можна перевірити в структурі даних, яка відображається на вкладці Запит в інтерфейсі розробки форм.

  • Advanced Conditions: дозволяють вам налаштовувати складні умови для компонента. Ці умови визначають, коли компонент стає, наприклад. видимим, базуючись на інших компонентах або їх значеннях на формі.

    Ця функція використовує JS-вставки. Детальніше про це див. на сторінці JS-вставки.

  • Simple: виконує тіж самі задачі, що і Advanced Conditions, але дозволяє задати умови в більш простому форматі

3. Формат даних

Компонент, в якості даних, використовує спеціальний об’єкт з координатами, або масив таких об’єктів, в залежності від обраної опції Single на вкладці Data в налаштуваннях компонента. Також структура цього об’єкта залежить від виду об’єкта карти - Point, Polygon чи Line

Submission
// Приклад точки (point)
{
  "geometry": {
    "type": "point",
    "longitude": "29.992676",
    "latitude": "50.289449"
  }
}

// Приклад для полігону
{
  "geometry": {
    "type": "polygon",
    "dots": [
      {
        "longitude": "30.047607",
        "latitude": "49.993726"
      },
      {
        "longitude": "30.091553",
        "latitude": "48.958693"
      },
      {
        "longitude": "31.376953",
        "latitude": "49.066781"
      },
      {
        "longitude": "30.047607",
        "latitude": "49.993726"
      }
    ]
  }
}

// Приклад прямої
{
  "geometry": {
    "type": "line",
    "dots": [
      {
        "longitude": "30.563965",
        "latitude": "50.436625"
      },
      {
        "longitude": "36.23291",
        "latitude": "49.993726"
      }
    ]
  }
}

4. Пов’язані сторінки