7.1. Руководство по работе с внешними скриптами

7.1.1. Назначение и общий функционал работы с внешними скриптами

Скрипты, поддерживаемые приложением располагаются в конфигурационной базе приложения. Внешние js-файлы обычно содержат код, который используется на нескольких различных веб-страницах. Такие скрипты называются внешними скриптами.

Управление скриптами в приложении осуществляется с помощью редактора скриптов см (Раздел 5.18) Руководства администратора.

Для работы с Системой в коде внешнего скрипта доступны следующие глобальные переменные:

  • $getters - все геттеры стора (vuex) приложения.
  • $repos - API репозитории (adminRepository, uiRepository и т.п.).
  • $plugins - плагины Приложения.

Внешние скрипты используются:

  • в Формах
  • в компоненте SmartInput
  • для вычисления ключевых слов (KEYWORDS) приложения
  • в Actions API

7.1.2. Порядок работы с внешними скриптами

Для импорта внешних скриптов в компоненты Приложения используется плагин «ScriptInjector».

Плагин «ScriptInjector»

Обеспечивает получение, сохранение и выполнение скриптов. Плагин и все его файлы находятся в каталоге /plugins/script-injector. Приложению доступен единственный метод «$ScriptInjector.inject(<script-id> [,context])».

Порядок работы плагина:

  • Скрипт запрашивается из списка доступных скриптов.
  • Полученный исходный js-файл внешнего скрипта сохраняется в отдельный динамический vuex-модуль. Последующие запросы по тому же URL возвращают ранее сохраненный скрипт из стора.
  • Выполнение внешнего скрипта производится через плагин «vm-browserify» (плагин для выполнения js-кода в Приложении). Используется локальная (измененная) версия стороннего плагина «vm-browserify». То есть данный плагин берется не из NPM-пакета, а хранится локально в каталоге /plugins/vm-browserify. Внешний скрипт выполняется через плагин «vm-browserify» в пределах контекста.

Примечание

Контекст - это передаваемые в скрипт переменные при его выполнении в плагине «vm-browserify».

Пример внешнего скрипта, в котором происходит обращение к переменным из контекста:

      dependency = {
      clickFunction: function (param) {
          return `param to clickFunction was ${param}`
      },
      lang: $getters['auth/language'],
      plugins: $plugins,
      repos: $repos,
      }

Здесь $getters, $repos, $plugins - это переменные, переданные из контекста.

Обращение к переменным из контекста означает, что из такого скрипта можно обращаться, например, к бэкенду.

*Например, в компоненте карты можно запрашивать данные локаций из бэкенда в методе клика по маркеру на карте.*

Если контекст приложения  не был передан, то используется контекст "по-умолчанию", содержащий геттеры, репозитории и плагины.

В этом случае используются:

  * $getters - все геттеры стора (vuex) Приложения. Описание геттеров (см :numref:`Store API Getters` Руководства разработчика)
  * $repos - API репозитории. (см :numref:`Repository API` Руководства разработчика)
  * $plugins - плагины Приложения.

Пример использования плагина «ScriptInjector»:

dependency = {
clickFunction: function (param) {
    return `param to clickFunction was ${param}`
},
lang: $getters['auth/language'],
plugins: $plugins,
repos: $repos,
}
// ...
// где-то в другом компоненте приложения
// запросим скрипт c идентификатором 7b425f17-b45a-3929-b904-a38aba3528f7 и вернем результат его выполнения
let result = await this.$ScriptInjector.inject(`7b425f17-b45a-3929-b904-a38aba3528f7`)

// inject() вернет объект с двумя свойствами:
// output - результат выполнения скрипта
// context - переданный контекст (при необходимости он может быть изменен скриптом)
console.log(result.output)
/*
{
clickFunction: function (param) {
    return `param to clickFunction was ${param}`
},
lang: $getters['auth/language'],
plugins: $plugins,
repos: $repos,
}
*/

Файлы плагина

injector
Является основным конфигурационным файлом плагина «ScriptInjector». В нем описывается функционал получения и выполнения скриптов. Возвращает factory-функцию с методами плагина. На вход получает ссылки на инстанс, хранилище и опционально дополнительные свойства для контекста.
store-module
Конфигурационный файл для динамического модуля vuex. Описывает vuex-модуль (методы запроса, хранения скриптов, где хранить и т.п.). Используется конфигурационным файлом «injector».
mixin
Миксин для использования в компонентах. Позволяет компонентам получить доступ к скачанным внешним скриптам.
index
В этом файле производится дополнение контекста, в котором выполняются скрипты и вставка в инстанс (стандартная процедура для плагинов). Вставка плагина в контекст фронтенда. Здесь в контекст для «vm-browserify» передаются геттеры, плагины и репозитории.

Для использования внешних скриптов компонентом SmartInput к нему необходимо подключить миксин /scipt-injector/mixin и выполнить его с привязкой к свойству, в котором перечислены источники скриптов.

Все компоненты полей форм наследуются от компонента Form/Elements/index в котором уже имеется функционал взаимодействия с внешними скриптами, поэтому для использования внешних скриптов в компонентах форм не требуется специально подключать миксин /scipt-injector/mixin (т.к. он уже включен в их корневой компонент Form/Elements/index).

7.1.2.1. Применение внешних скриптов в компоненте SmartInput

Функционал компонента SmartInput конфигурируется несколькими внешними скриптами, указанными в файле pages/feed/config/SmartInput.js. Все указанные конфигурационные файлы являются обязательными.

Подробное описание и назначение для каждого скрипта см. здесь Руководство по настройке SmartInput.

7.1.2.2. Применение внешних скриптов в компоненте формы

  1. Для использования внешних скриптов в компоненте формы необходимо сначала поместить данные внешние скрипты в реестр (базу) скриптов приложения.

  2. Затем в Редакторе форм необходимо открыть нужную форму на редактирование

  3. На вкладке «Компоненты» следует найти компонент, для которого предполагается использовать внешние скрипты.

  4. Далее необходимо редактировать компонент

  5. В открывшейся форме редактирования компонента на вкладке «Параметры» необходимо написать добавить в json описание параметр «dependencies» следующего формата:

    {
"dependencies": [
    {
    "name": "mapIncidentsHandler",
    "src": "241cc18a-e62a-36d9-8578-76fa468e8f2d"
   },
  {
   "name": "some_other_dependency",
   "src": "190b3f74-36e3-37a1-b34e-bee7d637658a"
  }
 ]
}

Здесь указано следующее:

dependencies
В квадратных скобках перечисляются все зависимости. Каждая зависимость указывается в фигурных скобках.
name
Указывается наименование зависимости. В примере указаны две зависимости, их наименования: «mapIncidentsHandler» и «some_other_dependency».
src
идентификатор скрипта в реестре скриптов.

Подробнее об использовании внешних скриптов компонентами форм см. Описание операций на вкладках редактора компонента формы.

  1. После этого необходимо сохранить изменения компонента формы и изменения самой формы по соответствующим кнопкам «Сохранить».
  2. Для того, чтобы измнения из внешних скриптов вступили в силу в Системе, достаточно обновить страницу с формой, к компоненту которой были добавлены внешние скрипты. Перезапускать Систему не нужно.

7.1.2.3. Примеры использования внешних скриптов в Системе

Пример 1. Использование внешнего скрипта для компонента поля формы с типом «карта» ElMap :

markerCallback({type, group, marker}){
    switch (type) {
        case 'click':
        // TODO: declare callbacks for specific marker groups
        this.dependencies.MAP.markerClickCallback({
            group,
            marker,
            },
            {
            $console:window.console,
            $vm:this
        })
        break;
        default:
        // this.markerDefaultCallback()
        break;
    }
    }

В этом примере компонент использует метод «markerClickCallback» из его зависимости (внешнего скрипта) с названием «MAP».

Примечание

Для остальных компонентов полей формы использование внешних скриптов указывается аналогичным образом.

Пример 2. Использование внешнего скрипта в Редакторе форм для компонента формы с типом «map»:

{
 "dependencies": [
  {
    "src": "e10802b3-035b-3284-801b-e6d1f5b2695a",
    "name": "MAP"
  }
 ],
 "url": "https://core-renderer-tiles.maps.yandex.net/tiles?l=map&x={x}&y={y}&z={z}&scale=1&lang=ru_RU"
}

Здесь в Редакторе форм в поле «Параметры» указывается структура «dependencies» в формате JSON. В результате компонент формы будет использовать внешний скрипт script-inject/form/incidents/map/sites-v2.js.

Примечание

Для остальных компонентов формы использование внешних скриптов указывается аналогичным образом.

7.1.3. Описание разработки ключевых слов, с помощью SCRIPT API

7.1.3.1. Общее описание

Для программирования ключевых слов используется скрипт с идентификатором KEYWORDS

Скрипт должен содержать javascript функцию keywords.
Функция возвращает объект с перечнем поддерживаемых ключевых слов.

Каждое ключевое слово содержит value, который может быть функцией или ссылкой (по идентификатору) на другой скрипт, в котором вычисляется значение.

7.1.3.2. Пример

function keywords (ctx) {
return {
   RANDOM_STRING: {
    value: 'db3c2509-864c-3b45-894a-75cab412d3da'
  },

  RANDOM_EMOJI: {
     value () {
      const emoji = ['emoji1','emoji2']
      const randomIndex = Math.floor(Math.random() * emoji.length)
       return emoji[randomIndex]
    }
  }
 }
}