Amocrm создание виджета

Для начала создадим структуру виджета.
Структура виджета очень проста. Обязательные файлы script.js, manifest.json, папки images и  локализации i18n.


Добавим виджет в Настройки — Api — Добавить виджет. Статус поставить надо private для локального тестирования.

1. Начнем с manifest.json.
«widget» — описание виджета
«locations» — страницы где будем отображать виджет.
«settings» — настройки виджета при его активации/деактивации на стр. Настройки — «Интеграции».

А теперь подробнее про каждый пункт. Не забудьте, Json не должен содержать комментарии!

amocrm_widget/manifest.json


"widget":{
"name": "widget.name", // название виджета, любое, перевод в i18n/ru.json
"description": "widget.description", // описание, там же где и название
"short_description": "widget.short_description", // см. выше
"code": "sample", // код, указывается при создании на стр. Настройки - Api - Добавить виджет
"secret_key": "2ee2e38c5fc2c8cfa1d1964b6a90f8475ccf4666bbaf68b800463fc90433b5c8", // там же
"version": "1.0.0", // любая
"interface_version": 2, // по умолч. 2
"init_once": false, // колбеки init() и bind_actions() не будут вызываться каждый раз при обновл. стр. при false
"locale":[
"ru",
"en"
],
"installation": true // установка, оставлю true чтобы показать настройки виджета при установке
},

"locations":[
"lcard-0", // выведем на деталь. стр. лида, 0 значит не отображать в правой колонке.
"settings" // выводим на стр. настроек виджета, при его установке. Здесь оно обязательно т.к. мы указали "installation": true
],

"settings":{
"api_key":{
"name": "settings.api_key",
"type": "text",
"required": true
}, // укажу поле ключ апи как обязательное. Описание в файле переводов i18n/ru.json4
"agreement":{
"name": "settings.agreement",
"type": "custom",
"required": true
}, // а также чекбокс "Согласие с правами", тип у него кастомный, обращаться к нему надо будет в script.js в колбеке settings

2. Вся логика в script.js. Рассмотрим его поподробнее.
Вначале идет объявление библиотек, к-е мы подключаем в стиле Require.js


define(['jquery', 'lib/components/base/modal'], function ($, Modal) {

Я подключил jquery и Модалку от амо.
Далее конструктор var CustomWidget = function () {} Он идет с предустановленными колбеками, к-е должны возвращать true.


this.callbacks = {
settings: function () {}
dpSettings: function () {}
init: function () {}
bind_actions: function () {}
render: function () {}
onSave: function () {}
}

Из всех колбеков по идее можно использовать только render, а остальные оставить пустыми. Тем не менее рассмотрю некоторые подробнее.

settings — колбек срабатывает при открытии мод. окна настроек виджета. Это делается на стр. Настройки — «Интеграции», далее находим наш виджет — обычно он в самом конце. Появляется модалка с настройками.



В нашем случае это поле «Ключ апи» и кастом. тип «Согласие», к-й мы должны определить (подробнее в https://developers.amocrm.ru/widgets/custom_settings.php) Обратиться к нему можно по id <код вижета>_custom_content, у нас это sample_custom_content.


this.callbacks = {
settings: function () {
if (AMOCRM.lang_id == "ru") {
// чекбокс
$("#sample_custom_content").html("<label><input type='checkbox' name='agreement' value='1'/>согласие с условиями</label>").parent().show()
}
}
}

Наконец колбек render — это как раз тот момент когда виджет отображается на странице. Тут весь костяк виджета. По умолчанию предоставляются методы объекта widget

render(), render_template(), set_lang(), set_settings(), list_selected(),  widgetsOverlay(), add_action(), set_status(), crm_post(url, data, callback, type, error)

, из которых реально используются render(), render_template(), а также crm_post(). Заметьте, названия первых 2-х совпадают с названием колбека, что поначалу может запутать. Эти 2 метода являются обертками методов twig.js. https://github.com/twigjs/twig.js/wiki Итак, эти методы:



self.render({
data : template // тут разметка twig, переменные к-й будут заменены
},
{
names: params // тут эти самые переменные, к-е передаем в шаблон
})

var params = [
{name:'name1',
id: 'id1'},
{name:'name2',
id: 'id2'},
{name:'name3',
id: 'id3'}
]; //массив данных, передаваемых для шаблона

var template = '<div><ul>'+
'{% for person in names %}'+
'<li>Name : {{ person.name }}, id: {{ person.id }}</li>'+
'{% endfor %}'+
'</ul></div>';

Вместо куска кода можно передать системный шаблон amocrm. Ссылку на шаблон указываем индексом ref


self.render(
{
ref: '/templates/select.twig'
},
{
names: params
}
)

Системные шаблоны:

textarea, suggest, select, radio, multiselect, date_field, checkbox, checkboxes_dropdown, file, button, cancel_button, delete_button, input

Используем свой шаблон. Закину его в templates/doc.twig . Ссылка на шаблон в индексе href передаваемого объекта.


self.render({
href:'templates/doc.twig', //путь до шаблона
base_path: self.params.path; //базовый путь до директории с виджетом
load: callback //вызов функции обратного вызова произойдет только если шаблон существует и загружен
}, params)

Давайте рассмотрим еще мод. окно и вынесим рендеринг шаблона в отд. ф-ю getTemplate()
Модалка подробно описана тут
https://developers.amocrm.ru/widgets/js_sdk.php
Вынесу код модалки в отд. ф-ю

amocrm_widget/script.js


self.openModal = function (data) {
// Modal
modal = new Modal({
class_name: 'modal-window',
init: function ($modal_body) {
var $this = $(this);
$modal_body
.trigger('modal:loaded') //запускает отображение модального окна
.html(data)
.trigger('modal:centrify') //настраивает модальное окно
.append('<span class="modal-body__close"><span class="icon icon-modal-close"></span></span>');
},
destroy: function () {}
});
}

Вынесу рендеринг шаблона в отд. ф-ю, как описано в док-ии амосрм.
https://developers.amocrm.ru/widgets/script_js.php


self.getTemplate = function (template, params, callback) {
params = (typeof params == 'object') ? params:{};
template = template || '';

return self.render({
href:'/templates/' + template + '.twig',
base_path:self.params.path, //тут обращение к объекту виджет вернет /widgets/#WIDGET_NAME#
load: callback //вызов функции обратного вызова
}, params); //параметры для шаблона
}

Добавлю кнопку в контекст. меню там, где многоточие рядом с названием лида. При нажатии на нее и появиться наше всплывающее окно.


self.getTemplate('button', {}, function(data){
$('.button-input-more .button-input__context-menu').prepend(data.render());
});

Шаблон кнопки создам отдельно.

amocrm_widget/templates/button.twig


<li class="button-input__context-menu__item element__basket " id="modal123">
<div class="button-input__context-menu__item__inner">

<span class="button-input__context-menu__item__icon icon icon-inline"></span>

<span class="button-input__context-menu__item__text">
Модалка
</span>

</div>
</li>

Событие для кнопки


$(document).off('click', '#modal123');
$(document).on('click', '#modal123', function(event) {
event.stopPropagation();
event.preventDefault();

self.openModal("<div>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ullam nisi maiores omnis, aliquam qui. Accusantium, minima aliquid. Repudiandae, cum nostrum expedita voluptatibus, provident quo. Ab, suscipit, ullam! Ad, laborum at!</div>")
});

Вот собственно и все. Запросы к удал. серверу делать не буду, думаю и так разберетесь.

Метод render_template() идентичен render(), только выводит содержимое в правой колонке.
Не забудьте при обновлении виджета чистить кеш, кеширует жестко.

3. Архивируем наш виджет как widget.zip Лишних символов тут быть не должно. Далее загружаем виджет. Вуаля!

Настоятельно рекомендую прочитать про ошибки

Типовые ошибки

  • Т.к. многие файлы, в частности manifest.json имеют формат json, то лучше перед их загрузкой убеждаться в корректности синтаксиса используя онлайн проверки json файлов. Одной из самых частых ошибок является загрузка файла с некорректным синтаксисом
  • Кодировка — все файлы должны быть в кодировке UTF-8 без BOM
  • Уже перед первой загрузкой виджета в манифесте необходимо заменить код и ключ из сказанного примера на сгенерированные вами уникальные
  • Зачастую в упакованном архиве в корне лежит папка widget, как первый уровень, а на самом деле должны уже сразу лежать файлы
  • Если изначально был загружен неверный manifest, то необходимо сгенерировать новый код и ключ, т.к. предыдущий будет дескредитирован

В гите https://github.com/vaajnur/amocrm_widget

Leave a comment

Your email address will not be published.


*