Overridable and built-in library objects

Scope: managed applications, mobile applications, and ordinary applications.

1. Depending on options to set up library functionality for a specific end user configuration, all library objects are divided into the following three categories:

  • Non-overridable objects are ready-to-use objects that you can use in an end user configuration. Do not change them in the end user configuration to ensure that these objects are identical in all configurations based on this library. Make sure that these objects are included in configurations that use the library. For example, the Users catalog. 
  • Overridable objects are changeable objects used to set up a library for a specific configuration. These objects can or must be changed in an end user configuration. Use such objects to change the behavior of library functionality, parameterize it based on end user configuration specifics, and attach library functionality to end user configuration objects.
  • Type identifiers are classifying objects without the basic implementation. They are used to generate a unified namespace in configurations. The implementation in end user configurations might be significantly different. For example, classifying catalogs where only a name is specified, and the "company" entity is to be always represented by a catalog with the Companies name, and so on.

2. It is recommended that you set the following delivery rules for objects of these categories:

  • For non-overridable objects, "changes are not recommended".
  • For overridable objects and type identifiers, "changes are allowed".

These recommendations are dictated by the following considerations:

  • Non-overridable objects are under responsibility of library developers. Therefore, such objects are not to be developed in end user configurations. If changes are required urgently, for example, you need to correct a critical error, or there are some other reasons, you can change non-overridable library objects directly in an end user configuration. Note that these changes might be lost upon the next library version update in the end user configuration. To avoid this, notify library developers of the necessary changes or document this deviation from the general library update instruction.
  • Change overridable objects and type identifiers in the end user configuration depending on their purpose.

3. To make library setup easier and reduce the time needed to update the library version in the end user configuration, minimize the number of overridable objects using the following methods:

  • Configure the set of types of overridable attributes or properties related to particular library objects to attach library functionality to end user configuration objects.
    For example, you can attach library functionality to configuration objects by expanding the set of common command types, a dimension of the composite type in an information register, and so on.
  • Add predefined items to parameterize library functionality based on end user configuration specifics.
    For example, for the library subsystem of keeping and processing contact information, using predefined items of the ContactInformationKinds library catalog, you can specify which contact information kinds (phone, address, email, and so on) end user configuration objects need to have.
  • Use overridable common modules to change the library functionality behavior in the end user configuration: 
    • By overriding event handlers provided by the library, for example:
      OnPrepareUpdatesDetailsTemplate
      OnWriteBusinessProcessesList
    • To pass information from the end user configuration to the library, for example,
      OnDetermineBaseConfigurationVersion
      OnAddUpdateHandlers

3.1. Name common overridable modules using the Overridable postfix.

See also: Rules of creating common modules

3.2. Common overridable modules must contain only export procedures that are called from the library code. In other words, procedures of overridable modules are not to be called directly from the end user configuration.

Such restriction is required to increase resiliency of the configuration code, which calls library procedures and functions included in the library API. Include only export procedures and functions of non-overridable common modules in the library API.

For example, the library includes the FilesFolders and FilesFoldersOverridable modules. For using in end user configurations, an export function is implemented in the FilesFolders module:

Function FilesFolder(FilesOwnerRef) Export

  StandardProcessing = True;
  Result = Undefined;
  FilesFoldersOverridable.OnGetFilesFolder(FilesOwnerRef, Result, StandardProcessing);

  If StandardProcessing Then
    // Implementation by default
    Result = ...
  EndIf;
  Return Result;

EndFunction

In the FilesFoldersOverridable module, the OnGetFilesFolder handler is implemented:

// Called from the library if it is required to get a file folder for the specified owner.
//
// Parameters:
//  FilesOwnerRef - AnyRef                  - a file owner, for which the folder is to be returned.
//  FilesFolder          - CatalogRef.FilesFolders - write the result to this parameter.
//  StandardProcessing - Boolean                       - by default, True. In this case, the folder is got using the default method.
// If the parameter value is set to False, in this procedure, you can implement your own method
// used in the configuration to get file folders.
//
Procedure OnGetFilesFolder(FilesOwnerRef, FilesFolder, StandardProcesing) Export

EndProcedure

All calls made from the end user configuration must refer only to the FilesFoldes library module. You can access the FilesFoldersOverridable module only from the FilesFolders library module.

3.3. In the overridable module, you need to place only export procedures with the empty implementation. The module must not contain any other non-export procedures or functions. You need to place the base implementation of overridable procedures and functions in the non-overridable code.

This restriction is required to reduce the time needed to update overridable modules in the end user configuration in the future.
For example, it is incorrect to supply the MyLibraryOverridable overridable module with any implementation:

Function SetUpOperationParameters() Export
 
 OperationParameters = New Structure;
 // If default settings are not suitable, change them.
 OperationParameters.Insert("ShowSingleSection",     False);
 OperationParameters.Insert("SetDateForOtherSections",    False);
 OperationParameters.Insert("UseExternalUsers", False);
 Return OperationParameters;

EndFunction

Correct example:

// Allows to set up the subsystem.
//
// Parameters:
//  OperationParameters - Structure - contains properties:
//    * ShowSingleSection     - Boolean - by default, False.
//    * SetDateForOtherSections    -Boolean - by default, False.
//    * UseExternalUsers - Boolean - by default, False.
//
Procedure OnGetOperationParametersSettings(OperationParameters) Export

EndProcedure

Implement setting of default values in the non-overridable common library module:

Function SetUpOperationParameters()

 OperationParameters = New Structure;
 // Default settings
 OperationParameters.Insert("ShowSingleSection",     False);
 OperationParameters.Insert("SetDateForOtherSections",    False);
 OperationParameters.Insert("UseExternalUsers", False);

 // Requesting for an end user configuration in case
 // these default settings are not suitable
 MyLibraryOverridable.OnGetOperationParametersSettings(OperationParameters);
 Return OperationParameters;

EndFunction

3.4. When updating the library version in an end user configuration, pay special attention to root configuration object modules and common overridable modules. Automatical update of such bottlenecks in the end user configuration is unavailable. To set up overridable common modules in the configuration, use the following general approach:

  • When you set up an overridable common module for the first time, read the documentation on its export procedures and functions displayed in comments to them. If necessary, enter the implementation in export procedures and functions of the module. 
  • Each time the overridable common module is updated, you need to transfer new export procedures and functions and delete the obsolete ones. Make sure that comments, the number of parameters, and their names are the same as in their library equivalents. If necessary, enter the implementation in export procedures and functions of the module. You also need to update the implementation of already existing functions if their purpose or the set of parameters were changed in the new library version.

See also: