The article considers several examples to apply one of the auxiliary objects of “1С:Enterprsie 8″ platform – event subscription.
Event subscriptions allow you to insert in the modules the external handlers that will be executed after execution of a certain event handler in the object module or manager module.
In this case, it is not required to make any changes in the object module or manager module. Thus, it becomes possible to extend the modules in software without their modification – it is a very useful technique when modifying the standard solutions.

Event subscriptions are described in the branch Common of configuration object window.
If configuration has a created event subscription of some object, for example, event BeforeWrite() of document object, when this event occurs, the platform performs the following sequence of actions.

• Event handler BeforeWrite() is executed in the document object module.
• If during handler execution the parameter Cancel take on a value True or an exception is called, the event processing is interrupted.
• If on the second step the event processing was not interrupted, the external handlers (event subscriptions) are executed defined for event BeforeWrite().
• If during execution of external handlers the parameter Cancel takes on a value True or an exception is called, execution of external handler is interrupted.

Using event subscriptions, it is possible to organize execution of various checks performed when writing the objects in database.

Example 1.

It is required to check the duplicate names when writing an item of catalog “Companies” without modification of modules in the catalog itself.

To solve the task, you need to create a general module EventSubscriptionsHandlers. In the properties palette of module set the flag Server.

In the branch Common of configuration object window create a new event subscription. In the properties palette enter the name of subscription CheckCatalogItemName. In the selection box Source select data type CatalogObject.Companies. In the selection box Event select event BeforeWrite(). After generating this event, the handling procedure of event subscription will trigger:

In the selection box Handler a general module is specified in which the handler of event subscription is located. Click in this box the button Open, select the module EventSubscriptionsHandlers and click ОК. The system will automatically create in general module the procedure CheckCatalogItemNameBeforeWrite() with parameters Source and Cancel. In parameter Source an object is passed for which the vent subscription is created – CatalogObject.. In parameter Cancel the flag to deny the item writing is passed.

The procedure CheckCatalogItemNameBeforeWrite() executes the query to catalog Companies. As a query parameter, the name of writable item of catalog Companies is passed. If an item with this name already exists in the database, then parameter Cancel is set to True (item writing is cancelled) and the corresponding diagnostic message is produced.

Listing of procedure CheckCatalogItemNameBeforeWrite()

Procedure CheckCatalogItemNameBeforeWrite(Source, Cancel) Export
	
	If Not Source.IsNew() Then
		Return;
	EndIf;
	
	Query = New Query;
	Query.Text = 
	"SELECT
	|	Companies.Ref
	|FROM
	|	Catalog.Companies AS Companies
	|WHERE
	|	Companies.Description = &Description";
	
	Query.SetParameter("Description", Source.Description);
	
	Result = Query.Execute();
	
	If Not Result.IsEmpty() Then
		
		Cancel = True;
		Selection = Result.Select();
		
		While Selection.Next() Do
			Message = New UserMessage;
			Message.Text = "There is already exist item with description = " + Selection.Ref;
			Message.Message();
		EndDo;
		
	EndIf;
	
EndProcedure

In practice, you can meet the task to implement the records of additional registers when conducting the document in the standard configurations. Creation of additional registers allows you to avoid modification of existing registers and, thus, get an opportunity of additional data processing when conducting the standard documents.

Example 2

Create circulating accumulation register “Cash outflows” and provide generation of records for this register when conducting the document “Cash payments voucher” using the mechanism of event subscriptions.

Create new circulating register with the name CashOutflows. Select recorder “Purchase return”. Add register measures:
Company, type: CatalogRef.Companies;
Product, type: CatalogRef.Products.

Create register resource:
Sum, type Number, Length – 15, Accuracy – 2.

Create new event subscription:
Name – RegisterRecordsCashOutflows;
Source – DocumentObject.PurchaseReturn;
Event – Posting.

in general module EventSubscriptionsHandlers create handler RegisterRecordsCashOutflowsPosting(). The handler walks over the table part of document “PurchaseReturn” and generates the records in the accumulation register CashOutflows.

Listing of procedure RegisterRecordsCashOutflowsPosting():

Procedure RegisterRecordsCashOutflowsPosting(Source, Cancel, PostingMode) Export
	
	CashOutflowRegisterRecords = Source.RegisterRecords.CashOutflow;
	CashOutflowRegisterRecords.Write = True;
	
	For each Line In Source.LineItems Do
		
		Record = CashOutflowRegisterRecords.Add();
		Record.Period = Source.Date;
		Record.Company = Source.Company;
		Record.Product = Line.Product;
		Record.Sum = Line.LineTotal;
		
	EndDo
	
EndProcedure

In typical configurations you may need to modify the main form of some object, for example, document. This task can be solved using the event subscription. In this case, the copy of main document form is created. In new form the required changes are made. The mechanism of event subscriptions provides the opening of new from instead of the main form. In this case, the main form being on the support remains unchanged.

Example 3

Provide substitution of main form for document “PurchaseReturn”.

Create new form of document “PurchaseReturn” with the name DocumentFormCustomised. Make arbitrary changes in the form, for example, change the order of control elements. To call this form, you need to use an event subscription FormGetProcessing() in the manager module of document “Cash payments voucher”.

Create new event subscription:
Name – MainFormPurchaseReturn;
Source – DocumentManager.PurchaseReturn;
Event – FormGetProcessing.

In general module EventSubscriptionsHandlers create handler MainFormPurchaseReturnFormGetProcessing(). In the handler the name of opened form is passed as a parameter SelectedForm.
Parameter StandardProcessing is set to False to disable main form opening.

Listing of procedure MainFormPurchaseReturnFormGetProcessing():

Procedure MainFormPurchaseReturnFormGetProcessing(Source, FormType, Parameters, SelectedForm, AdditionalInformation, StandardProcessing) Export
	
	If FormType = "ObjectForm" Then
		SelectedForm = "DocumentFormCustomised";
		StandardProcessing = False;
	EndIf;
	
EndProcedure

To search the event subscriptions defined for a certain configuration object, you can use the search engine of object references. To do this, you need to select an object in the configuration object window and in the context menu execute a command Find references to object. As a result of command execution, the window of service messages will output a list of objects that have the references to the desired object.

Thus, the event subscriptions provide the ability to add new functionality without changing the existing object modules. The disadvantages of event subscriptions may include:

• Increased complexity of algorithms.
• It is possible to subscribe only to events of objects and object managers.

If you need to modify some form event, the mechanism of event subscription is not available. In this case, it is required to make the changes in the form itself or copy the form and make the changes in the new object.