1C:Enterprise 8.3. Practical Developer’s Guide. Lesson 5 (2:00). Theory. Modules

Modules

In the previous lesson we discussed event handler script. You have learned that event handler procedures are located in form modules, which are basically storages for 1C:Enterprise script algorithms.

Now let us discuss the modules in more detail and get to know form module nature better.

Module types

Configuration can include various module types. The modules can belong to certain objects (such as forms), or they can exist independently (belong to a configuration as a whole).

The platform uses the script stored in the modules at predefined points of 1C:Enterprise operation. These points are referred to as events and we have discussed them earlier.

The following module types are available in 1C:Enterprise.

1. Managed application module. It is executed when 1C:Enterprise is started in the thin client or web client modes.

You can declare variables and define procedures and functions in this module, and they will be available to all configuration modules (except the external connection module). They are also available for nonglobal common modules with the Client (managed application) property enabled. Exported procedures and functions of common modules are available in the managed application module context.

To open a managed application module

  • In the configuration object tree, right-click the BeginnerGuide root item and click Open managed application module (fig. 5.1).

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.1. Opening the managed application module

2. Common modules. They store the procedures and functions that are called from other modules. A common module itself is never executed, it simply stores the procedures and functions.

To open a common module

  • In the configuration object tree, expand the Common branch, then expand the Common modules branch and double-click the module (fig. 5.2).

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.2. Opening a common module

3. Object modules. Examples of such modules are a catalog item module and a document module.

An object module is called when an object is created using 1C:Enterprise script (for example, the CreateItem() method of a catalog manager is called, or the CreateDocument() method of a document manager), or when a user creates an object (for example, a catalog item or a document).

When modified object data is recorded to the database, event handlers located in the object module are called.

For details on the event sequence during the writing of modified configuration objects, see chapter Quick developer reference.

To open an object module

  • In the configuration object editor, click the Other tab and then click Object module (fig. 5.3).
    -OR-
    In the configuration object tree, right-click the object and then click Open object module.

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.3. Opening an object module

4. Form modules. Each form that is defined in a configuration has its own module. This module is executed when the ManagedForm object of 1C:Enterprise script is created. The platform creates this object in 1C:Enterprise mode when a form is opened either using 1C:Enterprise script (the GetForm() or OpenForm() method) or interactively.

To open a form module

  • In the configuration object tree, expand the object and open its subordinate Form object, then click the Module tab (fig. 5.4).

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.4. Opening a form module

5. Session module. It is executed when the configuration is loaded during 1C:Enterprise startup. A session module is intended to initialize the session parameters and execute the session-related actions. It cannot contain exported procedures or functions. It can call procedures from the common modules.

To open a session module

  • In the configuration object tree, right-click the BeginnerGuide root item and click Open session module (fig. 5.5).

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.5. Opening a session module

6. External connection module. It is intended for storing functions and procedures that can be called in an external connection session.

To open a session module

  • In the configuration object tree, right-click the BeginnerGuide root item and click Open external connection module (see fig. 5.5).

7. Manager modules. Each application object has a manager that manages the corresponding configuration object. Using this manager, you can create objects and perform operations with their forms and templates. A manager module allows you to extend the functionality of default managers provided by the platform by writing procedures and functions in 1C:Enterprise script.

In fact, this allows you to define custom methods for a configuration object (for example, a catalog) that do not refer to a specific database object instance, but rather to the configuration object itself.

To open a manager module

  • In the configuration object editor, click the Other tab and click Manager module.
    -OR-
    In the configuration object tree, right-click the object and click Open manager module.

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.6. Opening a manager module

8. Command modules. The entire configuration and its applied objects can have subordinate configuration objects referred to as Commands. Each command has a command module. You can use this module to create a predefined CommandProcessing() procedure, which is called when the command is executed.

To open the module of a command subordinate to a configuration object

  • In the configuration object editor, click the Commands tab and double-click the command (fig. 5.7).
    -OR-
    In the configuration object tree, right-click the command and click Open command module.

    Lesson 5 (2:00). Theory / Modules / Module types
    Fig. 5.7. Opening a module of a configuration object command

Form module context

Each module is connected to other configuration parts. This relationship is referred to as module context.

The module context defines the assortment of objects, variables, procedures, and functions available when the module is executed.

Since further we will talk about the handler that you created in the form module, let us discuss the content of form module context in detail.

A form module context consists of:

  1. Local form module context
  2. Module form attributes
  3. Properties and methods of the ManagedForm 1C:Enterprise script object
  4. Properties and methods of the form extension that is defined by the type of the object whose data is stored in the main form attribute
  5. Global context, including nonglobal common modules and exported functions and procedures of global common modules
  6. Exported variables, procedures, and functions of the managed application module

Now let us discuss all the listed items in detail.

  1. Local form module context.

    The local form module context consists of variables, procedures, and functions declared in that module.

    For example, inside a form module you can call the GetTotal() procedure that is declared in this module using its name (listing 5.2).

    Listing 5.2. Form module

    &AtClient
    Procedure Command1()
        GetTotal();
    EndProcedure
    
    &AtServerNoContext
        Procedure GetTotal()
        ...
    EndProcedure
    Also, inside a form module you can directly address the InternalVariable variable that is declared in this module using its name (listing 5.3).

    Listing 5.3. Form module

    &AtClient
    Var InternalVariable;
    
    &AtClient
    Procedure Command1()
        InternalVariable = 3;
    EndProcedure
  2. Module form attributes.

    For example, if a form has an InternalAttribute attribute (fig. 5.8), you can directly address it using its name (listing 5.4).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.8. Form attribute: InternalAttribute

    Listing 5.4. Form module

    &AtClient
    Procedure Command1()
        InternalAttribute = 3;
    EndProcedure  
  3. Properties and methods of the ManagedForm object.

    Properties and methods of the ManagedForm 1C:Enterprise script object are described in the Syntax Assistant, in section Interface(managed) / Managed form / ManagedForm (fig. 5.9).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.9. Managed form properties and methods in the Syntax Assistant

    You can address them directly using their names. For example, you can define a form header (listing 5.5).

    Listing 5.5. Form module

    &AtClient
    Procedure Command1()
        Title = "New form title";
    EndProcedure
    Or you can close a form (listing 5.6).

    Listing 5.6. Form module

    &AtClient
    Procedure Command1()
        Close();
    EndProcedure
  4. Properties and methods of the form extension that is defined by the type of the object whose data is stored in the main form attribute.

    One of the form attributes can be the default one. It is displayed in bold in the attribute list. Normally the default form attribute contains the data of the object displayed in the form. For example, in a catalog form the default attribute stores the data of the CatalogObject.<name> object (fig. 5.10).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.10. Default form attribute

    And in a document form the default attribute stores the data of the DocumentObject.<name> object (fig. 5.11).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.11. Default form attribute

    Here we should clarify why the default attribute type is displayed in brackets in the list of attributes: (DocumentObject.Document1). This is because it is not the real attribute type. In this case the real type is FormDataStructure (fig. 5.12).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.12. Object type of the default form attribute

    But FormDataStructure is a universal type that can store data of various application objects. So to provide a clear description of the application object displayed in the form, the Type column of the editor shows the type of the object whose data is stored in this attribute instead of the actual form attribute type (FormDataStructure). And this "fake" type is displayed in the brackets.

    The type of the object whose data is stored in the default form attribute affects some form behavior specifics.

    For example, if the default form attribute stores document data, the user is prompted to confirm saving and posting of this document when the form is closed. And if the default form attribute stores catalog data, the platform does not display that prompt when the form is closed.

    Depending on the type of the object whose data is stored in the default attribute, the context of the ManagedForm script object includes the context of the respective extension.

    For example, if the default attribute is CatalogObject.<name>, the properties and methods of the Managed form extension for catalogs 1C:Enterprise script object are available in the form module (in the Syntax Assistant, see section Interface (managed) / Managed form / Managed form extension for catalogs, fig. 5.13).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.13. Object descriptions in Syntax Assistant

    And if the default attribute is DynamicList (fig. 5.14), the properties and methods of the Managed form extension for dynamic lists 1C:Enterprise script object are available in the form module (in the Syntax Assistant, see section Interface (managed) / Managed form / Managed form extension for dynamic lists, fig. 5.15).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.14. Default form attribute

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.15. Object descriptions in Syntax Assistant

    So in a form module where the default attribute stores document data (fig. 5.16) you can call the AutoTime property of Managed form extension for documents  (listing 5.7).

    Lesson 5 (2:00). Theory / Modules / Form module context
    Fig. 5.16. Default form attribute

    Listing 5.7. Form module

    &AtClient
    Procedure Command1()
        AutoTime = AutoTimeMode.First;
    EndProcedure
    Or you can save the document using the Write() method of Managed form extension for documents (listing 5.8).

    Listing 5.8. Form module

    &AtClient
    Procedure Command1()
        Write(DocumentWriteMode.Posting);
    EndProcedure
  5. Global context, including nonglobal common modules and exported functions and procedures of global common modules.

    In a form module you can get the system date by calling the CurrentDate() built-in function (listing 5.9).

    Listing 5.9. Form module

    &AtClient
    Procedure Command1()
        Message(CurrentDate());
    EndProcedure
    Or you can get the history of user actions by calling the UserWorkHistory property of the global context (listing 5.10).

    Listing 5.10. Form module

    &AtClient
    Procedure Command1()
        History = UserWorkHistory.Get();
    EndProcedure
    If a global common module (for example, DataExchange) defines the GetNumberPrefix() export procedure (listing 5.11), you can call it using its name in the form module (listing 5.12).

    Listing 5.11. Global common module

    Function GetNumberPrefix() Export
        Return Constants.NumberPrefix.Get();
    EndFunction 
    Listing 5.12. Form module

    &AtClient
    Procedure Command1(Prefix)
        Prefix = GetNumberPrefix();
    EndProcedure
    If such common module is nonglobal (for example, DocumentProcessing), when you call a procedure you have to specify the procedure name after the module name, separated by dot (.), see listing 5.13.

    Listing 5.13. Form module

    &AtClient
    Procedure QuantityOnChange(Item)
        DocumentProcessing.CalculateTotal(TabularSectionRow);
    EndProcedure
    The latter method is better because, unlike global modules, nonglobal common modules are not compiled at the system startup. Instead, they are compiled when they are called.

    Of course, it is important to ensure that the procedure directive in the form module (&AtClient, &AtServer, and so on) matches the properties of the common module (Client (managed application), Server, and so on).
  6. Exported variables, procedures, and functions of the managed application module.

    If a TestMessage() export procedure is defined in an application module (listing 5.14), you can call it using its name in the form module (listing 5.15).

    Listing 5.14. Application module

    Procedure TestMessage() Export
        Message("Test message");
    EndProcedure
    Listing 5.15. Form module

    &AtClient
    Procedure Command1()
        TestMessage();
    EndProcedure

Leave a Reply

Your email address will not be published. Required fields are marked *

1C:Enterprise Developer's Community