Просмотр исходного текста страницы UI Designer

С версии 2.15.260227 появилась возможность для создания кастомных интерактивных веб-форм с помощью продукта UI Designer.

Oktell UI Designer (далее UI Designer) — самостоятельный программный продукт для создания интерактивных веб-форм и диалоговых форм оператора. Он разработан отдельно от коммуникационной платформой «Oktell» (далее Oktell) и не является её модулем, надстройкой или производным продуктом. В этой инструкции описан один из способов применения продукта — интеграция с контакт-центром на базе коммуникационной платформой «Oktell» через открытый механизм веб-форм. Тот же способ подключения подходит и для других систем, умеющих отображать веб-страницу по ссылке.

'''1. О решении'''

UI Designer — это конструктор интерактивных веб-форм с визуальным редактором. Он позволяет описывать экран оператора в виде декларативного состояния (JSON) и отображать его в браузере, а также обновлять содержимое формы по запросу — например, при получении новых данных о звонке или заявке.
Продукт распространяется в виде отдельных сборок и работает в двух режимах:

–	режим просмотра — отображает готовую форму оператору;

–	режим редактирования (конструктор) — открывает визуальный редактор формы, доступный по отдельному GET-параметру (см. раздел 6).

Интеграция с внешней системой (в данном случае — с Oktell) выполняется через веб-страницу, которой передаются параметры сессии в адресной строке, и через файл конфигурации, который указывает, какой сценарий на стороне Oktell обрабатывает запросы формы.

'''2. Что потребуется'''

–	доступ к серверу Oktell, на котором нужно разместить сборку UI Designer;

–	права на редактирование файлов в веб-каталоге сервера Oktell (папка WWW);

–	текстовый редактор с подсветкой синтаксиса — например, Notepad++;

–	доступ к скрипт-конструктору Oktell — для настройки сценария, который будет обрабатывать запросы формы, и для указания ссылки на форму в диалоговом сценарии оператора.


'''3. Введение''' 

UI Designer входит в состав пакета обновлений Oktell. Убедитесь, что UI Designer установлен – проверьте наличии папки SRV\WWW\UIDesigner на сервере Oktell.Если папка отсутствует на сервере Oktell – обратитесь к партнеру OOO «Телефонные системы» для уточнения возможности получения и применения продукта.
Из перечисленных файлов и папок для настройки интеграции важны:

–	static — служебные файлы приложения (см. предупреждение в разделе 10);

–	form.ajax.js.execsvcscriptplain — конфигурация сценария обработки формы на стороне Oktell (раздел 4);

–	state.js — начальное состояние формы (раздел 6);

–	index.html — точка входа, по которой форма открывается в браузере.


'''4. Укажите проект и сценарий обработки формы'''

Файл form.ajax.js.execsvcscriptplain — текстовый; откройте его в Notepad++ или любом другом текстовом редакторе. В нём указано, какой сценарий Oktell (и в каком проекте) будет обрабатывать запросы, поступающие от формы.

Пример: в Oktell может быть несколько проектов со сценариями — выберите тот, что относится к вашей интеграции.

[[Файл:Scr1.png]]
                  


В файле укажите название вашего проекта (projectname) и название служебного сценария обработки формы (scriptname), например:

[[Файл:Scr2.png]]

Значение scriptname должно точно совпадать с названием сценария в Oktell, который вы настроите на обработку запросов формы (например, _constructor).

'''5. Настройте обработку событий в сценарии Oktell'''

Сценарий, указанный на предыдущем шаге, должен уметь обрабатывать события, которые присылает UI Designer — как минимум load (запрос актуального состояния формы) и, при необходимости, загрузку файлов (upload). Ниже — пример типовой структуры такого сценария: приём GET-параметров, разбор запроса и ветвление по типу события.

Пример схемы сценария: приём параметров, разбор запроса и обработка события load:

 [[Файл:Scr3.png]]


Логика внутри блоков (что именно отдавать в ответ на load, upload и на ошибочные запросы) зависит от вашей задачи — это обычная часть сценария Oktell, которую вы описываете в скрипт-конструкторе самостоятельно. Со стороны UI Designer важно только то, что ответ должен возвращать состояние формы в ожидаемом формате (см. следующий раздел).

'''6. Настройте начальное состояние формы'''

Файл state.js задаёт базовое (первоначальное) состояние формы, которое загружается при первом открытии. Чтобы форма отрисовалась с актуальным состоянием, в главном контейнере main должны быть заданы событие onInit и метод load, который запросит обновлённое состояние с сервера. Пример:

  "main": {
    "type": "container",
    "width": "100%",
    "height": "100%",
    "layout": "row",
    "paddings": {
      "left": "10px",
      "right": "10px",
      "top": "10px",
      "bottom": "10px"
    },
    "childs": [
      "messages-box"
    ],
    "bgColor": "secondary",
    "events": [
      {
        "event": "onInit",
        "method": "load"
      }
    ]
  }

'''7. Подключите форму к диалоговому сценарию оператора'''

В диалоговом сценарии Oktell, отвечающем за операторскую задачу, укажите веб-форму по ссылке, сформированной по следующему принципу:
http://<ip-адрес сервера>:4055/<имя папки>/index.html?id=<id сессии>&login=<логин>&password=<пароль>
где <имя папки> — название, которое вы задали папке со сборкой на шаге 3 (в примерах выше — constructor). Значения параметров id, login и password описаны в справочнике параметров (раздел 9).

'''8. Откройте режим редактирования формы'''

Чтобы открыть в браузере сам конструктор (визуальный редактор формы, а не отрисованную готовую форму), перейдите по ссылке:
http://<ip-адрес сервера>:4055/constructor/index.html?editor=1&emulateApi=1&persistState=1&syncTabs=1
На заметку
GET-параметры передаются как строка, поэтому значения "false" и "true" в них равнозначны — оба приводятся к true. Чтобы включить параметр, укажите любое непустое значение (например, editor=1); чтобы отключить — оставьте его пустым (например, editor=).

'''9. Справочник GET-параметров'''

Параметр	По умолчанию	Описание
id	—	Идентификатор сессии обращения клиента. Передаётся при каждом запросе к серверу.
editor	false	Включает режим редактирования формы (сам конструктор). В дальнейшем планируется разделение на отдельные сборки редактора и просмотрщика.
emulateApi	false	Отключает реальные запросы к серверу — данные эмулируются на стороне клиента.
persistState	false	Сохраняет текущее состояние формы в LocalStorage браузера. Удобно при разработке — не используйте в production.
syncTabs	false	Синхронизирует действия между вкладками одного браузера: действие в одной вкладке повторяется в остальных. Удобно при разработке — не используйте в production, так как замедляет работу.
wsDisable	false	Отключает интеграцию по WebSocket.
login	—	Логин пользователя с разрешённым доступом к web-api.
password	—	Пароль пользователя с разрешённым доступом к web-api, в виде MD5-хэша.

'''10. Важно при переносе в production'''

Предупреждение
В каталоге static/js собираются файлы вида 0.*.chunk.js, 1.*.chunk.js и main.*.js. Файл 1.*.chunk.js отвечает за работу режима редактирования (editor=1). Если удалить его при подготовке production-сборки, редактор формы перестанет открываться — просмотр готовых форм операторами при этом продолжит работать в обычном режиме.
Также для production не рекомендуется использовать параметры persistState и syncTabs — они предназначены для удобства разработки и могут замедлять работу формы у операторов.

'''11. Итоговый чек-лист'''

☐	Сборка UI Designer присутствует в папке WWW сервера Oktell.

☐	В form.ajax.js.execsvcscriptplain указаны верные projectname и scriptname.

☐	Сценарий Oktell обрабатывает событие load (и другие нужные события, например upload).

☐	В state.js настроены начальное состояние и событие onInit → load.

☐	В диалоговый сценарий оператора добавлена ссылка на форму с нужными GET-параметрами.

☐	Для production отключены persistState и syncTabs, файл 1.*.chunk.js сохранён.