Event handler


As you have already seen, the platform can handle the objects described in the configuration tree: it displays their data, provides the options for adding items, and so on. So the platform has some standard algorithms for this.

But developers are only satisfied with these standard algorithms in the very basic scenarios. Actual tasks are much more diverse. This is why the platform features events that are connected to various moments of standard operations. These include the events related to user interaction with forms and form controls.

Using 1C:Enterprise script, developers can interpose in the events and define custom algorithms that are executed when those events occur. This is exactly what you will do now.

  1. Double-click the MaterialsQuantity form control.
    Right-click the MaterialsQuantity form control and then click Properties.
  2. Scroll down the property palette window to see the list of events that can be linked to this field.

    It is obvious that you need the OnChange event that occurs when the field value is changed.
  3. In the OnChange field, click the Open button  (fig. 4.21).

    Fig. 4.21. Creating the OnChange event handler for the Quantity tabular section field

    The platform prompts you to select the event handler type (fig. 4.22).

    Fig. 4.22. Selecting event handler type
  4. Keep the default Create on client option.

    We will not explain these options for now, as they are described in the Compilation directives section.

    Then the platform generates a handler procedure template for this event in the form module and opens the Module tab of the form editor.

    Fig. 4.23. OnChange handler template for the Quantity tabular section field

    Modules store 1C:Enterprise script algorithms. There are several module types intended for storing algorithms related to various aspects of applied solution functioning. In this case it is a form module because handlers of all interactive events linked to form controls are stored in the form module.
  5. Add the following script to the MaterialsQuantityOnChange() procedure body (listing 4.1).

    Listing 4.1. Procedure MaterialsQuantityOnChange()

    TabularSectionRow = Items.Materials.CurrentData;
    TabularSectionRow.Total = TabularSectionRow.Quantity * TabularSectionRow.Price;

Let us examine this script.

The first line creates the TabularSectionRow variable that will store the object containing data of the tabular section row that requires recalculation.

1C:Enterprise script features weak data typing, which allows using variables without declaring them first (without specifying their types beforehand). In this line the variable is created on the fly and its type is defined by the type of the value assigned to it.

Since we are now in the form module, all the properties and methods of the ManagedForm 1C:Enterprise script object are available within this module. Hence you can call them directly. In this line after the equality sign a collection of form controls is called using one of the ManagedForm object attributes: Items.

The collection of form controls is a FormAllItems 1C:Enterprise script object that contains all of the form controls. This is basically a script analog of the root of the form control tree.

You can get a form control by specifying its name as the property of this object, separated by "." (dot). In this example the tabular section of the Materials document is called (Items.Materials).

A tabular section of a document is a FormTable 1C:Enterprise script object. You can get the row that is being edited using the CurrentData property (Items.Materials.CurrentData) of the FormTable script object.

So once the first line of the handler procedure is executed, the TabularSectionRow variable stores a FormDataStructure object. This object contains data stored in the current row of the document tabular section (Items.Materials.CurrentData).

Once you get this object, you can call the data of a specific column of the tabular section using the column name as the object property. For example, using TabularSectionRow.Quantity allows you to get the number located in the Quantity cell of the row being edited.

Hence, the second line of the handler procedure calculates the value of the Total column by multiplying the values in the Quantity and Price columns.

Add comment