Виджеты OkoCRM

Виджет — это пользовательское расширение OkoCRM, которое подключается к карточкам сделок, контактов и компаний и расширяет интерфейс CRM собственными кнопками, окнами и страницами.

Что такое виджет и для чего он нужен

Виджет — это набор файлов (JavaScript, CSS, Handlebars-шаблоны, конфигурация, изображения), который загружается в OkoCRM и исполняется внутри интерфейса CRM через Widget API. Виджет может:

• отображать собственную иконку в карточке сделки, контакта, компании или в сайдбаре;
• открывать модальные окна и отдельные страницы внутри CRM;
• читать данные сущности (название, ответственный, сумма, телефоны, e-mail и т. д.);
• реагировать на события CRM: открытие карточки, изменение, сохранение, создание;
• обращаться к публичному API OkoCRM и к внешним сервисам по HTTP;

Виджеты решают задачи, для которых нет готовой интеграции: подсчёт значений по полям сделки, заполнение полей карточки данными из внешнего сервиса, генерация документов, проверка контрагента, отправка уведомлений в сторонние системы и т. п.

Личные и публичные виджеты

Виджеты в OkoCRM делятся на два типа по способу распространения. Технически это один и тот же формат файлов, но условия использования и проверки различаются.

Личные виджеты

• доступны только пользователям аккаунта, в котором его загрузили;
• не публикуются в OkoStore и не проходят модерацию OkoCRM (но можно сделать его публичным, указав это в новой версии);
• подходят для внутренних интеграций компании, кастомных расчётов и одноразовых задач;
• могут содержать настройки и параметры, специфичные для одной компании.

Публичные виджеты

• публикуются в OkoStore и доступны любому аккаунту;
• проходят модерацию перед публикацией;
• запрещена обфускация и минификация кода;
• должны иметь корректное и адекватное описание;
• должны корректно работать у пользователей.

Общие требования

• все текстовые файлы (скрипты, стили, шаблоны, SVG, JSON) — в кодировке UTF-8 без BOM;
• перевод строки должен быть LF;
• script.js — это главный ES-модуль;
• config.json обязателен и содержит параметры виджета;
• все CSS-классы должны иметь префикс widget-<widget-id>- во избежание конфликтов со стилями платформы и других виджетов;
• HTML формируется в Handlebars-шаблонах в папке templates/;
• имена полей в шаблоне more_settings должны начинаться с setting, например name="setting[client_id]" — иначе значения не сохраняются;
• HTTP-запросы выполняются через fetch, widgetApi.externalFetch или widgetApi.internalFetch — в зависимости от целевого API.

Ограничения

• виджет работает только во фронтенде CRM — серверной части у виджета нет;
• виджет не отрисовывает позиции автоматически: иконки, модалки и страницы нужно отрисовывать вручную из script.js в ответ на события;
• приватные события (lead.main, company.main, contact.main, more_settings.*, page.*) изолированы для каждого виджета — виджеты не получают приватные события друг друга;
• шаблон more_settings уже встроен в форму настройки интеграции;
• настройки виджета (settings и more_settings) хранятся на стороне OkoCRM;
• встроенные библиотеки: Lodash, Umbrella JS.

Техническое описание виджета

Структура файлов

Виджет — это папка с фиксированной структурой:

/
  config.json          # Конфигурация виджета (обязательно)
  script.js            # Главный скрипт — ES-модуль с default export (обязательно)
  logo.png             # Иконка виджета (опционально)
  templates/           # Handlebars-шаблоны (.hbs)
    modal.hbs
    more_settings.hbs
    page.hbs
  styles/              # CSS-стили для шаблонов
    modal.css
    more_settings.css
    page.css

Имена шаблонов и стилей не ограничены теми приведёнными — можно создавать собственные (например, templates/row.hbs, styles/row.css) и подключать их через widgetApi.getTemplate('row') и widgetApi.linkStyle('row').

config.json

Декларативное описание виджета: идентификатор, версия, поля настроек и иконки позиций.

{
  "id": "<widget-id>",
  "author": "Author Name",
  "version": "1.0.0",
  "settings": {
    "links": [
      { "title": "Документация", "url": "https://example.com" }
    ],
    "text": "Описание виджета для страницы настроек",
    "fields": [
      { "name": "field_name", "type": "text", "label": "Название поля", "required": true }
    ]
  },
  "icons": {
    "lead.main":    "logo.png",
    "contact.main": "logo.png",
    "company.main": "logo.png",
    "sidebar":      "logo.png"
  }
}

script.js — точка входа

Главный файл виджета — ES-модуль с одним default export. Функция получает два аргумента: widgetApi (взаимодействие с CRM) и settingsApi (доступ к настройкам и идентификаторам виджета).

export default async function (widgetApi, settingsApi) {
  // Подписки на события, отрисовка позиций, бизнес-логика виджета
}

Шаблоны и стили

Весь HTML описывается в Handlebars-шаблонах templates/*.hbs. Шаблон загружается асинхронно и компилируется в функцию, которой можно передать данные:

const template = await widgetApi.getTemplate('modal');
const html = template({ title: 'Заголовок', items: [...] });

Стили подключаются через widgetApi.linkStyle('modal') — будет загружен файл styles/modal.css. CSS-классы внутри стилей обязательно должны иметь префикс (в личных виджетах - по усмотрению):
widget-<widget-id>-

Позиции отрисовки

OkoCRM не отрисовывает позиции виджета автоматически. Виджет сам решает, когда и что отрисовать, в ответ на события CRM. Различают два вида позиций:

• Статические позиции (иконки) — отрисовываются методом renderStaticPosition(position). Иконка берётся из config.json — icons. Доступные позиции: lead.main, company.main, contact.main, sidebar.
• Шаблонные позиции (HTML-блоки) — отрисовываются методом renderTemplatePosition(position, html). Используются для more_settings и page.

Встроенные библиотеки

• Handlebars — для шаблонов; доступны хелперы Lodash с префиксом _ (например, {{_capitalize name}}) и логические хелперы {{and a b}}, {{or a b}}.
• Umbrella JS (import u from 'umbrellajs') — для работы с DOM и обработки событий внутри отрисованного HTML.
• Lodash (import _ from 'lodash') — утилиты.

Правила и соглашения

• Нельзя перекрывать элементы интерфейса OkoCRM;
• Нельзя изменять стандартное поведение элементов системы OkoCRM;
• Нельзя использовать идентичные названия классов/id из OkoCRM;
• Нельзя подключать сторонние шрифты;
• Минимизировать HTML в JS — весь HTML выносить в templates/*.hbs;
• Не оставлять неиспользуемые переменные, функции и обработчики событий;
• Нельзя оставлять закомментированный код (комментарии к коду - можно);
• Не оставлять: eval, prompt, confirm, alert, console.*;
• Для элементов форм в шаблонах можно использовать CSS-классы платформы: input, textarea, select-base, checkbox, button.