Углубленное изучение АПИ плагинов Р7-Офис
Занятие 3
Особенности работы АПИ плагина
Инициализация плагина
При загрузке плагина, ядро редактора производит поиск и в случае успеха инициализирует плагин. Для успешной инициализации редактору требуется наличие в составе загруженного базового скрипта плагина специальной функции window.Asc.plugin.init. Если в конфигурационном файле config.json настроены параметры initData и initDataType, то в качестве аргумента функции будут переданы данные указанного типа, которые можно обработать.

Кроме функции window.Asc.plugin.init, к числу рекомендуемых относится ещё и функция window.Asc.plugin.button, которая служит для обработки срабатывания кнопок плагина. Эти кнопки должны быть описаны в разделе buttons того же конфигурационного файла. Однако, наличие этой функции не столь принципиально, особенно если такие кнопки не использовались в составе плагина.

Также может понадобиться функция перевода интерфейса плагина window.Asc.plugin.onTranslate. Однако, если локализация не требуется, то можно отказаться от использования данной функции.

Пример реализации:

// Инициализация плагина
window.Asc.plugin.init = function(initData) {
    // Обработка данных, переданных при инициализации (если есть)
    if (initData) {
        console.log("Init data:", initData);
    }
    // Основная логика инициализации плагина
    console.log("Plugin initialized");
};

// Обработка нажатия кнопок плагина
window.Asc.plugin.button = function(id) {
    switch (id) {
        case 'button1':
            console.log("Button 1 clicked");
            break;
        case 'button2':
            console.log("Button 2 clicked");
            break;
        default:
            console.log("Unknown button clicked");
    }
};

// Перевод интерфейса плагина
window.Asc.plugin.onTranslate = function() {
    // Пример перевода текстовых элементов интерфейса
    document.getElementById("label1").innerText = window.Asc.plugin.tr("Label 1");
    document.getElementById("button1").innerText = window.Asc.plugin.tr("Button 1");
};

// Закрытие плагина
window.Asc.plugin.onShutdown = function() {
    console.log("Plugin shutdown");
};
Вывод:

Если редактор Р7-Офис при загрузке обнаруживает функцию window.Asc.plugin.init, он передает ей управление. В дальнейшем логика работы плагина должна идти от этой функции. Дополнительные функции, такие как window.Asc.plugin.button для обработки нажатий кнопок и window.Asc.plugin.onTranslate для локализации интерфейса, могут быть добавлены по мере необходимости.

Функция инициализации window.Asc.plugin.init и JQuiery
Функция window.Asc.plugin.init является точкой входа. В ней желательно произвести инициализацию обработчиков событий для контролов и затем произвести вызов функции с логикой работы плагина.

При использовании JQuery инициализацию плагина рекомендуется производить в нем. Для этого можно использовать специальную функцию инициализации:

Код:

//Область инициализации обработчиков jQuery
$(function() { 
 //Обработчик нажатия на контрол с id="id_control"
 $("#id_control").click(function(){            
 //Какие то действия внутри обработчика
 });
 …следующий обработчик и т.д.
});   
Функция $(function(){…}); срабатывает только после загрузки всего HTML файла со всеми определениями контролов, благодаря чему обработчики обязательно свяжутся с контролами. В противном случае возможны ситуации, при которой в window.Asc.plugin.init() начнется привязка кода обработчиков ещё до окончания формирования всего DOM дерева листа HTML, и часть кода привязки не будет выполнена.

В коде функции window.Asc.plugin.init() следует произвести присвоение начальных значений для тех контролов, которые этого требуют в начальной фазе, сразу после загрузки плагина. Это могут быть значения для текстовых полей, начальные значения в комбо-списках или в группе radiobutton контролов и чекбоксов. Делается это средствами jQuery.

Значение для текстового поля:
$("#text_field").val("Значение поля");

Установка чекбокса:
$("#check_cntrl").prop("checked",true);

Поля комбобокса:
$("#select_cntrl").append(
$("<option>", {
value: 1,
text: "Значение 1",
});
);

Динамическое изменение панели плагина с помощью JQuery
Возможно динамическое изменение панели плагина с помощью JQuery.
Примеры такого изменения приведены ниже:

Пример добавления нового блока div с id=”id_block”:
let str="<div>";
str+="<select id='id_select'>";
str+="<option value=1>Item 1</option>";
str+="<option value=2>Item 2</option>";
str+="<option value=3>Item 3</option>";
str+="</select>";
str+="</div>";
$('#id_block').append(str);

Пример удаления блока:
$('#id_block').children().find('#id_child').remove();

Вывод:

Возможно любое изменение панели плагина в соответствии с логикой его работы.