Перейти к основному содержимому

Платформа YouGile. Создание расширений

Описание платформы​

YouGile Платформа это механизм расширений, позволяющий изменять и дополнять функциональность системы без изменения исходного кода продукта.

Расширения доступны в коробочной версии на тарифе Платформа.

Разрабатывать и тестировать расширения можно бесплатно, скачав дистрибутив YouGile.

Основные возможности платформы:

  • выполнение пользовательского JavaScript-кода
  • расширение интерфейса (UI)
  • выполнение серверной логики
  • использование REST API YouGile
  • обработка событий системы (webhooks)

Как это работает​

Работа расширений основана на встраивании JavaScript-кода в клиентскую и серверную части системы YouGile.

YouGile предоставляет собственный API для удобной разработки расширений. При этом разработчику доступны и стандартные возможности JavaScript:

  • в браузере - для UI-скриптов
  • в среде Node.js — для серверных скриптов

Для создания расширения требуется только:

  • дистрибутив YouGile
  • любой текстовый редактор

Создание простого расширения занимает около 3 минут и не требует предварительной подготовки: Видео с примером создания расширения.

Готовое расширение можно сохранить в виде ZIP-архива и загрузить в коробочную версию YouGile.

Возможности расширений​

С помощью расширений можно:

  • изменять поведение существующих интерфейсов YouGile с использованием JavaScript
  • создавать новые элементы и сценарии работы интерфейса
  • выполнять собственный JavaScript-код на стороне сервера YouGile и изменять бизнес-логику системы
  • использовать все возможности REST API YouGile из серверных скриптов

В дистрибутив YouGile уже включены все необходимые библиотеки для разработки расширений и установка дополнительных зависимостей не требуется.

Во время разработки расширения все изменения автоматически применяются в запущенной коробке YouGile, что позволяет сразу видеть результат работы кода.

Базовое расширение​

Рекомендуем ознакомиться с 3-х минутным видео по созданию расширения.

Установка и запуск коробки YouGile​

  1. Скачайте последнюю версию дистрибутива YouGile
  2. Распакуйте архив
  3. Запустите исполняемый файл server (рекомендуется запускать из терминала для просмотра логов)
  4. В браузере откройте указанный адрес mainPageUrl (по умолчанию): 
    http://localhost:8001
  5. Создайте учётную запись администратора и выполните вход в систему

Создание расширения​

  1. Перейдите в каталог:

    extensions

  2. Скопируйте папку example-extension в эту же директорию.

  3. Внутри папки уже находятся:

    • файл manifest.json
    • два JavaScript-скрипта, которые используются расширением

  4. Любая папка внутри каталога extensions считается расширением, если в ней присутствует файл manifest.json.

Включение расширения в интерфейсе​

  1. Откройте интерфейс YouGile в браузере:

    http://localhost:8001

  2. Перейдите в раздел Моя компания - Расширения

  3. В списке расширений должна появиться новая запись с названием Пример расширения

  4. Включите расширение

  5. После включения появится уведомление с текстом:

    Example extension!

Внесение изменений в расширение​

Открытие проекта​

Откройте папку расширения в любом редакторе кода, например:

  • Visual Studio Code
  • WebStorm
  • Atom
  • Sublime Text
  • Notepad++
  • Vim

Изменение manifest.json​

  1. Откройте файл manifest.json
  2. Измените значение поля name
  3. Сохраните файл — название расширения в списке расширений обновится автоматически

Изменение UI-скрипта​

  1. В файле manifest.json в поле ui указан файл ui.js

  2. Этот файл загружается в пользовательский интерфейс

  3. Откройте ui.js и измените текст:

    Example extension!

    на любой другой.

  4. Сохраните файл, после этого расширение автоматически перезапустится, и в интерфейсе появится новое уведомление.

Изменение server-скрипта​

  1. В файле manifest.json в поле service указан файл service.js
  2. Этот скрипт выполняется на сервере
  3. В примере скрипт выводит текст Hello в лог сервера
  4. Измените текст и сохраните файл
  5. В терминале, где запущен сервер YouGile, появится сообщение с новым значением

Ниже в этой инструкции приведена основная документация по платформе YouGile, включая описание возможностей API для клиентских и серверных скриптов. Для освоения платформы можно последовательно изучать документацию и обучающие видео, либо сразу приступать к экспериментам, ориентируясь на подсказки и автодополнение в редакторе кода. Готовое расширение можно упаковать в ZIP-архив и загрузить в другую коробочную версию YouGile через интерфейс в разделе Моя компания - Расширения

Структура расширения​

Пример структуры расширения:

extensions/
└── my-extension/
    ├── manifest.json
    ├── service-one.js
    ├── service-two.js
    ├── ui-one.js
    ├── ui-two.js
    ├── util.js
    ├── some-folder/
    │   └── example.js
    ├── node_modules/
    └── public/
        ├── image.png
        └── media/
            ├── icon.svg
            └── media.mp4

Расширение YouGile представляет собой каталог, в котором обязательно должен присутствовать файл manifest.json. Наличие этого файла является обязательным условием для распознавания каталога как расширения.

Внутри расширения могут находиться скрипты двух типов:

  • UI-скрипты выполняются в пользовательском интерфейсе YouGile
  • Service-скрипты выполняются на сервере YouGile

Каталог node_modules/ используется для подключения сторонних библиотек в серверных скриптах. Для этого в расширении можно создать файл package.json и установить необходимые зависимости с помощью npm. Установленные библиотеки будут доступны только для service-скриптов и не загружаются в интерфейс.

При необходимости в расширение можно добавить каталог public. Файлы, размещённые в этом каталоге, становятся доступными пользователям по прямому URL, например:

mainPageUrl/extension/my-extension/.../image.png

В скриптах расширения поддерживается использование require для импорта других файлов расширения и внешних библиотек.

Пример manifest.json:

{
  "name": "Интеграция с Телеграм",
  "description": "Расширение позволяет <b>синхронизировать</b> групповой чат с группой в телеграм. Для каждого группового чата можно создать бота, который будет передавать сообщения в группу и в YouGile, а также присылать ответы из группы",
  "image": "/extensions/telegram-bot/media/icon.svg",
  "ui": ["index.ui.js", "two.ui.js", "util.js", "some-folder/example.js"],
  "service": "one.service.js"
}

Если расширение включено, то js-файлы, которые указаны в ui, запускаются в интерфейсе пользователя при входе в компанию. На сервере, где развернут YouGile, запускаются service-скрипты.

Service-скрипты и ui-скрипты​

Возможности service-скриптов​

У service-скриптов помимо обычных возможностей и библиотек, которые присутствуют в node, есть доступ к библиотеке yougile:

const yougile = require('yougile')

// в yougile.Company – находятся данные о компании, в которой запущено расширение
const {name, companyId} = yougile.Company

// yougile.conf – хранит настройки сервера YouGile, которые указываются в conf.json
const conf = yougile.conf

Библиотека yougile позволяет работать с возможностями REST API:

// отправить сообщение от лица системного пользователя
// см. https://yougile.com/api-v2#/operations/ChatMessageController_sendMessage
yougile.Api.post(`/chats/${taskId}/messages`, {
  text: 'Привет!',
  textHtml: '<p>Привет!</p>',
  label: 'Упоминание'
})

Также библиотека yougile позволяет подписываться на события в системе (webhooks):

const yougile = require('yougile')

// подписка на событие с установкой обработчика в скрипте
// внешний endpoint, который принимает данные не нужен
yougile.Api.setupEventCallback({
  event: 'task-moved',
  handler: data => {
    // эта функция будет вызываться, когда будет перемещена
    // какая-либо задача в компании, где включено расширение,
    // перемещение должно быть в другую колонку
    // data - содержит информацию о перемещённой задаче
    console.log('Task was moved', data)
  }
})

Описание событий в REST API можно изучить по ссылке: https://yougile.com/api-v2#/operations/WebhookController_create

Обратите внимание: отсутствует использование некоторых нативных методов node. Это связано это с тем, что не все методы node попадают в бинарный файл. Например, для использования fetch необходимо использовать const fetch = require('node-fetch').

Возможности ui-скриптов​

UI-скрипты запускаются в браузере и десктоп-приложении YouGile. Для работы с интерфейсом системы, наравне со многими стандартными возможностями javascript, доступна библиотека yougile-ui.

// при подключении библиотеки
// новые методы добавляются в глобальное пространство имён
require('yougile-ui')

// показать сообщение об ошибке
Notifier.error('Hello!')

Cписок возможностей такой же, как и в конфигураторе YouGile.

В интерфейсе YouGile есть встроенный редактор, который позволяет быстро проверить работу небольших ui-скриптов.го можно вызвать сочетанием клавиш Ctrl+˜ . В правой части этого интерфейса есть список всех методов, которые доступны в ui-скриптах, также в редакторе можно попробовать данные методы.

Взаимодействие между ui- и service-скриптами​

UI-скрипты поддерживают механизм взаимодействия с серверными (service) скриптами. В service-скрипте можно определить функции, которые затем могут быть вызваны из ui-скриптов.

Пример определения функции на стороне service-скрипта:

const yougile = require('yougile')
const Service = yougile.Service

// userId передаётся всегда – это id пользователя
// у которого вызвался метод (в этих примерах userId не используется)
Service.serverTime = ({userId}) => {
  return Date.now()
}

Service.addTwoNumbers = ({userId, args}) => {
  const [a, b] = args
  return a + b
}

На стороне ui-скрипта:

equire('yougile-ui')

const time = await Service.serverTime()
console.log('Server time is', time)

const sum = await Service.addTwoNumbers(1, 2)
console.log(sum, 'must be equal to', 3)

Хранение публичных данных в ui- и service-скриптах​

На клиенте:

const data = await Service.getData()
Service.setData({...})

На сервере:

const yougile = require('yougile')
const data = await yougile.Service.getData()
await yougile.Service.setData({...})

Хранение непубличных данных в service-скриптах​

На клиенте методы Service.getPrivateData(), Service.setPrivateData() недоступны. На сервере используем:

const yougile = require('yougile')
// получаем непубличные данные
const data = await yougile.Service.getPrivateData()
// сохраняем непубличные данные
await yougile.Service.setPrivateData({token: '...'})

Расположение данных​

Публичные данные хранятся по пути ./database/$companyId/$extension-name.json. Приватные данные хранятся по пути ./database/$companyId/$extension-name-private.json

Получить путь до базы данных:

const {DataService} = require('yougile')
DataService.getDatabasePath()

Библиотека yougile​

Данная библиотека yougile используется только в service-скриптах. Из yougile может быть сделан импорт следующего:

  • Api - необходим для REST Api вызовов, также можно подписаться на вебхуки yougile (метод subscribe) или подписаться на свои кастомные вебхуки (метод setupCustomWebhook)
  • Company - хранит имя компании и companyId
  • Service - необходим для взаимодействия клиент/сервер и получения/сохранения данных
  • conf - хранит основную конфигурацию yougile
  • extension - имя расширения
  • mainDir - путь до папки yougile

Библиотека yougile-ui декларирует типы для конфигуратора, в ней содержится более полное описание некоторых сигнатур методов.

Пример расширения​

Для старта разработки расширения вы можете воспользоваться примером расширения. Находится он по пути ./example-extension.

В примере есть запросы к REST API, подписка на событие перемещения задачи (перемещение не должно быть внутри столбца), обмен данными между сервером и клиентом, пример взаимодействия с публичными и приватными данными.

Для того чтобы пример появился в списке расширений, папку ./example-extension нужно скопировать в папку ./extensions

Установка расширения​

Расширение можно установить двумя способами:

  • Установить через архив (поддерживаются zip архивы). Для того чтобы установить, нужно заархивировать папку расширения в zip архив, перейти в Моя компания - Расширения и внизу нажать на кнопку Установить. Через 5-10 секунд Ваше расширение появится в списке расширений. Расширение установится в папку ./extensions

  • Поместить папку с расширением в папку ./extensions

Расширения запускаются через 15 секунд после старта сервера. Иногда требуется перезагрузить страницу, чтобы клиентский код расширения появился в браузере.