Основная идея

Данный репозиторий демонстрирует как встраивать внешние приложения в CRM. Основная идея - предоставить функционал для реализации удаленных приложений, используя который разработчики могут написать собственные реализации виджетов (или любое другое приложение) расширяющее функционал ядра не затрагивая и не ломая функционал CRM. Для этого выбран подход с удаленным рендерингом. Код удаленного приложения выполняется в изолированной среде - iFrame, что позволяет загружать расширения безопасным и надежным способом, в то время как хост (код, который отображает пользовательский интерфейс) является частью основного приложения. Связь между удаленным приложением и хостом осуществляется через postMessage.

Удаленное приложение содержит ограничения на используемый функционал Vue и JS. Ниже описаны компоненты, api ядра и тд., что доступно и недоступно в рамках реализации собственных приложений. Более подробно об архитектуре и api библиотеки для удаленного рендеринга можно прочитать в документации @omnicajs/vue-remote

Используемые технологии

• В качестве UI фреймворка используется Vue 3. Компоненты ниже основаны на нем
• @omnicajs/vue-remote используется для рендеринга удаленного приложения и коммуницаии с host приложением
• @remote-ui/rpc используется для создания канала коммуникации между host и remote приложениями

Ядро предоставляет следующие компоненты:

    UiButton,
    UiError,
    UiLink,
    UiLoader,
    UiMenuItem,
    UiMenuItemGroup,
    UiModalSidebar,
    UiModalWindow,
    UiModalWindowSurface,
    UiScrollbar,
    UiTag,
    UiTransition,
    CrmYandexMap

Более подробно познакомиться с этими компонентами можно на витрине.

Доступны props, слоты (дефолтные и именнованные). Методы компонентов, компонент Transition, scoped slots, refs, директивы (кроме v-if/v-show) и модификаторы на данный момент недоступны.

Доступны события:

    InputEvent,
    DragEvent,
    FocusEvent,
    KeyboardEvent,
    PointerEvent,
    WheelEvent,
    MouseEvent,
    TouchEvent

Актуальный список событий можно посмотреть тут

В ядре доступно встраивание удаленных приложений в следующих местах(scope):

1. Карточка просмотра клиента (физ лицо) customer-card
2. Карточка редактирования клиента (физ лицо) customer-form
3. Карточка заказа order-card

Только для карточки заказа доступно api.

API Ядра в карточке заказа

api.getCustomerEmail 

Возвращает значение string Значение поля "Email"

api.setCustomerEmail

Принимает значение (): string | null Устанавливает переданное значение в поле "Email"

api.getCustomerPhone 

Возвращает значение string Значение поля "Телефон"

api.setCustomerPhone

Принимает значение (): string | null Устанавливает переданное значение в поле "Телефон"

api.getDeliveryAddress 

Возвращает значение string Значение поля "Адрес"

api.setDeliveryAddress

Принимает значение (): string | null Устанавливает переданное значение в поле "Адрес"

api.parseDeliveryAddress

Парсит адрес в соответствующем поле

Стили должны быть модульными

В удаленном приложении нужно описать используемые компоненты

const CrmYandexMap = defineRemoteComponent('CrmYandexMap', [
    'change',
] as unknown as { 'change': (address: string) => void })

export { UiButton, UiModalWindow, CrmYandexMap }

Более подробно можно посмотреть в документации @omnicajs/vue-remote

Инициализация расширения

В CRM доступна функция extensionsInit, которую можно вызвать в консоли для инициализации расширения. В качестве параметра функция принимает массив объектов вида:

[{
    entrypoint: 'extension-url',
    placement: 'delivery-address',
    scope: 'order-card',
    stylesheet: 'stylesheet-url',
    uuid: '1'
}]

extension-url - адрес страницы с подключаемыми скриптами сборки расширения. stylesheet-url - файл стилей расширения.

В текущем расширении сервер, возвращающий перечисленные ресурсы, описан в файле server.mjs.

Требования к архиву

Архив должен содержать следующие файлы:

• Файл manifest.json, описывает метаданные модуля. Он содержит информацию, необходимую для правильной интеграции и работы модуля в CRM
• HTML файл (*.html). Является точкой входа для расширения
• CSS файл (extension.*.css). Необязательный файл, который является стилями расширения
• JS файлы (extension.*.js). Файлы с кодом расширения. В архиве должен присутствовать хотя бы 1 файл.

Структура manifest.json

Файл manifest.json содержит метаданные для расширения и создается автоматически при выполнении команды make zip-archive. Пример содержимого файла manifest.json:

{
  "code": "core-ui-extensions",
  "version": 1,
  "scope": ["order"],
  "entrypoint": "index.html",
  "scripts": ["extension.js"],
  "stylesheet": "extension.css"
}

Где:

• code: string. Уникальный код расширения. Обязательный параметр
• version: number. Версия расширения. Значение должно быть целым числом и больше 0. Обязательный параметр
• scope: string[]. Область применения расширения. Обязательный параметр
• entrypoint: string. HTML файл, который является точкой входа для расширения. Обязательный параметр
• scripts: string[]. JS файлы расширения. Обязательный параметр
• stylesheet: ?string. CSS файл расширения. Необязательный параметр

Команда для создания архива

Для создания архива с необходимыми файлами и manifest.json, используйте команду:

make zip-archive

Пример удаленного приложения на основе @omnicajs/vue-remote

Описание примера

Пример представляет собой модальное окно с интерактивной картой от Яндекса. Маркер можно перетаскивать и тем самым изменять адрес. Используется JavaScript API Яндекс Карт и Геокодер версии 3.0. При первоначальной отрисовке позиционирование маркера происходит исходя из адреса в поле "Адрес", далее при перетаскивании маркера адрес выбирается исходя из текущих координат маркера, выбирается ближайший адрес к текущим координатам. При нажатии кнопки "Выбрать", происходит заполнение или обновление адреса в поле "Адрес".

Запуск

Начальное развертывание

Установка зависимостей

yarn install

Сборка приложения

yarn build

Сборка архива core-ui-extensions-examples.zip

make zip-archive

Для инициализации приложения внутри CRM необходимо выполнить его сборку (yarn build), а затем предоставить html страницу с подключенными скриптами сборки в качестве значения entrypoint, а так же файл стилей в качестве значения stylesheet объекта конфигурации.

В данном примере есть файл сервера, который отдает необходимые ресурсы и после сборки приложения достаточно его запустить с помощью команды node server.mjs.

После этого, на странице заказа в CRM достаточно вызвать в консоли браузера метод extensionsInit:

extensionsInit([{
    entrypoint: 'http://localhost:3000/extension/62aa8145-ed53-4862-b28f-f1bc6b36a3a3',
    placement: 'delivery-address',
    scope: 'order-card',
    stylesheet: 'http://localhost:3000/extension/62aa8145-ed53-4862-b28f-f1bc6b36a3a3/stylesheet',
    uuid: '1'
}])

В секции "Отгрузка и доставка" под полем "Адрес" должна появиться кнопка "На карте". При клике на кнопку открывается модальное окно с картой. Для работы карты нужен api ключ.