5.3.8. Event subscriptions

Event subscriptions allow you to assign event handlers to a single object or a group of 1C:Enterprise language objects.

When adding a new event subscription, in addition to the common configuration object properties, it is necessary to specify the event source, the event, the handler of which is assigned, and the procedure that handles this event.

Applied objects, sets of register records, and configuration object managers can be event sources. Both multiple selection of objects that are event providers, and the selection of all objects of the same type (for example, all the documents) is allowed.

The event is selected from the drop-down list, where the list contains those events that are present in all the selected objects. If there are no such events, the list will be empty.

The event handler is selected in a window containing procedures that can be assigned as an event handler. Such procedures must meet the following requirements:

• The procedure must be located in a common module.
• The common module that contains the procedure must have the following properties set:
  • The Global check box is cleared.
  • The Client (ordinary application) check box is selected.
  • The Client (managed application) check box is cleared.
  • The Server check box is selected.
  • The External connection check box is selected.
• The procedure parameters number must exceed the selected event handler parameters number by one. This is due to the fact that in addition to the parameters that are passed by 1C:Enterprise to the event handling method, the source object of this event is also passed.

When the specified event occurs, the following sequence of actions is performed:

• First, the event is handled in the object itself and the event handler defined in the object or record set module is called. If the configuration extensions are connected to the application, the program code extending the event handlers is also executed at this stage.
• If the Fail parameter is set to True or an exception is thrown during the execution of the handler, the action is aborted.
• Then the external handlers assigned to this event are called in an arbitrary order.
• If the Fail parameter is set to True or an exception is thrown during the execution of the assigned handler, the action is aborted.

As a source, the object itself (record set) that caused the event is passed to the assigned handler.

The assigned event handlers are called in the same context as the action that triggered the event. If the execution of the assigned handler needs to be passed to the server, the common module procedure executed on the server must be called in the handler code.

The event handler assignment is also available using 1C:Enterprise language. For this the AddHandler and RemoveHandler operators are used.

Objects that can be event sources have the AdditionalProperties property of the Structure type. The property allows you to store information between event calls, for example, if this object is new or old.