Разработка плагинов для модуля доставки «API-1C»
Версия МОДУЛЯ 2.17
Модуль доставки «API-1C» (далее — Модуль) версии ПРО поддерживает работу с плагинами. Плагины – это внешние обработки 1С:Предприятия, содержащие программный код, который вызывается из Модуля в определённые моменты его работы (далее — Хуки). Данная документация описывает все возможные Хуки, параметры, которые могут быть в них переданы, возвращаемые данные и возможности по использованию.
Замечания по работе плагинов
- Обработка плагинов выполняется внутри попытки. Если обработка не удалась, в журнал регистрации записывается соответствующее сообщение.
- Плагины подключаются модулем автоматически, разработчику плагина не нужно выполнять никаких дополнительных действий для этого.
- Рекомендуется делать отдельный плагин для отдельной логической функции. Особенно не рекомендуется смешивать функции, подключающие разные хуки, т.к. это влияет на время работы модуля.
- Разработчик плагина имеет доступ к структуре и данным модуля, что можно использовать для вредоносных действий. Не используйте плагины, источник которых Вам не известен! Мы работаем над созданием магазина плагинов, где будут содержаться только проверенные плагины.
Подключение плагина
Для подключения плагина он должен быть вначале добавлен как дополнительные обработка. Подробнее о том, как это сделать, читайте в документации к Вашей конфигурации. После того, как плагин был добавлен в дополнительные обработки, зайдите в настройки Модуля и перейдите на страницу Плагины. В таблице плагинов добавьте новую строку. В поле Доп.обработка выберите Ваш плагин. В поле Включён установите флажок. Сохраните настройки. Если плагин работает с формой настроек Модуля, то для того, чтобы его работа отразилась на форме настроек, эта форма после подключения плагина должна быть закрыта, а затем открыта вновь.
Структура плагина
Плагин – это внешняя обработка 1С:Предприятия. Минимальный программный код, который необходим, чтобы Модуль распознал такую обработку, как Плагин, это:
- Программный код, который позволяет подключить обработку как дополнительную обработку в конфигурациях, разработанных на базе БСП. О том, что такое БСП, механизм дополнительных обработок и что нужно, чтобы создать такую обработку, можно узнать на сайте 1С.
- Функция «ЭтоПлагин», экспортная, без параметров, возвращает Истина
- Функция «Назначение», экспортная, без параметров. Возвращает Структуру. Имена полей структуры являются именами форм Модуля, либо «_Модуль», если плагин должен обрабатывать какие-то общие хуки. Ключи – это Структура, которая содержит имена хуков, которые обрабатываются данным плагином. Пример функции:
Функция Назначение() Экспорт
прСтр = Новый Структура;
// модуль обрабатывает хук ОбновлениеСтатусов, не привязанный к формам
прСтр.Вставить(«_Модуль», Новый Структура(«ОбновлениеСтатусов»));
// модуль обрабатывает хук ПриСозданииНаСервере в форме Settings
прСтр.Вставить(«Settings», Новый Структура(«ПриСозданииНаСервере»));
// модуль обрабатывает хуки ПослеЗаполненияДанными
// и ПриСозданииНаСервере в форме Order
прСтр.Вставить(«Order», Новый Структура(«ПослеЗаполненияДанными, ПриСозданииНаСервере»));
Возврат прСтр;
КонецФункции
- Функция «Обработать», экспортная. Параметры:
Хук – Строка, <имя формы или «_Модуль»>_<имя хука>.
Параметры – Необязательный, Структура, поля зависят от обрабатываемого хука. Возможные параметры будут показаны в разделе с описанием хуков.
Данная функция выполняет саму обработку всех поддерживаемых хуков. Пример:
Функция Обработать(Хук, Параметры = Неопределено) Экспорт
Если Хук = «Settings_ПриСозданииНаСервере» Тогда
Settings_ПриСозданииНаСервере(Параметры.Форма);
ИначеЕсли Хук = «_Модуль_ОбновлениеСтатусов» Тогда
_Модуль_ОбновлениеСтатусов(Параметры);
ИначеЕсли Хук = «Order_ПриСозданииНаСервере» Тогда
Order_ПриСозданииНаСервере(Параметры);
КонецЕсли;
КонецФункции
Обрабатываемые хуки
Примечание: Параметры – это Структура, передаваемая в функцию «Обработать». В колонке Параметры описаны поля этой структуры, а не параметры функции. Например, если описан параметр Форма, то обратиться внутри функции к ней можно через Параметры.Форма.
_Модуль
| Имя | Параметры | Возвращаемое значение | Описание |
| ОбновлениеСтатусов |
|
нет | Выполняется после обновления статуса. Можно использовать для оповещений об изменении статуса и любых других действий, связанных с изменением статуса заказа в доставке. Заказы, статусы которых не изменились, не обрабатываются. |
Settings
| Имя | Параметры | Возвращаемое значение | Описание |
| ПриСозданииНаСервере | Форма – сама форма Settings | Нет |
Выполняет доработку формы. У данной формы есть поле «мДанныеПлагинов», тип Структура, обязательные поля «Реквизиты» (тип Структура) и «Таблицы» (тип Структура), куда нужно добавлять данные, которые нужно сохранять в настройках модуля.
В данном хуке можно добавлять свои элементы, и дорабатывать существующие. НЕ рекомендуется удалять или изменять функционал существующих элементов. |
Order
| Имя | Параметры | Возвращаемое значение | Описание |
| ПриСозданииНаСервере |
Форма – сама форма Order. В частности содержи таблицу «Заказы», где колонка «Заказ» содержит ссылку на документ. Может содержать несколько заказов, если форму открыли для нескольких выделенных заказов.
Настройки – структура, содержит все настройки модуля. В частности содержит поля с именами, соответствующими полям модуля (внешней обработки Api1C.epf). В них УИДы доп.сведений, в которых хранятся значения полей модуля для документа. |
Нет |
Выполняет доработку формы отправки заказов.
В данном хуке можно добавлять свои элементы, и дорабатывать существующие, а также выполнять предварительную подготовку данных 1С для работы с модулем (передавать данные нетиповых реквизитов в реквизиты модуля и т.д.). Если данные, которые нужно заполнить или изменить, известны до открытия модуля, рекомендуется использовать именно этот хук. На момент выполнения, данные модуля ещё не заполнены и не обработаны. НЕ рекомендуется удалять или изменять функционал существующих элементов. |
| Плагины_ПослеОтправкиЗаказа | Форма – сама форма Order | Нет |
Выполняется после того, как отправлены все заказы в таблице Заказов модуля. Если заказ не был отправлен по причине ошибок, событие всё равно будет вызвано. Вне зависимости от количества отправляемых заказов, вызывается один раз после попытки отправки всех заказов.
В данном хуке рекомендуется вызывать механизмы в базе 1С, которые нужно запускать после отправки заказов. НЕ рекомендуется удалять или изменять функционал существующих элементов, а также разблокировать заблокированные элементы формы. |
| ПослеЗаполненияДанными (начиная с 2.15.6) | Форма – сама форма Order | Нет |
Выполняется после того, как форма полностью заполнена.
В данном хуке можно выполнять изменение заполненных значений по своим данным (подставлять другие ПВЗ или адреса, изменять информацию о местах и т.п.). На момент выполнения данные модуля уже заполнены и обработаны. НЕ рекомендуется удалять или изменять функционал существующих элементов. |
| ПослеИзмененияПоляСлужбыДоставки (начиная с 2.15.6) | Форма – сама форма Order | Нет |
Выполняется после того, как на форме перевыбрана служба доставки.
В данном хуке можно выполнять перезаполнение данных, зависящих от службы доставки. НЕ рекомендуется удалять или изменять функционал существующих элементов. |
Примеры
Заполнение полей модуля своими значениями
Самый простой способ выполнить такую задачу – при открытии формы модуля записать значения полей в соответствующие доп.сведения:
Функция Обработать(Хук, Параметры = Неопределено) Экспорт
Если Хук = «Order_ПриСозданииНаСервере» Тогда
Order_ПриСозданииНаСервере(Параметры);
КонецЕсли;
КонецФункции
Функция СсылкаПВХ(УИД)
Возврат ПланыВидовХарактеристик.ДополнительныеРеквизитыИСведения.ПолучитьСсылку(Новый УникальныйИдентификатор(УИД));
КонецФункции
Функция Order_ПриСозданииНаСервере(Параметры) Экспорт
прСвойствоТелефон = СсылкаПВХ(Параметры.Настройки.ТелефонОтправителя);
// Функция ниже показана как пример, её вам нужно реализовать
// самостоятельно. Например, запросом получить телефон из
// какого-то регистра сведений или нетипового реквизита.
// В параметр функции мы для примера передали ссылку на первый
// заказ в таблице заказов.
прНовыйТелефон = ТелефонОтправителяИзПроизвольногоИсточника(Параметры.Форма.Заказы[0].Заказ);
// Функция ниже показана как пример, её вам нужно реализовать самостоятельно.
// Она должна записать доп.сведение в соответствующий регистр сведений для
// заказа.
ЗаписатьСвойствоВРегистр(Параметры.Форма.Заказы[0].Заказ, прСвойствоТелефон, прНовыйТелефон);
КонецФункции