Переопределяемые и поставляемые объекты библиотеки

Методическая рекомендация (полезный совет)

1. С точки зрения возможностей по настройке функциональности библиотеки для работы в конкретной конфигурации -потребителе все объекты библиотеки условно делятся на три категории:

• Непереопределяемые объекты – «готовые» объекты, которые можно брать и использовать в конфигурации -потребителе «как есть». Их не следует изменять в конфигурации-потребителе, чтобы они были гарантированно одинаковы во всех конфигурациях, основывающихся на данной библиотеке. Более того, такие объекты обязательно должны присутствовать в конфигурациях, использующих библиотеку. Примеры: справочник Пользователи.
• Переопределяемые объекты – «изменяемые» объекты для настройки библиотеки под конкретную конфигурацию. Они могут или должны быть изменены в конфигурации-потребителе. Могут поставляться с базовой реализацией. С помощью таких объектов решаются задачи изменения поведения библиотечной функциональности, ее параметризации спецификой конфигурации-потребителя, а также для подключения библиотечной функциональности к объектам конфигурации-потребителя.
• Определители типов – объекты-« классификаторы », которые не имеют базовой реализации. Предназначены для формирования единого пространства имен в конфигурациях, а реализация при этом может как угодно сильно различаться в конфигурациях-потребителях. Например: справочники-классификаторы, в которых определено только «название»; сущность «организация» должна быть везде представлена справочником с именем Организации и т.п.

2. Рекомендуется устанавливать для объектов этих категорий следующие правила поставки:

• Непереопределяемые объекты – «изменения не рекомендуются»;
• Переопределяемые объекты и определители типов – «изменения разрешены».

Эти рекомендации продиктованы следующими соображениями:

• Непереопределяемые объекты – это зона ответственности разработчиков библиотеки, поэтому они не должны разрабатываться «по месту» в конфигурациях-потребителях. Но если необходимость изменений носит срочный характер (например, исправление критичной ошибки) или продиктована какими-то другими особыми соображениями, то допускается вносить изменения в непереопределяемые библиотечные объекты непосредственно в конфигурациях-потребителях. При этом нужно иметь в виду, что эти изменения могут быть потеряны при следующем обновлении версии библиотеки в конфигурации-потребителе, если не принять специальные меры (донести до разработчиков библиотеки необходимость внесения изменений или задокументировать этот отход от общей инструкции по обновлению библиотеки).
• Переопределяемые объекты и определители типы должны или могут быть изменены в конфигурации-потребителе, исходя из их назначения.

3. Для того чтобы упростить настройку библиотеки и снизить трудоемкость последующих обновлений версии библиотеки в конфигурации-потребителе следует минимизировать количество переопределяемых объектов с помощью следующих методик:

• Настройка состава типов переопределяемых реквизитов (свойств) тех или иных объектов библиотеки – для подключения библиотечной функциональности к объектам конфигурации-потребителя.
  Например: можно подключить библиотечную функциональность к конкретным объектам конфигурации с помощью расширения состава типов общей команды, измерения составного типа в регистре сведений и т.п.
• Добавление предопределенных элементов – для параметризации библиотечной функциональности спецификой конфигурации-потребителя.
  Например: для библиотечной подсистемы ведения и обработки контактной информации с помощью предопределенных элементов библиотечного справочника ВидыКонтактнойИнформации можно указать, какие виды контактной информации (телефон, адрес, электронный адрес и т.п.) должны быть предусмотрены для объектов конфигурации-потребителя.
• Переопределяемые общие модули – для изменения поведения библиотечной функциональности в конкретной конфигурации-потребителе
  • с помощью переопределения тех или иных «обработчиков событий», предоставляемых библиотекой; например:
    ПриПодготовкеМакетаОписанияОбновлений()
    ПриЗаписиСпискаБизнесПроцессов()
  • а также для того, чтобы сообщить ту или иную информацию из конфигурации-потребителя в библиотеку. Например:
    ЭтоБазоваяВерсияКонфигурации()
    ОбработчикиОбновления()

3.1. Переопределяемые общие модули следует называть с постфиксом Переопределяемый.

См. также: правила создания общих модулей

3.2. Переопределяемые общие модули должны содержать только экспортные процедуры и функции, которые вызываются из кода самой библиотеки. Другими словами, не следует допускать вызовов процедур и функций переопределяемых модулей непосредственно из кода конфигурации-потребителя.

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

Например, в библиотеке имеются модули ПапкиФайлов и ПапкиФайловПереопределяемый. Для использования в конфигурациях-потребителях в модуле ПапкиФайлов реализуется экспортная функция:

Функция ПапкаФайлов(ВладелецФайловСсылка) Экспорт
	
	СтандартнаяОбработка = Истина;
	Результат =  Неопределено ;
	ПапкиФайловПереопределяемый.ПолучитьПапкуФайлов(ВладелецФайловСсылка, Результат, СтандартнаяОбработка);
	
	Если СтандартнаяОбработка Тогда
		// реализация  по умолчанию 
		Результат = ...
	КонецЕсли;
	Возврат Результат;
	
 КонецФункции 

а в модуле ПапкиФайловПереопределяемый:

// Вызывается из библиотеки при необходимости получить папку файлов для указанного владельца.
//
// Параметры:
// ВладелецФайловСсылка – владелец файлов, для которого нужно вернуть папку.
// ПапкаФайлов – в этот параметр нужно записать результат. 
// СтандартнаяОбработка – по умолчанию, Истина. В этом случае папка будет получена способом по умолчанию. 
// Если значение параметра установить в Ложь, то в этой процедуре можно реализовать свой способ, 
// которым в конфигурации получают папки файлов.
// 
Процедура ПолучитьПапкуФайлов(ВладелецФайловСсылка, ПапкаФайлов, СтандартнаяОбработка) Экспорт
 КонецПроцедуры 

При этом все вызовы из конфигурации-потребителя должны идти только к библиотечному модулю ПапкиФайлов. Обращение к ПапкиФайловПереопределяемый разрешается только из библиотечного модуля ПапкиФайлов.

3.3. При этом в переопределяемом модуле не должно быть каких-либо других не-экспортных процедур/функций и какой-либо реализации в его экспортных процедурах и функциях. Базовую реализацию переопределяемых процедур и функций следует располагать в непереопределяемом коде.

Например, неправильно поставлять переопределяемый модуль МояБиблиотекаПереопределяемый скакой-либо реализацией:

Функция НастройкаПараметровРаботы() Экспорт
	
	ПараметрыРаботы = Новый Структура;
	// если настройки по умолчанию не подходят, то измените их. 
	ПараметрыРаботы.Вставить("ПоказыватьЕдинственныйРаздел", Ложь);
	ПараметрыРаботы.Вставить("ЗадаватьДатуДляПрочихРазделов", Ложь);
	ПараметрыРаботы.Вставить("ИспользоватьВнешнихПользователей", Ложь);
	Возврат ПараметрыРаботы;
	
КонецФункции

правильно:

// Позволяет настроить работу подсистемы.
//
// Параметры:
// ПараметрыРаботы - Структура, с полями:
// ПоказыватьЕдинственныйРаздел - Булево (по умолчанию Ложь),
// ЗадаватьДатуДляПрочихРазделов - Булево (по умолчанию Ложь),
// ИспользоватьВнешнихПользователей - Булево (по умолчанию Ложь).
Процедура НастройкаИнтерфейса(ПараметрыРаботы) Экспорт
КонецПроцедуры

а установку значений по умолчанию перенести в непереопределяемый общий модуль библиотеки:

Функция НастройкаПараметровРаботы()
	
	ПараметрыРаботы = Новый Структура;
	// настройки по умолчанию
	ПараметрыРаботы.Вставить("ПоказыватьЕдинственныйРаздел", Ложь);
	ПараметрыРаботы.Вставить("ЗадаватьДатуДляПрочихРазделов", Ложь);
	ПараметрыРаботы.Вставить("ИспользоватьВнешнихПользователей", Ложь);
	
	// а теперь запросим конфигурацию-потребитель на случай, 
	// если эти умолчания не устраивают
	МояБиблиотекаПереопределяемый.НастройкаПараметровРаботы(ПараметрыРаботы);
	Возврат ПараметрыРаботы;
	
КонецФункции

3.4. При обновлении версии библиотеки в конфигурации-потребителе особого внимания требуют модули корневого объекта конфигурации и переопределяемые общие модули, так как автоматическое обновление таких «узких мест» конфигурации-потребителя невозможно. Для настройки в конфигурации переопределяемых общих модулей рекомендуется придерживаться общего подхода:

• При первой настройке переопределяемого общего модуля следует ознакомиться с документацией к его экспортным процедурам и функциям, приведенной в комментариях к ним. И при необходимости вписать реализацию в экспортные процедуры и функции модуля.
• При каждом обновлении переопределяемого общего модуля требуется перенести новые экспортные процедуры и функции, удалить устаревшие и убедиться, что комментарии, количество и имена параметров у всех функций совпадают с их библиотечными эквивалентами. При необходимости вписать реализацию в новые экспортные процедуры и функции модуля, а также актуализировать реализацию уже существующих функций, если в новой версии библиотеки было изменено их назначение или состав параметров.

См. также

• Переопределение общих модулей в условиях иерархии библиотек