Creating common modules

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

1.1. A common module contains a group of related procedures and functions. In general, a module contains procedures and functions that belong to the same subsystem or have similar features.

1.2. When you develop a common module, choose one of the code execution contexts:

	Type	Example of description	Server call	Server	External connection	Client (ordinary application)	Client (managed application)
1.	Server module	Common or CommonServer		+	+	+
2.	Server module called from the client-side	CommonServerCall	+	+
3.	Client module	CommonClient or CommonGlobal				+	+
4.	Client/server module	CommonClientServer		+	+	+	+

2.1. Common server modules contain procedures and functions that are not available from the client-side code. Such procedures and functions carry out the application's business logic.
To ensure the proper operation of the application, for the common server modules, select the following flags:

Server with the Server call checkbox cleared
Client (ordinary application)
External connection

In this case, you can call server procedures and functions with mutable-type parameters. For example, CatalogObject and DocumentObject. Usually, these are:

Event subscription handlers of documents, catalogs, and other metadata objects that take as a parameter a mutable value or object.
Server procedures and functions that take as a parameter an object from metadata object modules or event subscription modules.

Common server module names must comply with the general metadata naming conventions.
For example, FilesOperations, Common.

To avoid name conflict with global context properties, it is acceptable to append common module names with postfix Server.
For example, ScheduledJobsServer, DataExchangeServer.

2.2. Server modules called from the client-side contain server procedures and functions available from the client code. They constitute the server API.
For the server modules called from the client-side, select the following flags:

Server with the Server call checkbox selected

For server modules called from the client-side, the names must comply with the general metadata naming conventions and must be postfixed with ServerCall.
For example, FilesOperationsServerCall, CommonServerCall.

In such common modules, export procedures and functions must not contain parameters of mutable types—for example, CatalogObject and DocumentObject—as they cannot be passed to or from the client code.

2.3. Common client modules contain client-side business logic and have the following properties:

Client (managed application)
Client (ordinary application)

This rule does not apply to modules whose procedures and functions must be available only in one mode: managed application mode, ordinary application mode, or external connection mode. In these cases, other combinations of these properties are allowed.

The names of common client modules must be postfixed with Client.
For example, FilesOperationsClient, StandardSubsystemsClient.

2.4. To avoid code duplication, place the procedures and functions that run on both the server-side and client-side in common client/server modules. For client/server common modules, select the following flags:

Client (managed application)
Server with the Server call checkbox cleared
Client (ordinary application)
External connection

The names of common client/server modules must be postfixed with ClientServer.
For example, FilesOperationsClientServer, UsersClientServer.

In common client/server modules, if you need to separate the code into the server-side and client-side, do not employ preprocessor commands. Instead, place the code into the common modules of respective types: server common modules (item 2.1) and client common modules (item 2.3). The separation of client and server code is considered to be the best practice and has the following benefits: better modularity and code reuse, easier to maintain and to monitor client/server communication, and less chance of making mistakes. On the other hand, this approach will lead to the increased number of application modules.

For more details, see Compilation directives and preprocessor commands

A particular type of client/server modules is command and form modules that implement client-side and server-side business logic in a single module.

3.1. Common module names must comply with the general metadata naming conventions. A module name must match the name of its subsystem or the feature, procedure, or function it contains. In common module names, avoid using common, vague, and abstract words that won't help the reader to deduce the module's purpose. For example, "procedure," "function," "data processor," "module," "functionality," "feature." Use your best judgment and include such words in module names only when they help to convey the purpose.

To denote the context of the modules that belong to a single subsystem, in the module names, use the postfixes described in 2.1-2.4.

3.2. Common module names can also be postfixed with words that clarify the modules' purpose.

3.2.1. The names of global modules are postfixed with Global. If you added postfix Global, don't add postfix Client.
For example, FilesOperationsInternalGlobal, StandardSubsystemsGlobal.

3.2.2. The names of modules with privileged rights—Privileged flag is selected—are postfixed with FullAccess.
For example, FilesOperationsInternalFullAccess, StandardSubsystemsFullAccess.

3.2.3. The names of modules that memoize return values for a call or session are postfixed with Cached for server-side and ClientCached for the client-side.
For example, FilesOperationsInternalClientCached, StandardSubsystemsCached.

3.2.4. Library modules, which are intended for other configurations and whose procedures and functions can be overridden, are postfixed with Overridable for the server-side and ClientOverridable for the client-side.
For example, FilesOperationsClientOverridable, CommonOverridable.

3.2.5. For configurations that are to be localized, the names of modules with specific national contexts are postfixed with Localization and ClientLocalization.
For example, ElectonicSignatureInternalLocalization, StandardSubsystemsClientServerLocalization.

See also:

<< Prev Next >>