Lesson 26. Collections and Input on Basis

Estimated duration of the lesson is 1 hour.

CONTENT:

Managing Collections.

Single Collection.
Multiple Collections.
Collections with Multiple Selection.
Multiple Collection with Multiple Selection.
Using NotifyChoice() Method.

Input on Basis.

Input on Basis Command.
Objects Added as Input on Basis.
Using a Filter Criterion.
Obtaining Objects Added as Input on Basis.

Quiz.

There are a number of techniques involved in using configuration objects that are applicable to multiple objects.

Such techniques include collections and input on basis that will be discussed during this lesson.

Managing Collections

The task of managing up collections generally consists of filling in a document tabular section with information users will select from a list of some object.

To illustrate making collections in a form, we will use one of the most common tasks, that of selecting catalog items for inclusion in a document tabular section.

Since the mechanism of collection is implemented at the form level, in different situations other application objects will be involved. The mechanism of the collections will not change.

To manage a collection within a document form, you should open a catalog form as a subordinate to either the document form in general or to one of the form controls. It does not matter how you get the catalog form or which catalog you use. All that matters is that the form should be opened as a subordinate.

A collection result will be accessible in the ChoiceProcessing event handler of the document form or form control (depending on the entity the catalog form was subordinated to when opened).

The ChoiceProcessing event will be called for in two situations in a document form:

- When an interactive choice is made in a catalog form;

- When the NotifyChoice() method is called in the catalog form.

We will demonstrate various collection methods using the example of choosing items from the Products catalog for the ReceiptOfGoods document.

Single Collection

When making a single collection, the catalog form will close immediately after an item is selected. To select the next item, you will need to reinitiate the collection process.

In the Designer Mode

Open the ReceiptOfGoods document form.

On the Commands tab create a command Collect and in the properties palette that opens click an opening button in the Action row.

Do not replace the existing template of the command execution event handler for now. Instead navigate to the Form tab and drag this command to the form controls window so that it is located in the command bar of the Materials table (fig. 26.1).

In the document form, add the following code to the handler of the Collect button clicking event (listing 26.1).

Listing 26.1. The Collect button event handler

&AtClient
Procedure Collect(Command)
	OpenForm("Catalog.Products.ChoiceForm",, Items.Materials);
EndProcedure

In this procedure we open the selection form for the Products catalog and specify that this form is subordinate to the Materials table of the ReceiptOfGoods document (Items.Materials).

When you choose an item from the catalog selection form, the selected value is transferred to the ChoiceProcessing event handler of the Materials form table because it owns the opened selection form. Hence open the properties palette of the Materials table and create the ChoiceProcessing event handler (fig. 26.2) (listing 26.2).

Fig. 26.2. Creating ChoiceProcessing event handler for the Materials table

Listing 26.2. The ChoiceProcessing event handler of the Materials table

&AtClient
Procedure MaterialsChoiceProcessing(Item, SelectedValue, StandardProcessing)

	Items.Materials.AddRow();
	Items.Materials.CurrentData.Material = SelectedValue;
  
EndProcedure

In this procedure we add a new row to the Materials table and assign the value selected in the catalog selection form to the column named Material in the new row. This value is passed to the event handler in the ValueSelected parameter.

In the 1C:Enterprise Mode

Run 1C:Enterprise in the debugging mode.

Navigate to the Goods Management section and create a new receipt using the Receipt Of Goods command.

In the list command bar click Collect and select one material for the receipt by double-clicking it.

Multiple Collections

In the Designer Mode

When making multiple collections, the catalog form will remain open until the user closes it interactively, or until the form's Close() method is called for.

In the ReceiptOfGoods document replace the previous code with a new one in the handler of the Collect button clicking event (listing 26.3).

Listing 26.3. The Collect button event handler

Procedure Collect(Command)

	FormParameters = New Structure("CloseOnChoice", False);
	OpenForm("Catalog.Products.ChoiceForm", FormParameters, Items.Materials);
  
EndProcedure

When a form is opened, we use its parameters.

Form parameters are required for the form to be opened in some desired state. Form parameters represent a structure. Every structure item describes one form parameter. An item key is the form parameter name.

This structure is transferred to the OpenForm() method in the second parameter (the FormParameters variable).

First this statement should be generated. The structure only has one item with the key CloseOnChoice.

So when we transfer this statement to the OpenForm() method, we select False value for the CloseOnChoice parameter of the opened form.

This means that the created form will not be closed after a product is double-clicked.

In the 1C:Enterprise Mode

Run 1C:Enterprise in the debugging mode.

Navigate to the Goods Management section and create a new receipt using the Receipt Of Goods command.

In the list command bar click Collect. Double-click one material to select one product for the receipt and then select another material. Switch to the Services group and select some services.

When all the required products and services are selected, close the selection form window.

Collections with Multiple Selection

In the Designer Mode

Another way to arrange a collection is selecting multiple rows in a list simultaneously.

Multiple selection mode in a list is normally enabled for all the list forms by default.

But by default the feature of choosing multiple items from a list is normally disabled.

So if you want to both highlight and actually select multiple items from the Products catalog, first use one of the parameters of dynamic list form extension - MultipleChoice.

In the ReceiptOfGoods document form replace the handler of the Collect button clicking event with the following code (listing 26.4).

Listing 26.4. The Collect button event handler

&AtClient
Procedure Collect(Command)

	FormParameters = New Structure("MultipleChoice", True);
	OpenForm("Catalog.Products.ChoiceForm", FormParameters, Items.Materials);
  
EndProcedure

When multiple collection is used, the selection form will return an array of items instead of a single item.

So add search within the array of transferred items into the ChoiceProcessing event handler (listing 26.5).

Listing 26.5. ChoiceProcessing event handler of the Materials table

&AtClient
Procedure MaterialsChoiceProcessing(Item, SelectedValue, StandardProcessing)
	For Each SelectedItem In SelectedValue Do
		NewRow = Object.Materials.Add();
		NewRow.Material = SelectedItem;
	EndDo;
EndProcedure

In the 1C:Enterprise Mode

Run 1C:Enterprise in the debugging mode.

Navigate to the Goods Management section and create a new receipt using the Receipt Of Goods command.

In the list command bar click Collect.

For convenience in the selection form of the Products catalog select list view: All Functions - View - List.

Press and hold Ctrl and highlight multiple products and some services from the list.

Click Select.

The highlighted items will appear in the document tabular section.

Multiple Collection with Multiple Selection

In the Designer Mode

The final collection method we will now discuss combines both methods discussed above. The method is to highlight multiple catalog items simultaneously and choose it for inclusion in the document without closing the selection form. Then you can highlight multiple catalog items again and choose them for inclusion in the document.

To do so, when a selection form is opened both parameters should be enabled: CloseOnChoice and MultipleChoice.

This results in the following appearance of the Collect button clicking procedure (listing 26.6):

Listing 26.6. The Collect button event handler

&AtClient
Procedure Collect()
	
	FormParameters = New Structure("CloseOnChoice, MultipleChoice", False, True);
	OpenForm("Catalog.Products.ChoiceForm", FormParameters, Items.Materials);

EndProcedure

In the 1C:Enterprise Mode

Run 1C:Enterprise in the debugging mode.

Navigate to the Goods Management section and create a new receipt using the Receipt Of Goods command.

In the list command bar click Collect.

Open the group Services - Televisions, highlight all the services in the group and click Select.

Open the group Resources - Miscellaneous, highlight all the materials in the group and click Select.

Close the window containing the selection form of the Products catalog.

Using NotifyChoice() Method

The form's NotifyChoice() method is used when the algorithm for generating selection data is complex and we need the user to specify some additional information in addition to selecting the catalog item. In that case, the NotifyChoice() method is called when all the necessary information for the collection is generated.

The NotifyChoice() method alerts the form's owner that a collection or a selection is executed, transmits the selected value to the owner and closes the form unless it is opened in multiple selection mode.

The NotifyChoice() method can also be used when we need to pass some arbitrary data structure in addition to the selected catalog item (or array of items) to the document form.

Input on Basis

The input on basis (contextual) mechanism can be used to enter various new objects (documents, catalogs, chart of characteristic types, etc.). We will discuss this mechanism using the example of entering new documents, which is the most common usages.

For each Document object we can permit input on basis (its entry based on other database objects), and define if it can serve as a basis for other objects.

Actions to be taken to fill in the attributes when using input on basis need to be defined within the Document object's module in the Filling event.

You can either do it manually or use the input on basis wizard that offers visual tools too design data processor code.

We will discuss an example where the ServicesRendered document will be entered on the basis of an item from the Clients catalog.

Input on Basis Command

In the Designer Mode

Open the configuration object editor for the ServicesRendered Document and add a new document attribute named BasisObject of type CatalogRef.

Clients.

Creating such an object is not required for input on basis and is only needed to be able to build a chain of dependent documents in the future.

Switch to the Input on Basis tab and specify the assortment of documents that can serve as a basis for the ServicesRendered document and that can use it as a basis.

Click Edit List Item over the Input on Basis list and select the Clients catalog (fig. 26.3).

Fig. 26.3. Defining the assortment of objects that can serve as a basis for the document

Then call the input on basis wizard and set values for the attributes of the document to be created on this basis.

To do so, click the Fill Expressions button (fig. 26.4).

Note that the wizard suggests using the value Basis.Ref to fill in the BasisObject attribute. In this situation this record is redundant because a reference to a catalog item will be transferred as a basis.

However, in general, the Filling event comes up when creating a new object on the basis of a certain passed value. It is not necessarily the case that it will be a reference type value.

Confirm all the wizard's recommendations and click OK.

The code for the Filling event handler will be generated in the document module (listing 26.7).

Fig. 26.4. Populating attribute values for a document Input on Basis

Listing 26.7. Filling event handler

Procedure Filling(FillingData, StandardProcessing)

	//{{__CREATE_BASED_ON_WIZARD
	//This fragment was built by the wizard.
	//Warning! All manually made changes will be lost next time you use the wizard.
	
	If TypeOf(FillingData) = Type("CatalogRef.Clients") Then
	
		//Filling the headline
		Client = FillingData.Ref;
		BasisObject = FillingData.Ref;
		
	EndIf;
	
	//}}__CREATE_BASED_ON_WIZARD

EndProcedure

As you see, an If.. condition is generated for each type of basis object, and within each condition we fill in the attributes for a new document.

In the 1C:Enterprise Mode

Run 1C:Enterprise in the debugging mode and test how input on basis operates.

Open the client list.

Note that the command bar of the Clients catalog list now contains Create Based On button.

Highlight the required client and use Create Based On &gt Services Rendered to create a new Services Rendered document where the currently highlighted in the catalog list client will be selected as a client (fig. 26.5).

Fig. 26.5. Creating Services Rendered document based on a client

Enter some more documents based on some client yourself.

Objects Added as Input on Basis

While the platform allows creation of objects based on other objects, it has no special means to analyze chains of related documents.

To solve this task, we offer a few tips that may be used as the basis for a specific application.

To form chains of linked objects, we need to give each object entered on basis a system attributed that will store a reference to the basis object. Then you will need to create a FilterCriterion object that will be used to filter for the desired system attribute value.

In the future to obtain all the objects created on basis, all you will need to do is specify an appropriate value for the filter criterion.

Using a Filter Criterion

FilterCriterion configuration object is used to establish the rules to select objects.

This object is used to search for various information, e.g. when you need to select all the documents where a specific contractor is used (in attributes and tabular sections).

In doing so, you can also consider other information filter criteria (e.g. only search within posted documents or within a specific time period).

Obtaining Objects Added as Input on Basis

Since the task of getting all the objects created on the basis of some other object comes up most often in analyzing documents, we will look at an application of the methodology described above using the example of getting a list of documents created on the basis of items from the Clients catalog.

In the Designer Mode

Expand the Common branch and create a new FilterCriterion configuration object named ServicesRendered.

On the Data tab select the type for the criterion used - CatalogRef.Clients.

On the Contents tab select the Basis attribute of the ServicesRendered document as an object included in the criterion (fig. 26.6).

Fig. 26.6. Content of the Rendering Services filter criterion

After you do so, the navigation panel of the Clients catalog item will have a command to open the filter criterion in the Go To group.

Create this form and on the Command Interface tab enable visibility for the Services Rendered command (fig. 26.7).

Fig. 26.7. Command to open filter criterion from the Clients catalog item

In the 1C:Enterprise Mode

Launch 1C:Enterprise in the debugging mode and test how the filter criterion operates.

In the client list form highlight the name Peters Smith that we used as a basis to create the Services Rendered documents.

Open the client form. The navigation panel now has the Services Rendered command to open the list form of the created filter criterion with filter applied by the opened item of the Clients catalog.

Execute this command (fig. 26.8).

Fig. 26.8. Opening the ServicesRendered filter criterion list with filter by client

In this list you can see the Services Rendered documents created with the client Peters Smith as a basis. You can navigate to content of a document by clicking the respective link in the document list.

Quiz

• What is a collection?
• How does one arrange for various collections to a tabular section of a document form?
• What is input on basis?
• How does one arrange for adding some configuration objects based on other objects?
• How does one use filter criterion to display a list of all the objects entered based on the current object?