Event subscriptions

docs/ПодпискиНаСобытия.md

@@ -1,23 +1,65 @@
-# Подсистема "подписки на события"
+# Подсистема "Подписки на события"
 
 Подписки на события применяются для реализации дополнительной постобработки или проверок, которые активируются после определённых событий в типовых объектах или модулях менеджера.
 В случае отстутствия типовой подписки, используется подсистема **"Подписки на события"**. Если нужно внести изменения в типовую логику работы подписки, используется заимствование методов в расширении с аннотацией &ИзменениеИКонтроль.
 
+Общая структура подписок на события:
+ - Для каждого класса **общий модуль** (пример: "пбп_ДокументыОбработчики")
+   - В каждом общем модуле распологаются процедуры-обработчики класса (пример: "пбп_ДокументыОбработкаПроведения", "пбп_СправочникиПриЗаписи")
+   - В области **СлужебныйПрограммныйИнтерфейс** добавляются одноименные процедуры (пример: "СписаниеБезналичныхДенежныхСредствПриЗаписи")
+   - В общем модуле **пбп_ОбщегоНазначенияПовтИсп** добавить в соответствие тип объекта и вызываемую процедуру в одноименной функции  **(Указывать только имя процедуры!)** 
+
 Порядок действий при работе с подсистемой:
- - Необходимо проверить, существует ли общая подписка на нужный тип объекта и событие. Например: **ДокументОбработкаПроведения**, **СправочникПриЗаписи** и так далее.
-Недопускается смешение типов объектов и событий в одной подписке. Если подписки не существует, нужно её добавить, а так же общий модуль с аналогичным названием (напр. **пбп_ДокументыОбработкаЗаполнения** - и подписка, и общий модуль).
+ - Необходимо проверить, существует ли общая подписка на нужный тип объекта и событие. Например: **пбп_ДокументыОбработкаПроведения**, **пбп_СправочникиПриЗаписи** и так далее.  
+Недопускается смешение типов объектов и событий в одной подписке. Если подписки не существует, нужно её добавить, а так же общий модуль с аналогичным названием (напр. **пбп_ДокументыОбработчики** - и подписка, и общий модуль).
 Добавить их в подсистему **пбп_ПодпискиНаСобытия**.
  - Если создана новая подписка и модуль, то в модуле создается обработчик для подписки и выбрать его в подписке. У каждого события свой набор параметров.
+ - Структура общего модуля обработчиков:
+   - В области **СлужебныйПрограммныйИнтерфейс** располагать обработчики объектов, в ней располагаются подобласти по обработчикам. Допустимо добавлению произвольных областей внутри **СлужебныйПрограммныйИнтерфейс**, для группировки по подсистемам.
+```1C (BSL)
+#Область ПрограммныйИнтерфейс
+
+Процедура ПередЗаписью(Источник, Отказ, РежимЗаписи, РежимПроведения) Экспорт
+КонецПроцедуры
+
+Процедура ПриЗаписи(Источник, Отказ) Экспорт
+КонецПроцедуры
+
+#КонецОбласти
+
+#Область СлужебныйПрограммныйИнтерфейс
+
+// Добавить процедуры обработчиков объектов в эту область
+
+#Область ПередЗаписью
+#КонецОбласти
+
+#Область ПриЗаписи
+
+Процедура СписаниеБезналичныхДенежныхСредствПриЗаписи(Источник, Отказ) Экспорт
+КонецПроцедуры
+
+#КонецОбласти
 
+// Конец добавления
+
+#КонецОбласти
+
+#Область СлужебныеПроцедурыИФункции
+
+#КонецОбласти
+```
+
+**Пример обработчика общего модуля "пбп_ДокументыОбработчики":**
 ```1C (BSL)
-Процедура ДокументыОбработкаПроведения(Источник, Отказ, РежимПроведения) Экспорт
-    // Опустить обработку, если есть отказ или идёт загрузка обмена данными
+Процедура ПриЗаписи(Источник, Отказ) Экспорт
+
     Если Отказ Или Источник.ОбменДанными.Загрузка Тогда
         Возврат;
     КонецЕсли;
 
     // Получение имени метода для исполнения
-    ИмяМетода = юр_ОбщегоНазначенияПовтИсп.ДокументыОбработкаПроведения().Получить(ТипЗнч(Источник));
+    ИмяМетода = пбп_ОбщегоНазначенияПовтИсп.ДокументыПриЗаписи().Получить(ТипЗнч(Источник));
 
     // Выполнение метода, если он определён
     Если ЗначениеЗаполнено(ИмяМетода) Тогда
@@ -26,7 +68,6 @@
             ПараметрыМетода = Новый Массив;
             ПараметрыМетода.Добавить(Источник);
             ПараметрыМетода.Добавить(Отказ);
-            ПараметрыМетода.Добавить(РежимПроведения);
             ОбщегоНазначения.ВыполнитьМетодКонфигурации(ИмяМетода, ПараметрыМетода);
         Исключение
             // В случае ошибки вывод информации о ней
@@ -36,19 +77,28 @@
 КонецПроцедуры
 ```
 
- - В общем модуле **пбп_ОбщегоНазначенияПовтИсп** найти функцию с названием объекта и события и добавить в соответствие тип объекта и вызываемую процедуру. Если функции для данного набора нет, создать её.
+ - В общем модуле **пбп_ОбщегоНазначенияПовтИсп** найти функцию с названием объекта и события и добавить в соответствие тип объекта и вызываемую процедуру **(Указывать только имя процедуры!)**. Если функции для данного набора нет, создать её, перед возвратом добавить вызов заранее созданной процедуры:  
 
+**Пример вызова процедуры для заполнения соответствия:**
 ```1C (BSL)
-Функция ДокументыОбработкаПроведения() Экспорт
+Процедура ОбработатьСоответствие<ИмяКласса>(Соответствие)
+    ЗаполнитьПолныеПутиВызоваМетодов(<ИмяОбщегоМодуля>, Соответствие);
+КонецПроцедуры
+```
+
+**Пример заполнения соответствия типа объекта и вызываемой процедуры:**
+```1C (BSL)
+Функция ДокументыПриЗаписи() Экспорт
     Соответствие = Новый Соответствие;
+
     // Добавление соответствий между типами объектов и методами
     Соответствие.Вставить(Тип("ДокументОбъект.СписаниеБезналичныхДенежныхСредств"),
-        "юр_ДокументыОбработкаПроведения.СписаниеБезналичныхДенежныхСредств");
+        "СписаниеБезналичныхДенежныхСредствПриЗаписи");
     Соответствие.Вставить(Тип("ДокументОбъект.ПоступлениеБезналичныхДенежныхСредств"),
-        "юр_ДокументыОбработкаПроведения.ПоступлениеБезналичныхДенежныхСредств");
-
+        "ПоступлениеБезналичныхДенежныхСредствПриЗаписи");
+    // КонецДобавления
+
+    ОбработатьСоответствиеДокументы(Соответствие);
     Возврат Соответствие;
 КонецФункции
 ```
-
-- В модуле объекта и события добавить экспортную процедуру с такими же параметрами как у основной и добавить необходимую логику.