1C:Enterprise 8.3. Developer Guide. Contents

FORMS

Forms are objects created for entering and viewing information and for managing various processes. The program uses forms to ask the user for information it needs to continue processing or to display information the user can view and edit.

The main purpose of a form is to provide the user with a convenient tool for entering and viewing data. As in paper documents, you can use forms to quickly enter the necessary information and to store it for later processing and when necessary, to restore the previously entered data for viewing or editing.s

The visible part of a form (displayed to users) is a tree with form elements. The items can include text boxes, check boxes, radio buttons, buttons, etc. Moreover, an item can be a group consisting of other items. A group can be represented as a panel with borders, a panel with pages (tabs), a page or a command bar. An item can also represent a table containing other items (columns). A structure of items describes how a form looks like. All form functionalities are described by attributes and commands. Attributes are data used in a form, while commands are actions it performs. Therefore, a developer has to include the relevant attributes and commands in the form through the form editor, create form elements to display them and group these elements, if necessary.

TIP

We recommend designing forms with the resolution set to 96 DPI.

The system can auto-generate forms for application objects; however, the developer can create a custom form and define its attributes, commands and displayed items. This logical description is used by the system to auto-generate the form as it is displayed to users. The system checks various properties of the displayed data (e.g., types) in the process in order to arrange form elements in the most user-friendly way. The developer can change the location of items through various settings. He/she can define the order of items, specify their width and height. This, however, is additional information that helps the system display the form.

Within forms the developer can use both form commands and global commands used in the command interface of the entire configuration. Moreover, he/she can create parameterized commands that open other forms based on the specific data from the current form. For example, one of these commands can open an inventory balances report for the warehouse currently selected in an invoice form.

Forms support linking messages displayed to the user to form data. It means the system can visually mark and activate the form elements that contain user-made errors.

Forms also automatically account for role-based data availability. Thus, if an attribute of a displayed object cannot be viewed by a specific user, the system automatically removes the corresponding form element and rebuilds the form.

You can create forms in the form editor that is available in the Designer mode (see page 2-937). This editor defines the following objects:

„ Form attributes that store data used in the form (see page 1-362).

„ Form parameters that link forms to each other and manage a form's functionality on opening (see page 1-384).

„ Form commands that perform various factions within a form (see page 1-388).

„ Form module that stores program code associated with form operation (see page 1-390).

„ Form elements that display form attributes and make them editable and can be used to display and execute commands (see page 1-391).

„ Command interface that contains commands which can be executed in a form and are provided by the global command interface and form commands (see page 1-421).

IMPORTANT!

Forms exist both on the server and at the client concurrently. You should always keep it in mind as you develop forms.

7.1. FORM ATTRIBUTES

The set of form's attributes describes the data displayed, edited and stored in the form. Independently, the form attributes cannot ensure data display or editing. To display and edit data, use form elements associated with the form attributes. The set of all the form attributes is known as form data.

IMPORTANT!

Please keep in mind that all the form data have to be described as attributes. You cannot use form module variables as sources of data for the form elements.

When you develop a form, you can expressly specify that certain form attributes can be viewed and edited in specific fields; to do this, use the View and Edit prop-

erties (for details see page 2-942). You can also customize an attribute availability in the form using functional options (for details on functional options page 1-211).

You can assign the Main attribute to a form, i.e. the attribute that defines the form's standard functionality (the form's extension).

IMPORTANT!

Please keep in mind a form cannot have more than one main attribute.

Form extension describes additional properties, methods and parameters for a ManagedForm object form; they are determined by the type of the form's main item.

7.1.1. Form Data Types

Forms use a limited set of data types:

„ Types that are directly used in forms are the types at the thin and web client (e.g., Number, CatalogRef.Goods, GraphicalSchema, SpreadsheetDocument).

„ Types to be converted to special data types, i.e. form data types. These types are displayed in the list of form attributes and are enclosed in parentheses, e.g. (CatalogObject.Goods).

„ Dynamic list is a special data type that manages how random information from database tables is displayed in a form. You must specify the table to be displayed or describe the resulting selection in the query language for this data type. This feature is based on the data composition system and allows to apply sorting, filtering, searching, grouping and conditional appearance to the retrieved data.

Certain application types (e.g. CatalogObject and others) do not exist at the thin and web clients. Therefore, the platform uses special data types designed to work in forms in order to represent the application types. This explains why application objects need to be converted to form data (and backwards).

The following data types are available:

„ FormDataStructure: Contains a set of properties with arbitrary types. Properties can represent other structures, collections or structures with collections. An example of this type in a form would be CatalogObject.

„ FormDataColletion: Represents a list of typed values, similar to an array. You can access a collection item using its index or ID. If collections are retrieved based on register record sets or object tabular sections, the collection item's LineNumber field does not match the real index of the item. In certain case you cannot access items by IDs. It is defined by the type of the application object represented by the collection. An ID can be any integer. An example of this type in a form would be a tabular section.

„ FormDataStructureandCollection: Represents an object as a structure and collection at the same time. You can handle the object as any of these entities. An example of this type in a form would be a record set.

„ FormDataTree: This object is used to store hierarchical data.

IMPORTANT!

It is not recommended to use these forms as parameters for procedures and functions transferring control from the client to the server and as function return values, if control is given to the client.

IMPORTANT!

When server procedures and functions are called and control is given back to the client, only changes in form data are transferred. If the Arbitrary type is selected as the form attribute type and the mutable value is selected as the attribute value, you need to assign the mutable value to the form attribute after the mutable value is changed, so data can be correctly transferred between the client and the server.

An application object can be represented by a single or multiple form data items. Generally, the hierarchy and make-up of form data depends on the complexity and interrelation of the form's application objects.

For example, a document that includes a tabular section is represented by the FormDataStructure object (the document proper) with a subordinate FormDataCollection object (the document's tabular section).

IMPORTANT!

As you develop the configuration, please keep in mind that application objects are only available on the server, while form data objects can be used both on the server and at the client.

When form attributes are created, the following limitations apply:

„ You are not allowed to assign Array and Map values to form attributes.

„ You are not allowed to assign Array and Map values to arbitrary-type attributes of FormDataStructure, FormDataCollectionItem, FormDataTreeItem and FormDataStructureAndCollection objects.

„ You are not recommended to use Array and Map values as items of Structure or ValueList collections.

„ In the above cases you are recommended to use fixed collections: FixedArray, FixedMap.

„ You are not recommended to use Structure or ValueList types in form attribute data (i.e. attributes of attributes).

Form data can be viewed as a standardized presentation of data from various application objects that the form uses identically and that exist both on the server and at the client. In other words, the form contains a view of application object data represented as its data types and converts these types as necessary. However, if a configuration developer implements a custom data processing algorithm, data conversion (between special and application types) must also be custom.

When form attributes are edited, the developer can influence data transfer between the server and the client during the form's operation. This is ensured by the Use always column of the attribute editor. The property's behavior differs depending on the type of attributes:

„ If the attribute is subordinate to a dynamic list (a column of the dynamic list):

○     the property is on: the attribute is always read from the database and added to the form data;

○ the property is off: the attribute is read from the database and added to the form data only when a form element that is associated with the attribute or its subordinate attribute is currently visible.

„ If the attribute is subordinate to a collection of register records:

○     the property is on: the document register records are read from the database and added to the form data;

○ the property is off: the document register records are not read from the database and are not added to the form data (if no form element references the records).

„ Other form attributes:

○     the property is on: the attribute is added to the form data regardless of the fact whether any form element is associated with the attribute or its subordinate attribute;

○ the property is off: the attribute is added to the form data only when a form element is associated with the attribute or its subordinate attribute. Unlike the case of dynamic list attributes, the associated item visibility is irrelevant here.

NOTE 1

Please remember that setting a property for a parent attribute affects all of its subordinate attributes. For example, if you disables the Use always property for a document's tabular section, the system assumes the property is disabled for all the subordinate attributes (regardless of the actual property statuses).

NOTE 2

Form attributes of the object type (CatalogObject, DocumentObject, etc.) always have Ref, DeletionMark and IsFolder attributes in the form data (if the object has the corresponding attribute), regardless of the Use always property status.

NOTE 3

It is forbidden to assign other form data objects to form data attributes.

If the attribute editor (Type column) displays the type description in parentheses, e.g. (CatalogObject.Goods), it means the application type is going to be converted to the form data types.

If the form data contain an invalid type (e.g., an attribute of the form attribute), the form attribute editor displays the (Not available in form data) label next to the type name of this attribute. In the 1C:Enterprise mode the form field corresponding to this attribute is not created. No error messages are displayed in this case. You need to explicitly implement the program code that supports copying and processing of such attributes in the form when you copy or edit objects containing such data.

Let us review form attributes of different types:

„ Form attributes of ValueTable and ValueTree types allow you to add columns (the Add attribute column command). It defines the data structure of the created collection.

„ Attributes of FormDataCollection (e.g., objects' tabular sections) and FormDataStructureAndCollection types (e.g., register record sets) allow you to set additional attribute columns (the Add attribute column command) that are not associated with the data stored in the infobase.

The system generates these columns when it creates the form data. You can call these attributes both at the client and on the server.

Below is an example of how you can fill in an attribute column unrelated to data:

&AtServer
Procedure  OnReadAtServer(CurrentObject)

For Each String In Object.Goods Do

// ProductType is an attribute unrelated to data
String.ProductType = String.Product.Type;
EndDo

EndProcedure

„ Attributes of the ValueList type allows you to set the value type (the Value type property) to be stored in the list. In this case the system automatically limits the type of data to be added interactively. Programmatic addition is also allowed, but the system attempts to convert the value of the added type to the limiting type (or the composite type). You can also associate the Value type property with a form element. It enables you to limit the type of data that can be added to the value list interactively.

„ Attributes of the DynamicList type allow you to set list parameters: main table, settings, etc. For details see page 1-369.

IMPORTANT!

Attribute columns that are not associated with data are excluded from data conversions between form data and infobase objects.

For a description of the View and Edit properties see page 2-942.

Form data changes are displayed by form elements after execution of the 1C:Enterprise script or a forced call of the RefreshDataRepresentation() method. Consider the following example.

Assume a form contains a Counter attribute of the Number type. This attribute is displayed in the form as a field of the Progress bar type. Assume you have an action you want to be tracked in the progress bar. This action is triggered by clicking a button in the form:

Procedure  FormCommandHandler()

For Counter=1 to 100 Do

ExecuteAction();

EndDo

EndProcedure

If you click the button that initiates this command in the 1C:Enterprise mode, the progress bar indicator is first in its leftmost position and then it moves directly to the rightmost position (assuming the ExecuteAction() method has been operating for some time allowing to see the change in the progress bar). In other words, the progress bar is only updated after the command handler completes its work.

For the progress bar to display the real progress of the process, you have to replace the handler code with the following:

Procedure  FormCommandHandler()

For Counter=1 to 100 Do

ExecuteAction();
RefreshDataRepresentation();

EndDo

EndProcedure

After this modification the progress bar will change in the course of command handler's code execution.

NOTE

In the web client, calling the RefreshDataRepresenation() method will refresh form elements only when built-in code execution is completed.

7.1.2. Conversions Between Application Object Data and Form Data

You can use a set of global methods to convert application objects to form data and backwards:

„ ValueToFormData() „ FormDataToValue()

„ CopyFormData()

Methods that work with application objects are only available within server procedures. The method that copies values between form data is available both on the server and at the client since it does not use application objects as parameters.

When you convert form data to an application object, you should know whether they are compatible.

„ ValueToFormData(): converts an application-type object to form data; „ FormDataToValue(): converts form data to an application-type object;

„ CopyFormData(): copies form data with a compatible structure. It returns True if data are copied successfully or False if object structures are incompatible.

Conversion of form data to application objects and backwards uses object caching; at the same time the object version in the cache is checked for relevance.

NOTE

Conversion is automatic for standard operations (opening a form, executing the standard Write command, etc.) in a form with the main attribute.

Below is an example of how you can use data conversion in custom algorithms.

&AtServer
Procedure  OnCreateAtServer(Cancel, StandardProcessing)

ObjectProduct =  Goods.FindByDescription("Coffeepot").GetObject();
ValueToFormData(ObjectProduct, Object);

EndProcedure

&AtClient
Procedure  Write()

WriteAtServer();

EndProcedure

&AtServer
Procedure  WriteAtServer()

ObjectProduct = FormDataToValue(Object,  Type("CatalogObject.Goods"));
ObjectProduct.Write();

EndProcedure

The ManagedForm object also has methods available on the server:

„ ValueToFormAttribute(): converts an application-type object to a specified form attribute.

„ FormAttributeToValue(): converts a form data attribute to an applicationtype object.

Using these methods is generally more convenient as they contain information about the form attribute type. Moreover, the FormAttributeToValue() attribute matches form data and the object which is useful for message generation (see page 1-353).

Please keep in mind that when you convert ValueTable or ValueTree objects to form data (using the ValueToFormData() or ValueToFormAttribute() method), the converted object must contain all columns existing in the form data.

IMPORTANT!

Attributes columns that are not associated with data (see page 1-363) are excluded from data conversions between form data and infobase objects. Columns that are not included in object data are cleared when they are converted to form data.

NOTE

Only the following form attribute types can be the first parameter of the FormAttributeToValue() and FormDataToValue() methods: FormDataStructure, FormDataCollection, FormDataStructureandCollection, FormDataTree.

Review an example of using these methods.

&AtServer
Procedure  RecalcAtServer()

// Converts the Object attribute to an application object.
Document = FormAttributeToValue("Object");

// Uses the recalculation method defined in the document module.
Document.Recalc();

// Converts the application object to the attribute.
ValueToFormAttribute(Document, "Object");
EndProcedure

7.1.3. Dynamic List

Dynamic list is a special data type that displays random information from database tables in a form. You must specify the table to be displayed or describe the resulting selection in the query language for this data type.

This feature is based on the data composition system and allows to apply sorting, filtering, searching, grouping and conditional appearance to the retrieved data. The source of data is a query that can be auto-generated by the system (based on the specified data) or written manually by a developer.

Fig. 149. Options of Dynamic List Creation

When creating a DynamicList form attribute the developer can generate the data query using one of two methods:

„ Setting the main table – in this case it is sufficient to specify the table (the Main table property) that has to be used as a data source; in this case the system will auto-generate the data query (see the right part of fig. 149);

„ Generating the query manually – by setting the Custom query property (see the left part of fig. 149). After this you can manually format the query that retrieves data from the infobase.

The query can retrieve data from multiple tables; therefore, you can indicate the main table. It is required so the dynamic list knows which data are primary and which are secondary, so it can select and display information correctly and provide standard commands. However, defining the main table in the query is optional; in this case the dynamic list will have no commands related to the main table.

If you select manual query formatting, the following limitations apply:

„ The dynamic list does not support batch queries.

„ The dynamic list does not support unions in a query if the main table is specified.

„ The dynamic list does not support grouping, sorting and filtering by attributes of tabular sections.

„ The dynamic list may not contain ORDER BY sections if the main table is specified. In this case you should use queries without the main table or set the required ordering using the dynamic list settings.

„ You cannot use subquery fields that return multiple values in a query. Use queries without the main table.

„ The query may not contain groupings and aggregate functions if the main table is specified. In this case you should use queries without the main table or set the required groupings using the dynamic list settings.

„ If the dynamic list is displayed as a hierarchical list or tree, the query may not contain filters by its parent.

„ If a dynamic list is shown as a hierarchical list or a tree, the query should be generated in such a way that query results will contain elements and their parents.

„ The dynamic list does not support sorting if the query contain aggregate functions.

„ If the main table is specified in the dynamic list, the query may not include TOP and DISTINCT instructions.

„ If the arbitrary query is specified, the query should not include the TOP instruction.

„ Specifying a dynamic list table used in the query only in an external connection as a main table.

„ It is not recommended that you use table joins inside the FROM block of the dynamic list query if such joins are specified using the extension of the data composition system query language (in squiggle brackets). We recommend overwriting the query so as to get rid of such joins.

Make sure that you consider the following when creating a dynamic list:

„ You cannot specify tabular sections of objects in the main table of a dynamic list.

„ You cannot use change registration tables (used in data exchange mechanisms), sequence tables and recalculation tables (used in periodic calculation mechanisms).

„ If the query specified for the dynamic list does not ensure uniqueness of the selected strings, the strings in the list and scrolling will be incorrect. In this case you have to disable use of the main table.

In other words, a dynamic list with a specified main table will only work correctly if the query specified as a data source does not increase the number of rows received from the main table (with applied filter).

„ In this case you must disable use of the main table.

„ When dynamic list properties are modified programmatically, any command bars associated with the dynamic list are not updated automatically.

„ The interactive list setup is not available for a dynamic list showing enumeration lists.

If a list form assumes filtering of linked data (for example, filter by owner in a subordinate catalog list), a dynamic list generation query should include a field with a reference to the parent object. This field should have the name of the corresponding standard attribute: Owner, Parent, BusinessProcess, etc. If this requirement is not fulfilled, the standard command for switching to any subordinate list will work, but filtering will not be set. If for any reason it is impossible to fulfill the requirement, you should not use standard commands and instead implement your own commands to open such lists.

If a dynamic list displays data sourced from a virtual table (the Main table property, see page 1-441), for which the BeginOfPeriod and EndOfPeriod parameters are set, these specified period borders are inserted directly into the parameters of a virtual table when a user sets the display period using the Set date range command).

You can use an array or a list of values as a parameter of the dynamic list. But if a list of values is a parameter, only the first list value will be used as a filter value. If a dynamic list uses a query with parameters, initial setting of the parameter values should be done in the OnCreateAtServer handler.

If the dynamic list is the main form attribute, you can set filter values for it using the form's Filter parameter (for details on form parameters see page 1-384). In this case the structure's property name stored in the Filter parameter should march the filter field name in the dynamic list. If these names match, the value of the structure property is set as the right value of the filter item. If an array, a fixed array or a value list is passed as the value for the Filter parameter item of the dynamic list form, a condition with the In list option is added to the filter; the right value of the condition is placed in the value list (which results from conversion of an array or a fixed array).

A query using a parameter to generate any field value can be used as a custom query in a dynamic list, for example:

SELECT
CASE
WHEN Delivery.Rate = 1
THEN &Presentation
ELSE Delivery. Rate
END AS Rate
FROM
Document.ProductDelivery AS Delivery

If the parameter value type is different from the object attribute type, (e.g., Attribute1 has the Number type and parameter value has the String type), you should explicitly cast the parameter value to the required type to correctly display the field:

SELECT
CASE
WHEN Delivery.Rate = 1
THEN CAST(&Presentation AS String(100))
ELSE Delivery. Rate
END AS Rate
FROM
Document.ProductDelivery AS Delivery

If the field used in the filter is disabled with the help of functional options, the filter is not set, even if the filter value is passed as a form parameter or a selection parameter link.

The Read data dynamically property specifies if data for the dynamic list have to be read by small chunks. Regardless of this setting, the following conditions apply:

„ If you set the hierarchical list view, the system reads data from the current folder only.

„ If you set the tree view, the system reads data from the open tree nodes only.

„ Simultaneously loading a dynamic list data is not supported if the hierarchical view is set (the Display property is set to Tree or Hierarchical list) and initial tree representation set to Expand all levels. To obtain the data, the server will be queried for the number of times that there are nodes in the list displayed.

To get displayed data dynamic lists use one of these three methods:

1.     Data are read from a database by chunks where the data item count is equal to the number of rows shown by the list simultaneously. Server-side caching is not used.

2.     Data are read from the database in 1000-data-item chunks. Server-side caching is used.

3.     Data are read from the database in chunks. The first chunk contains 1000 items. Each subsequent chunk is increased by 1000 items (when the previous selection reaches its end). The closer the "view point" moves to the end of the displayed data sequence, the bigger the selection that is read from the database is; eventually, it becomes as large as the size of the data displayed. Server-side caching is used.

Different data reading methods are used based on what the dynamic list main table selects and what the value of the Read data dynamically property is:

„ One of the following tables is specified as the value of the Main table property: the exchange plan, catalog, document list, document journal, chart of characteristic types, chart of accounts, chart of calculation types, business process, job or business process point table:

○     A key identifying the table row: Reference.

○ The Read data dynamically property is set: method 1 is used (see the description above).

○ The Read data dynamically property is not set: method 2 is used (see the description above).

„ One of the following tables is specified as the value of the Main table property: the main table of the information register, accumulation register, accounting register, calculation register or RecordsWithExtDimensions accounting register table:

○     A key identifying the table row: RecordKey.

○ The Read data dynamically property is set: method 1 is used (see the description above).

○ The Read data dynamically property is not set: method 2 is used (see the description above).

„ The filter criteria table is specified as the value of the Main table property:

○     A key identifying the table row: Reference.

○ The Read data dynamically property is not applicable.

○ Method 2 is used (see the description above).

„ The SliceFirst or SliceLast virtual information register table is specified as the Main table property:

○     A key identifying the table row: RecordKey.

○ The Read data dynamically property is not applicable.

○ Method 2 is used (see the description above).

„ One of the virtual register tables is specified as the value of the Main table property, excluding the tables stated above: ○ A key identifying the table row: Count.

○     The Read data dynamically property is not applicable.

○ Method 3 is used (see the description above).

„ The Main table property is not set, a custom query is used:

○     A key identifying the table row: Count.

○ The Read data dynamically property is not applicable.

○ Method 3 is used (see the description above).

Displayed data are transferred to the client in chunks whose size is defined as the number of data items displayed by the list at any one time and incremented by two rows.

When a form is created that contains a dynamic list, initially 32 data items of every dynamic list (if the list contains more than 42 items) are transferred to the client. If a dynamic list shows more than 42 items, data are transferred to the client when a form is opened using the standard algorithm: the number of data items shown simultaneously by the list increased by two rows.

Dynamic lists use values of the following properties belonging to metadata object attributes:

„ Format

„ Edit format

„ Tool tip

„ Negative value selection flag

„ Mask

„ Multi-line mode flag

„ Extended edit flag

„ Password mode

When you display and edit filters or parameter of the data composition system, edit format of the relevant field is applied.

List setup property: Click the Open hyperlink to open the display settings form for the dynamic list. Setting up the list is similar to other operations in the data composition system.

Fig. 150. Conditional Appearance of Dynamic List

Setting up the dynamic list in the configuration, the developer can do the following:

„ Specify the fields to order by;

„ Describe the list filtering;

„ Specify conditional appearance settings; „ Specify the fields for grouping the data.

The developer must specify the sort settings if the default sorting set up by the system is not acceptable.

TIP

Please keep in mind that an inappropriate selection of the sorting fields (as well as fields of data filtering and grouping) negatively affects efficiency of dynamic selection.

IMPORTANT!

Sorting and grouping by fields that contain strings of unlimited length is not allowed.

From the point of view of the application developer, dynamic list settings consist of several interrelated parts. The main property to be used to manage dynamic list settings is SettingsComposer. This object contains three sets of settings that define the final system settings applied to the dynamic list:

„ Settings – settings created in Designer mode.

„ UserSettings – are settings changed by the user in 1C:Enterprise mode.

„ FixedSettings – are settings set programmatically by means of the script. Filter values transferred to the form via its parameters are also included in this property. The Filter, Order, Parameters, and ConditionalAppear-

ance dynamic list properties provide easy access to the fixed settings of the dynamic list settings composer. In other words, these requests are identical: List.SettingsComposer.FixedSettings.Filter and List.Filter.

When a final setting of the dynamic list is created, different variants of the settings are combined as follows:

„ If a certain type of settings is marked in full as a custom set, the resulting settings will contain these custom settings (List.SettingsComposer. UserSettings). If any items of the settings are marked as unavailable, these settings will be added to the resulting settings from the List.SettingsCom- poser.Settings property.

„ If a certain type of settings is marked as a custom type on a by-element basis:

□ Items marked as custom itemss will be added to the resulting settings from the List.SettingsComposer.UserSettings property.

□ Items marked as unavailable will be added to the resulting settings from the List.SettingsComposer.Settings property.

„ Fixed settings (List.SettingsComposer.FixedSettings) are added to the resulting settings as is. Fixed and user settings cannot have settings with the same names, i.e. a filter with a similar left value in the condition.

Whether or no settings are available to the user is controlled in the dynamic list settings window (see fig. 151).

An option in the lower part of the window (see fig. 151) controls the layout of the entire settings view in the settings area (standard or quick). This option is available for the purposes of filtering, ordering, grouping, and conditional formatting. If settings are specified in the Quick access editing mode, specify an empty group of the form where the elements connected to the quick user settings of a dynamic list will be located, in the List setup property of a form table that displays the dynamic list. If the group is not set, quick user settings will not be displayed in the form. You can also explicitly initiate the creation of user settings with the help of a script by using the CreateFormControlsOfUserSettings() method for dynamic list expansion.

Furthermore, you can enable the placing of specific settings elements in user settings. This option is available for filter items and conditional formatting (see fig. 151).

Fig. 151. Managing inclusions in custom settings

There are two ways to enforce the downloading of special settings when a dynamic list is opened:

„ With the help of a parameter of a UserSettings dynamic list form. The data contained in this parameter will be added to the dynamic list’s user settings.

„ With the help of a parameter of a UserSettingsKey dynamic list form. If this parameter is specified when a form is opened, the user settings from the settings storage with the specified key will be loaded to a dynamic list (which is the form’s main attribute).

7.1.4. Attribute Properties

This section describes certain properties of form attributes.

Title: Text used as a title for a form element associated with this attribute if the form element Title property is not set.

Main attribute: Determines whether this form attribute is the main attribute and defines the form extension.

Saved data – Where this property is set for the attribute, changing it interactively will result in:

„ An attempt to block the linked form attribute.

„ Setting the change flag for the form (the Modified flag).

„ If an attribute has the Saved data property set and the form is in the View only mode, all of the form elements related to the attribute also are in the View only mode.

Fill ñheck: Defines whether the attribute has to be checked for completeness (the property value is Display error). You can perform fill checks for the following attribute types only:

„ Primitive data types (Number, String, Boolean, Date, any reference types and a standard period)

„ List of values

„ Value tree

„ Value table

NOTE

Attribute fill checking is similar to the ValueIsFilled() function. In tabular section fill checking a tabular section is filled if it contains at least one row.

7.1.5. Form Conditional Appearance

You can set conditional appearance of items in a form. Conditional appearance settings are similar to conditional appearance settings in the data composition system. These settings can be accessed from the properties palette of the form's root item.

The following types of conditional appearance are available:

„ Background color: It changes the background color and can be applied to the following form elements: text boxes, text document fields, tables, usual buttons and table fields (label fields, text boxes, radio button fields and picture boxes).

„ Text color: It changes the text color and can be applied to the following form elements: label fields, text boxes, text document fields, picture boxes, radio button fields, tables, usual buttons, hyperlinks, text decorations, picture decorations and table fields (label fields, text boxes and radio button fields).

„ Font: It changes the font and can be applied to the following form elements: label fields, text boxes, text document fields, picture boxes, radio button fields, calendar fields, tables, usual buttons, hyperlinks, text decorations, picture decorations and table fields (label fields and text boxes).

NOTE

Changes of form element font done with conditional appearance is not considered when item size is determined.

„ Mark negatives: It specifies if negative values are marked. It can be applied to the following form elements: label fields, text boxes and table fields (label fields and text boxes).

„ Horizontal position: It sets horizontal alignment for a value and can be applied to the following:

○     form elements: label field, text box, text decoration

○ table fields: label field and text box

„ Unfilled mark: It sets incomplete value marks and can be applied to the following:

○     form elements: text box, table

○ table fields: text box

TIP

If the Unfilled mark property is managed via the conditional appearance, set the Automark unfilled property of the field processed to No.

„ Text: It is used to specify the text and can be applied to table fields (label fields and text boxes).

„ Format: It changes the value output format can be applied to the following: ○ form elements: group of Page type, group of Regular group type, ○ table fields: label field and text box.

„ Visibility – this is used only to disable rendering of table fields: the label field, text box, switch field and picture box. The location of cells with disabled rendering is allocated by changing the size of adjacent cells. The cell stretching algorithm can be different in different client applications.

„ Accessibility – this is used only to disable the availability of table fields: the label field, text box, switch field and picture box.

„ Read Only – this is used only to enable View only mode for table fields: label field, text box, switch field, picture box.

„ Show – this is used only to disable rendering of table fields: the label field, text box, switch field and picture box.

NOTE

Conditional appearance uses the current date of the computer adjusted to the time zone of the 1C:Enterprise session. For details on time zones see page 1-292.

If conditional appearance is used to format a form table, the current table data containing the column is used when the condition is calculated. If the formatted field does not belong to the table, first table form (in the order specified in the form editor) data are used to calculate the condition.

You can use conditional appearance to specify certain appearance types for form elements depending on the values of the form attributes; in this case form appearance is dynamic, i.e. changes in form data are tracked. You do not need to perform any special actions to modify the form's appearance.

Consider an example of this type of appearance.

Assume you need to highlight rows in a tabular section of a Goods Issue document if the count in these rows is less than 10.

To do this, you need to set the following conditions in the form's conditional appearance:

„ Conditional appearance type: text color. Select a custom color.

„ Set the following expression as a condition: Object.Goods.Quantity Less than "10". In this expression, Object is the form's main attribute, Goods is the tabular section and Quantity is the tabular section's attribute.

„ Select the entire Goods tabular section as the formatted fields.

Fig. 152. Conditional Appearance Settings

For the resulting view of the conditional appearance, see fig. 153.

Fig. 153. Conditional Appearance Results

As you can see, the font color in the first row of the tabular section is now red, because the count of goods in this row is below 10.

However, in some cases you cannot highlight the entire row with a special color; instead, you need to highlight the tabular section cell than contains the count.

To do this, change the previous conditional appearance: select the Quantity field as the formatted field instead of the entire Goods tabular section.

In this case a single field is highlighted (see fig. 154).

Please note that you can also use values of columns that are not associated with the infobase data in conditional expressions.

Fig. 154. Appearance of Single Field in Tabular Section

7.1.6. Formatted Documents

In the process of application development, there is a need to provide users with the ability to edit formatted texts and documents. An example of this need is the creation of e-mails, different service notes and covering documents.

The FormattedDocument object is designed to work with formatted documents, it is used to programmatically process documents. The Field of formatted document text box is used to interactively edit formatted documents.

It is recommended to store formatted documents in an infobase as a ValueStorage type attribute containing a FormattedDocument type object.

Do the following to allow users to edit documents interactively:

„ Create a FormattedDocument type form attribute and set the Saved data property.

„ Create a Text box type form element of the Field of formatted document type and link it to the attribute created.

„ When form data are read (the OnReadAtServer() handler), load the document to be edited (the SetHTML() method) to the form attribute, having previously received the document from the infobase.

„ Before you can write form data (the BeforeWriteAtServer() method), first receive the result (the GetHTML() method) of the document editing and put it into the attribute stored in the infobase.

You can use tabs while working with a document. A tab is a position in a document. When you define a tab, consider the following:

„ Document contents is considered to be a one character sequence.

„ Line wrap is considered to be one character.

„ A picture is considered to be one character.

You can use tabs to set and get a selection or cursor position in the editor or to add or delete text items in a document.

When the selection start position and end position match, it means that there is no selection and cursor position is received. The same goes for setting the selection: if the selection start and end match, the cursor position is changed with no selection. You should also remember that if the text selected is changed programmatically, the selection is not cancelled. The selection keeps the positions which were set before the text was changed programmatically.

An example of getting and setting the selection in the formatted document editor is given below:

//  Content – form attribute of FormattedDocument type
//  Editor – form item of Formatted document type
//  Begin – attribute forms of Number type. Specifies the position of the start  selection.
//  Finish – attribute forms of Number type. Specifies the position of the end of  the selection.

&AtClient
Procedure  GetSelection()

StartPosition = 0;
EndPosition = 0;
Items.Editor.GetTextSelectionBounds(StartPosition,EndPosition);
Beginning = Content.GetBookmarkPosition(StartPosition);
Finish = Content.GetBookmarkPosition(EndPosition);

EndProcedure

&AtClient
Procedure  SetSelection()

StartPosition = Content.GetPositionBookmark(Beginning);
EndPosition = Content.GetPositionBookmark(Finish);
Items.Editor.SetTextSelectionBounds(StartPosition,EndPosition);

EndProcedure

When delete operations are used, the tab describing the start of the fragment being deleted may be incorrect. If you need to keep the deleted fragment's starting point, use the fragment start position. Thus an example of replacing selected text with another text will look as follows:

Procedure  InsertStringAtCurrentPosition(Editor, Content, String)
Var Beginning, End;

Editor.GetTextSelectionBounds(Beginning, End);
Position = Content.GetBookmarkPosition(Beginning);

Content.Delete(Beginning, End);

Beginning = Content.GetPositionBookmark(Position);
Content.Insert(Beginning, String);

Bookmark = Content.GetPositionBookmark(Position + StrLen(String));

Editor.SetTextSelectionBounds(Bookmark, Bookmark);

EndProcedure

If a formatted document contains hyperlinks and it is displayed in View only mode, the hyperlinks can be used for movement. This movement is performed in a new browser window.

Program access to the text of the formatted document is also available. The text consists of FormattedDocumentParagraph type objects accessible via the Items property of the FormattedDocument object. Every paragraph includes objects of the following types: FormattedDocumentText, FormattedDocumentLinefeed and FormattedDocumentPicture (items of the formatted document). This collection can be accessed through the Items property of the FormattedDocumentParagraph object. The item boundary is not necessarily a word boundary.

The example below illustrates sorting of all the paragraphs of a formatted document with the text and a separate processing of each paragraph.

Example:

For  each Paragraph From Document.Items Do
If Paragraph.ParagraphType = ParagraphType.Normal Then
ProcessOrdinaryParagraph(Paragraph);
ElseIf Paragraph.ParagraphType = ParagraphType.BulletedList Then
ProcessList(Paragraph);
ElseIf Paragraph.ParagraphType = ParagraphType.NumberedList Then
ProcessList(Paragraph);
Else
Continue;
EndIf;
EndDo;

It could be useful to process items of a formatted document that is a part of the paragraph if you need to delete all formatting such as italics or the bold font.

Example:

Bold  = New Font(, , True);
Italic  = New Font(, , , True);
Normal  = New Font;
For each Item From Paragraph.Items Do
If TypeOf(Item) = Type("FormattedDocumentLinefeed") Then
Continue;
EndIf;
If Item.Font = Bold OR Item.Font = Italic Then
Item.Font = Normal;
EndIf;
EndDo;

The GetItems() and GenerateItems() methods can also help in working with a text. These methods return the array of formatted document items. To understand the difference between these methods, look at a formatted sample document with the string: 012 456 890. The string consists of 10 characters with "5" and "7" characters replaced with spaces. Items located between positions 2 and 9 in the document must be obtained.

BeginPosition  = Document.GetPositionBookmark(2);
EndPosition  = Document.GetPositionBookmark(9);
Result  = Document.GetItems(BeginPosition, EndPosition);
For  each Item From Result Do
Message("Text – " + Item.Text);
EndDo;

Result  = Document.GenerateItems(BeginPosition, EndPosition);
For  each Item From Result Do
Message("Text – " + Item.Text);
EndDo;

These methods differ in that the GetItems() method returns all the items detected between specified bookmarks (including all border items), i.e. in the example considered the following text will be displayed:

Text – 012 456 890

And if the GenerateItems() method is applied, the result will be as follows:

Text – 2 456 8

In other words, when you apply the GenerateItems() method, the system generates a set of items in such a way as to include only the content of the formatted document located between the bookmarks.

Please note that the GenerateItems() method changes the formatted document at the time of the call, and if (in the given example) the GetItems() method is called again after the GenerateItems() method, the result will be as follows:

Text – 2 456 8

You get this result even if no changes have been made to the set of items received after calling GenerateItems().

7.2. FORM PARAMETERS

Form parameters (the Parameters tab) serve two purposes:

„ They describe a set of data that define how the form opens (form parameterization). It requires listing all the necessary parameters and specifying their types.

„ They define the parameters that affect the form's unique key. It requires setting the Key parameter property for the parameters to be included in generation

of the form's unique key. When you attempt to open a form, the system searches the right form using the generated unique key. If the form with the obtained unique key exists in the system, it is the one to be returned; otherwise a new form is created.

When you call a form, you can specify values of the parameters created by a developer in the parameter structure along with the form's system parameters (if any).

The form's parameters can be passed to the form when it is created. The passed parameters can be analyzed in the OnCreateAtServer() event (the Parameters collection is a property of the ManagedForm object):

//  At the call location.

//  Generate a form parameter.
Parameters  = New Structure();
Parameters.Insert("Importance",
PredefinedValue("Enum.Importance.Important"));

//  Open the form specifying the parameters.
OpenForm("CommonForm.ViewForm",  Parameters);

…

//  In the form module.
&AtServer
Procedure  OnCreateAtServer(Cancel, StandardProcessing)

If Parameters.Importance =  Enums.Importance.Important Then
…
EndIf;

EndProcedure

IMPORTANT!

After you call the OnCreateAtServer event handler all the non-key parameters of the form are removed from the Parameters collection.

TIP

The form's non-key parameters required in further work should be saved in the form data.

7.2.1. Standard Form Parameters

To support automatic interaction between forms, the system provides a number of standard parameters that manage forms at the opening step. The system uses these parameters to select selection forms in the form fields, open object forms, operate standard commands, etc. In other words, these parameters are used to implement various interface operation scenarios within the system. However, the developer can also use these parameters in the 1C:Enterprise script by passing them when calling the OpenForm() method.

For a list of standard form parameters depending on the form extension type, see section Script – Interface (managed) – Managed form – …extension… of the builtin help.

7.2.2. Form Parameters Handling: Example

To demonstrate how form parameters work, we will implement an item selection operation in the text box. The basis of this example is implementation of item selection from a list in the 1C:Enterprise script.

Before you start your work with the example, you need to have a configuration with the following characteristics:

„ A Goods catalog with a hierarchy of folders and items;

„ A Substitutes catalog with the SelectedProduct attribute of the CatalogRef.Goods type;

„ Both catalogs have item forms.

Now, use the 1C:Enterprise script to implement all the mechanisms used by the platform to select items from a list. You will see the following:

„ How standard form parameters are used;

„ How the system uses the parameters;

„ How the developer can use the parameters.

Add another parameter to manage how the selection form is closed after an item is selected. Name this parameter CloseAfterSelection (Boolean type). Add it to the ChoiceForm of the Goods catalog.

To open the item selection form, you need to create a StartChoiceStartChoice event handler for the SelectedProduct form element at the Substitutes catalog item form:

&AtClient
Procedure  SelectedProductStartChoice(Item, StandardProcessing)

StandardProcessing = False;

ChoiceParameters = New Structure();
ChoiceParameters.Insert("SelectionMode", True);
ChoiceParameters.Insert("ChoiceFoldersAndItems",  FoldersAndItemsUse.Items);
ChoiceParameters.Insert("AllowRootSelection", False);
ChoiceParameters.Insert("CurrentRow", Object.SelectedProduct);
ChoiceParameters.Insert("CloseAfterSelection", False);

OpenForm("Catalog.Goods.ChoiceForm",  ChoiceParameters, Items.SelectedProduct);

EndProcedure

Special attention should be paid to the third parameter of the OpenForm() method. This parameter determines the owner of the selection form that will get notifications of the selection made. In the above example the selection form owner is the form element; however, you can also specify the form in this parameter. In this case you need to implement the ChoiceProcessing handler of the form module and use it to decide what form attribute to use to store the selected data.

NOTE

If the StartChoice event handler is not implemented, the system performs its actions instead. The same is true for all the other handlers used in the example above.

Now you need to process the passed parameters in the selection form. You can do this in the OnCreateAtServer() handler of the selection form module:

&AtServer
Procedure  OnCreateAtServer(Cancel, StandardProcessing)

StandardProcessing = False;

Items.List.ChoiceFoldersAndItems =  Parameters.ChoiceFoldersAndItems;
Items.List.AllowRootSelection = Parameters.AllowRootSelection;
Items.List.CurrentRow = Parameters.CurrentRow;

CloseOnSelection = Parameters.CloseAfterSelection;

EndProcedure

To check whether the specified form parameters are valid, set the ChoiceFoldersAndItems property to Folders for the selection form's List table (catalog item selection is unavailable without the parameter).

NOTE

If the SelectionMode property is not set to True for the List table that displays the list of goods, product selection is unavailable.

Now you need to process selection of the required item in the selection form. To do this, define the ValueChoice event handler for the form table:

&AtClient
Procedure  ListValueChoice(Item, StandardProcessing,Value)

StandardProcessing = False;
NotifySelection(Value);

EndProcedure

Finally, you need to process item selection in the text box. To do this, you need to process the ChoiceProcessing event for the SelectedProduct text box.

&AtClient
Procedure  SelectedProductChoiceProcessing(Item, ValueSelected, StandardProcessing)

StandardProcessing = False;
Object.SelectedProduct = ValueSelected;

EndProcedure

Now you have implemented the system mechanism of value selection in the form text box.

IMPORTANT!

This example is not complete. It only demonstrates how to work with form parameters.

When creating parameters (SelectedGoodStartChoice() handler), you can replace the following string:

  ChoiceParameters.Insert("CloseAfterSelection", True);

with the string:

  ChoiceParameters.Insert("CloseAfterSelection", False);

In this case the selection form will not close after you make the selection. For example, you can use this string to implement a multiple-selection form (when you need to select multiple products without closing the selection form).

7.3. FORM COMMANDS

You can use form commands to perform actions in a form. The commands only describe the required actions. For a command to perform its function, it has to be bound to a form element (e.g., Button). Commands in a form can be divided into several groups.

„ Commands created by a developer while he/she designs the form. These commands require a handler in the form module.

„ Standard commands provided by the form main attribute extension and list attribute extensions (e.g., an object tabular section, dynamic list, information register record set, etc.) if this attribute has an associated form element.

„ Global commands provided by the global command interface (for details on the command interface see page 1-83). These commands can be non-parameterized or parameterized. Parameterized global commands are available in a form, only if the form has parameter sources with the appropriate types.

Availability of the standard commands and form elements is determined by the Command set property of the relevant form element.

Commands provided by the global command interface (the Global commands tab) can be located anywhere in the form, just as the form commands.

The Action property specifies the handler that implements the action of the command. If no handler is set, the command is unavailable. You can only select client-side procedures and functions without parameters in this field (for details see page 1-390).

If the command modifies the form data, you should specify it in the Modifies saved data property. When you attempt to execute the command, the following will occur:

„ An attempt to block the linked form attribute is made. Where the attempt fails, the command will not be executed.

„ The change flag for the form (the Modified flag) is set.

If the command property is set to Saved data and the form is in the View only mode, all form items connected with this command will have the status View only.

In addition, when a global parametrized command whose parameter is provided by an attribute with the property set to Save data is executed for a new unsaved object, the execution will result in an attempt to write the object. In this case the user will be asked whether writing is necessary. If the answer is no, the command will not be executed.

NOTE

If command bars and context menus with the specified command source are filled in automatically, standard commands are not added if the item has buttons with the same commands added manually. This logic does not apply to the commands added from a fragment of the global command interface.

To facilitate development of various dialogs, standard form commands include Yes, No, OK, Cancel, Retry, Abort and Ignore. If a command of this type is added to the form, clicking the button does the following:

„ If the form is opened in the modal mode, it is closed and a value of the DialogReturnCode type is returned;

„ If the form is opened in the non-modal mode, it is only closed.

The command's Name property is used to generate a name for the command execution handler.

Use: For details see page 2-942.

Functional options: Defines what functional options are associated with this form attribute. For details on functional options page 1-211.

7.4. FORM MODULE

A form module is a set of procedures and functions. Module variables and module body are allowed.

Each procedure, function or variable declaration of a form module must be preceded by one of the following compiler directives:

„ AtClient: Specifies the method is executed at the client, while the variable lives as long as the client-side form.

You are allowed to call any methods from a client method.

„ AtServer: Specifies the method is executed on the server, while the lifetime of a variable lasts as long as a server call execution.

Calls of server-side, server-side out-of-context and ñlient/server out-of-context methods are allowed for server-side methods.

„ AtServerNoContext: The method is executed on the server outside the form context. Variables cannot be preceded by this compilation directive.

The form's context is not available to such methods. When these methods are called, there is no data roundtrip. Using out-of-context methods gives a significant decrease in overheads when calling a server-side procedure from the client-side application environment.

It is allowed to call server-side methods of common modules from server-side out-of-context form methods.

„ AtClientAtServerNoContext: The method is executed both at the client and at the server, outside the form context. Variables cannot be preceded by this compilation directive.

Moreover, this method has no access to the form module variables.

You can call methods of non-global server-side common modules and methods of non-global common modules with the Server and Client (Managed application) check boxes from the ñlient/server out-of-context method.

If a procedure is not preceded by a compiler directive, it means that the default directive is used. The default directive is AtServer.

If you use the context call to transfer control from the client to the server, please note that before the call the form data are passed to the server which is followed by the server call execution, and then the form data are passed back to the client. This might take quite a long time. However, an out-of-context server-side call does not require this kind of transfer; therefore, it is faster.

You are allowed to use preprocessor instructions in the form's program module (i.e. a code fragment outside procedures and functions) to expressly mark the code areas that initialize the relevant variables.

IMPORTANT!

You cannot save data between two calls of the server-side form in the server-side form variable.

You are not allowed to use multiple compiler directives before a single method or variable. You are not allowed to have multiple methods or variables with the same names differing only in compiler directives.

Form command handlers created by the developer can only be included in the client-side methods of a form module.

In the form module, you are recommended to use preprocessor directives within procedures and functions only.

NOTE

To understand the possible results in case when the preprocessor instructions cross the procedure boundaries, you should take into account that the preprocessor instructions are processed before compiler directives.

For a complete list of compiler directives and preprocessor instructions, see page 1-157.

Review the following example of using compiler directives:

&AtServer
Var  ServerSideVariable;

&AtClient
Var  ClientSideVariable;

&AtServer
Procedure  ServerSide()
Message(ServerSideVariable);
EndProcedure

&AtClient
Procedure  Command1Execute()
Message(ClientSideVariable);
ServerSide();
EndProcedure

#If  Server Then
ServerSideVariable = "Server";
#EndIf

#If  AtClient Then
ClientSideVariable = "Client";
#EndIf

7.5. FORM ELEMENTS

Hierarchy of form elements defines the appearance and set of controls displayed in the form. There are several types of form elements:

„ form is the form proper which is a root item in the item tree

„ form field

„ form decoration

„ form table

„ form button

„ form groups

Form fields and tables are always associated with the form data. If the associated attribute is not specified, is unavailable at the client due to right restrictions or is excluded from the set of attributes (the View and Edit properties of the form attributes), the field is not displayed in the form and is automatically removed when the form is created in the execution mode.

7.5.1. Common Properties of Form Elements

This section describes common properties of form elements. Properties which is specific for the elements are described below.

7.5.1.1. General Property Category

The Title position property determines how an element title is displayed. The title is a synonym of data associated with the selected element if the Title property is not defined for the form element. The title always ends with the ":" character (it is automatically appended by the system).

When you add a element, use the Data property to specify a reference to the form attribute associated with the element. If the from element has no attribute associations, it will not be displayed in the form. When you add a button to the form, use the Command property to specify a reference to the command to be executed when the button is clicked. If the button has no command association, it will not be displayed in the form.

A form element can be View only (no changes allowed) if its View only property is set (in the Designer or programmatically), the owner group View only property is set or if the associated form attribute has the Saved data flag and the form is View only.

You can manage form element visibility in two properties: Visible and User visibility. The first property can be edited in the form editor (the Designer) or programmatically. The User visibility property is set up in the Designer only and defines the initial visibility of the form element for roles. The final form element visibility results from AND concatenation of Visible and User visibility properties for a specific user. For a description of how to edit the User visibility property see page 2-942. Moreover, editing form element visibility in the Customize form dialog box, the user actually modifies the User visibility property for a specific form element.

For a description of the Height and Width properties (or Height in table rows) see page 1-408.

You can use the Skip on input property to skip the element when using the Enter key to tab between form elements. If the property is set to Yes, the item will be skipped when pressing Enter (but it will be available when pressing the Tab key or pointing to it with the mouse). If the property is set to No, the item will not be skipped when you press Enter. There is also the option to specify automatic skipping of form elements. For this you need to set the property to Auto. In this case the following algorithm is used:

„ The Field type element will be skipped if it is a label field or a picture box, depending on the Display warnings during editing property (see page 1-400).

„ The Button element will not be skipped if it is a default button.

„ The Decoration element will be skipped.

„ The Table element will not be skipped.

Special Modes of Elements-Attribute Associations

As noted above, any element that displays data has to be associated with a form data attribute. In addition to the standard attribute association, several special modes are available.

Association with Current Table Data

A form element can be associated with an attribute representing a column in a table placed in the form. In this case the element displays the field data from the current table row. This type of association is allowed both for fields and for tables; the relevant column does not have to be displayed in the table. The element associated with the current data can be in either the View only or the edit mode. Assume you need to add a field that displays the price for the current product row to the form. To do this, insert the field (it can be a Label field or a Text box) in the appropriate location in the form elements hierarchy and select Object.Goods.Price as the field data (in the Attribute selection dialog box). Here, Object is a form's Document attribute for a specific type, Goods is the document's tabular section and Price is the tabular section's attribute.

Attribute Associations with Specific Table Row

The form item can be linked with an attribute representing a column of a specified table that is a form attribute. This link is allowed both for fields and tables. Moreover, the corresponding column does not have to be displayed in the table. The specific row is defined by the row index (e.g. ValueTable[1]) or an index sequence for hierarchical tables (e.g. ValueTable[2].TotalsList[4]). The item linked with current data may be both in the View only mode and in the edit mode.

NOTE

This link is not supported for dynamic lists.

For instance, you need to place in the form a field that displays a value of the Debt field from Row 4 of the Contragent value table. To do this, add a field (the field type can be both Label field and Text box) to the required location in the hierarchy and select Contractors[3].Debt (in the Attribute selection dialog) as data for this field. Here Contractors stands for an attribute of the (ValueTable) type, and Debt is a column of the value table.

If these fields reference to a missing row, they cannot be edited even when a text box is selected, otherwise any change made in the text box will also be made in the table to which the text box provides the reference.

In the example above, if the user changes the text box, the value from this text box is passed to the Debt column of Row 4 in the Contractors value table. Attribute Association Through Reference

If the form data have reference-type attributes (e.g., CatalogRef), a form element can be associated with the attribute retrieved using the reference. Data for these elements are automatically retrieved and updated whenever the reference modifies. Attribute association through reference can have any level of nesting. Elements associated with this type of attributes are always View only.

NOTE

Attribute retrieval through references is not allowed for composite-type attributes (including CatalogRef, DocumentRef, etc.).

Assume you need to add a field that displays the article for the current product row to the form. To do this, insert a Label field in the appropriate location in the elements hierarchy and select Object.Goods.Product.Article as the field data (in the Attribute selection dialog box). Here, Object is a form's Document attribute for a specific type, Goods is the document's tabular section, Product is the tabular section's attribute and Article is an attribute of the Goods catalog. Association with Collection Totals

An element can be associated with attributes representing the collection's totals: the tabular sections, recordsets and list of values (only the number of rows in a collection). These attributes can include:

„ Totals for the numerical fields; „ Row count in the collection.

Elements associated with this type of attributes are always View only.

As an example, add a field that displays totals for the Goods tabular section to the form. To do this, select Object.Goods.TotalsSum as the form field data, where Objectis the form's main attribute, Goods is the document tabular section and TotalsSum is a special attribute. In addition to the element associations, other association types are allowed, too. You can set associations to display data in a table footer or tab header (Page type groups).

Depending on the type of data displayed by the form element (text box, button or group), you can use the Type property to specify the data display method.

7.5.1.2. Use Property Category

For details on how to use the Quick choice property see page 1-274.

For information about the Choice parameters links and Selection parameters properties see page 1-274. If the Choice parameters links and Selection parameters properties are set both in the properties of a metadata object attribute and in the form element properties, their values are combined. The OR concatenation is used (by parameter names).

You can specify an extended tooltip for the following form items:

„ Field

„ Table

„ Group

„ Button

„ Decoration

The extended tooltip is defined via the Extended tooltip property of the respective form item. To be able to specify this tooltip, select Show extended tooltip in the context menu of the form item. In this case the extended tooltip represents a form decoration of the Text type. It allows you to specify a tooltip using various appearance types (color, font, etc.). This can be done by selecting the Formatted row value of the radio button in the extended tooltip editing window. The text of the extended tooltip should be specified in the Title decoration property. You can also specify the tooltip display mode for the foregoing form items: around the form item, a button near the form item, a pop-up window, or the display mode will be selected automatically. Where the Button display mode is specified, the Title property of the extended tooltip with formatting will be displayed. Where the Pop-up display mode is specified, the system will display the Title property of the extended tooltip but in the form of an ordinary row (without formatting).

When the Tooltip property and the Title property of the extended tooltip are specified simultaneously, the text from the extended tooltip will be displayed.

7.5.1.3. Events Property Category

This group combines references to handlers provided by form elements.

7.5.1.4. Element Pictures

You can use pictures to represent form elements. You can select pictures using one of two methods:

„ The Designer

„ Programmatic selection

If you select a picture programmatically, it can be either a blank picture or a picture from the configuration picture library.

If a picture is selected in the Designer, you can use another option of selecting a file on the hard drive (an external picture). You are only recommended to use pictures of this type when you develop external reports or data processors that can be used in various configurations and the picture is a meaningful formatting item; in other cases using these pictures is undesirable. You cannot select an external picture for form commands and global commands.

7.5.2. Form

It describes the form's visual properties. Element of this type is always unique; it is located in the element hierarchy root. The form properties also describe handlers of form events.

The form opening mode is controlled by a special property: Window open mode.

This property defines how the window is opened:

„ Independent: The form opens in a non-modal window that represents an auxiliary application window:

○     Forms in separate windows. A form is opened in a non-modal window which is the application’s auxiliary window.

○ Forms in tabs. A form is opened in a separate tab.

○ Taxi. The form is opened in the work area of the main application window.

„ Lock parent window: The form opens in a non-modal window, but this mode locks operations with the form used to open the current form. This mode is intended for the forms that are used for short periods of time and do not require a lot of data to be entered, e.g. forms for entering items in catalogs with a small number of attributes. This mode is similar to the modal form opening mode; however, when you open a module from the 1C:Enterprise script, the module operation is not interrupted while you are using the opened form. All other actions with the form are identical to the operations with non-modal forms. In this case the form is also opened in an auxiliary window.

If you open a form in this mode, it is not included in the search of forms that have already been opened. If you try to open an identical form (even if the unique parameter is set to False), the form opened in the Lock parent window mode will not be found and a new form will be displayed.

This mode is set by default for the following forms:

○     Catalog item and folder

○ Exchange plan node

○ Item and folder of a chart of characteristic types

○ Account

○ Calculation type

○ Task

○ Record of an independent information register

„ Lock the entire interface – similar to the form that is opened in the Lock parent window mode, but in this case one is blocked from working with the parent form and the full interface of the application. This mode for opening is not used as a default setting.

The following algorithm is used to define the locked window when you open a form in the lock mode:

„ If the FormOwner property specifies a form which is not closed, the form window is locked;

„ If the FormOwner property specifies a form element in a form and the form is not closed, the owner form window is locked;

„ In other cases (if the FormOwner property is Undefined or the owner form is closed) the current window of the client application is locked.

The Window opening mode property does not affect the way a form opens if the modal mode is used or if the form is opened in an existing main or auxiliary window.

For a description of automatic title generation see page 2-1195.

The Vertical scrolling form property determines how form elements will behave if the form is collapsed vertically. If the property is set to Use or Auto (determined for a specific form as Use), a vertical scroll bar is visible after the vertical size of form elements reaches the size specified when the form was edited in Designer (this refers to the elements whose height is also determined automatically). If a property is set to UseIfNecessary, the form elements will shrink vertically to their minimal size before a scroll bar appears.

For instance, there is a form with the attribute List of type DynamicList. This attribute is shown in the form as table List, for which the height is set to 8 table lines. If the form’s Vertical scrolling property is set to Use, the form will hardly decrease in size at all:

Fig. 155. Vertical scroll in a form. Use

In this case, the vertical scroll bar appeared almost immediately after an attempt was made to vertically shrink the form.

If the form’s Vertical scrolling property is set to UseIfNecessary, the form will first shrink vertically to its minimum, and then a vertical scroll bar appears.

Fig. 156. Vertical scroll in a form. Use if necessary

If the property is set to Auto, the form’s behavior is defined by the system based on the type of the main form attribute:

„ If the main attribute of the form is of type DynamicList or of type ReportObject, and the ReportResult property is specified for the report form extension, Auto is treated as UseIfNecessary; „ In all other cases Auto is treated as Use.

You can display a command bar for a form (you can use the Command bar position property to manage the bar location in the form). The set of standard form commands is managed using the form's Command set property.

If the Enable form change property is off, the user cannot change the make-up and relative position of form elements in the 1C:Enterprise mode.

The Check fill automatically property checks how form data are filled. For details on the fill check see page 1-270.

If the form Save form data in the settings property is set to Use list, the Save column becomes available in the attribute list. The attributes with the Save property set to True are saved in the form data storage (for details see page 1-223). In this case the system uses either the storage from the form's Settings repository property or the storage from the configuration's Form data settings storage property.

NOTE

You can't check the Save checkbox for object tabular sections.

You can make the form View only using its ReadOnly property which can only be changed programmatically. If this property is set to True, the following standard commands become unavailable (including the cases when you try to invoke them using the keyboard shortcuts):

„ For all forms:

○ Restore settings „ For table boxes:

○ Add

○ Copy

○ Delete

„ Generate commands

„ For object form extensions, information register records and constants:

○ Write

○ Write and Close

○ Post

○ Post and Close

○ Clear posting

○ Activate

○ Completed

„ For selection form/settings extensions:

○ Finish editing

○ Select settings

„ For table box extensions in dynamic lists:

○ Mark for deletion

○ Post

○ Clear posting

○ Create group

○ Move to folder

„ For table box extensions in value lists:

○ Edit

○ Move up

○ Move down

○ Sort descending

○ Sort ascending

○ Pickup

„ For all the commands that modify the following collections of the data composition system:

○ Settings collections

○ Collections of available fields

„ For table box extensions for FormDataCollection, FormDataTree, FormDataStructureAndCollection:

○ Edit

○ Move up

○ Move down

○ Sort descending

○ Sort ascending

Form element associated with these commands are also unavailable.

If the form is Read Only and its main attribute is a dynamic list, all tables associated with the list also become read-only. Moreover, if the Folder List property is filled, the form element indicated in this property also becomes read-only. However, the View only property of the form elements remains unchanged.

7.5.3. Field

The Field form element is used to display and edit a form attribute. A form field can have one of the following types:

„ Text box

„ Label field

„ Check box field

„ Image field

„ Radio buttons

„ Text document field

„ Spreadsheet document field

„ Calendar field

„ Progress bar field

„ Track bar field

„ Chart field

„ Gantt chart field

„ Dendrogram field

„ Flowchart field

„ Geographical schema field

„ HTML document field

If the field is subordinate to a Table form element, it can be assigned the following types:

„ Input field

„ Picture field

„ Label field

„ Check box field

If you insert a Radio buttons field, you should specify the form element Selection list property that defines the number and contents of values for radio buttons. By default radio buttons are positioned horizontally. If you want to arrange them vertically, change the value of the Column count property.

You can specify a viewing type for fields like Checkbox and Radio buttons. Use the Check box type property of the corresponding form element to do this. You can select a checkbox view or a toggle switch view for the checkbox field.

Fig. 157. Checkbox or toggle switch

Fig. 157 shows different variants for representing the checkbox field. The upper part of the picture shows the checkbox field as a toggle switch, and the lower part as a checkbox. You can select a radio button view or a toggle switch view for the checkbox field.

Fig. 158. Radio button or toggle switch

Fig. 158 shows different variants for representing the radio button field. The upper part of the picture shows the radio button field as a toggle switch, and the lower one – as a radio button.

If you want to add a text box to the form (available field types: spreadsheet document field, chart field, Gantt chart field, dendrogram field, graphical schema field, geographical schema field), you have to create an appropriate form attribute and set it as the form element data.

If you want to add an HTML document field to the form, you have to create a String-type attribute and an HTML document field and set the generated attribute as the field data. You can use a URL or HTML document text as a value for the form attribute.

NOTE

Please note that some HTML functionalities may not be supported if an HTML document field is used. In particular, this includes status scripts (variables that store values required in different event handlers), the parentWindow property of an HTML document, and any work done with SVG markup language.

If you want to place a formatted document field on the form, you have to create a FormattedDocument-type form attribute, create a Field of formatted documenttype text box and set the generated attribute as the field's data.

NOTE

You can work with the GeographicalSchema attribute on the server only.

If you use the form text box to edit an auto-filled attribute that can be filled manually (in rare cases), you can implement this behavior using the text box Display warnings during editing and Warnings during editing properties. If the Display warnings during editing property is set to Show and you attempt to edit the field, 1C:Enterprise displays a warning with the string that is specified in the Warnings during editing property or auto-generated.

If the AutoMarkIncomplete property of the input field is set to False, its MarkIncomplete property will be automatically actualized when a value is transferred from an attribute to the input field.

For the standard Code and Number fields (for objects with auto-numbering), the auto-generated string is Number filled automatically when writing, while for other fields it is Edit field Field Name not recommended.

If the Display warnings during editing property is set to Auto, the standard Code and Number attributes will use the Show value, while other fields will use Do not show.

The Display warnings during editing property also affects the text box Skip on input property. When the Skip on input property is set to Auto, the field is skipped on input if the Display warnings during editing property is set to Show (or Auto for the standard Code and Number fields).

You can use one of two methods to edit the form's StandardPeriod or StandardBeginningDate attributes:

„ Use a single form field that will be added to the form and directly associated with the edited attribute. In this case all editing is performed in this field.

„ Use multiple fields. You can add fields associated with the attribute properties to the form. In this case a developer can independently implement the required logic of interaction between the standard period option and date values.

The property of the Entry suggestion text box allows you to specify a tooltip to be generated just "inside" the text box provided that the following prerequisites are met:

„ The linked attribute type is neither Number nor Date.

„ The linked attribute value does not include a default value for this type.

„ The input focus is not on this text box.

7.5.4. Decoration

Decoration represents an appearance form element. It is not associated with data (form attributes). It can be a label or a picture.

TIP

You are recommended to use decorations for constant text explanations. If text can be modified programmatically, it is recommended to represent it as a label field.

7.5.5. Table

The Table form element visualizes table data. It can be represented as a dynamic list, tabular section, value list, etc.

The position of the table command bar is managed in the Command bar position form element. The set of standard commands in the table command bar is defined in the Command set property. Commands disabled in this property become unavailable.

You can group columns using the Group form element. For details see page 1-409.

You can specify how to display the form's ValueList attribute. If you select Table, the value list will be displayed as a table with the following columns: Value, Presentation, Check and Picture. Please remember about the way of displaying values in Value column. This column shows the values of the Presentation column. The value itself does not change. You select Input Field, a special window appears where you can edit the list.

A standard set of editing commands, including the commands of selecting and clearing check boxes, is available for a table associated with a ValueList attribute.

If the table is associated with a DynamicList attribute that has grouping set in the list settings (the form attribute's List setup property), the list is always displayed as a Tree (the Display form element property), regardless of the display mode set by the developer. If the table box associated with the dynamic list is View only and you open object forms from this list, their ReadOnly parameter is automatically selected.

You can also manage list updates when data change for tables associated with dynamic lists. To do this, use the Update when data is changed property. If this property is set to Auto, the list is auto-updated when any changes are made to the displayed data. If the property value is Do not update, the list is not autoupdated; in this case updating the list requires explicit execution of the Refresh() command. If the dynamic list is auto-updated with a regular interval and its Update when data is changed property is set to Auto, the interval starts after the last data change; however, if the property value is Do not update, the interval starts after the last call of auto-update or execution of the Refresh() command.

If the table is associated with the main form attribute of the dynamic list type, you can manage the multiple selection mode using the relevant form parameter. The value of the form's MultipleChoice parameter is copied to the table property with the same name. In this case the Selection mode property if set to Multiple if the form MultipleChoice parameter is True.

When you open the form, only data for visible tables linked with dynamic lists can be read. As for tables that remain invisible when the form is open, data can be read only when tables are displayed for the user. In particular, the value of the CurrentRow property will be Undefined for invisible tables. This should be noted when developing the form logic.

If the dynamic list is in the selection mode and you add a new object, the system checks the added object to the specified selection criteria; if the object matches the criteria, the cursor is placed over it in the table that displays the dynamic list.

If the form for a chart of accounts list or a catalog with item hierarchy is opened and its AllowRootChoice and SelectionMode parameters are set to True, the following property values are modified in all the form tables associated with the form's main attribute (of the DynamicList type):

„ The ShowRoot property is set to True;

„ The AllowRootChoice property is set to True; „ The Representation property is set to Tree.

If a table displays a hierarchical list with a set picture row, this set picture will be ignored for table rows displaying groups and the standard group picture will always be shown.

NOTE

If a table displays a dynamic list (see page 1-369) and the Initial tree display property is set to Expand all levels, only a list of rows shown on the first level will be received when a form is created on the server, and then when the form is opened the rest of the rows displayed will be received. A separate server query will be run for every group displayed.

When forms are being designed, certain situations can arise when you need to stop scrolling some columns in a table. For example, you need to lock the Number, Nomenclature and Sum columns in a tabular section.

You also need to align Number and Nomenclature to the left side of the table, and align Sum to the right side of the table.

FixedInTable properties are used for this operation. This property is available for a field located in the table and for Column group-type groups (see page 1-406). In this example, we need to set the FixedInTable property to Left for the Number and Nomenclature columns, and to Left for the Sum column. The columns will be aligned with the corresponding side of the table regardless of their location in the form editor. But these fixed columns are shown in the order in which they are located in the editor.

If the alignment attribute is set for a group, the whole group will be aligned (with all the subordinate form elements) and the FixedInTable property value for any subordinate items will be ignored. If the alignment attribute is set for a column included in a group with the FixedInTable property set to No, the column will be processed as a separate column not included in a group.

The Search when typing property is used to determine how the system handles character input from the keyboard, if a table is the active item and direct keyboard input is not available:

„ Auto – in this case the search window is opened for the table linked to the dynamic list, for other tables the search window is not opened.

„ Use – the search window is opened for any type of attribute linked to the table.

„ Do not use – the search window is not opened for any type of attribute linked to the table.

7.5.6. Button

Each command in a form is displayed by the Button form element. A button can be displayed in the command bar or the form itself. If the button is displayed in the form, it can be represented as a hyperlink (use the Type property to change the setting).

Use the Command property to specify the command invoked by clicking the button.

If the Only in "All actions" property is set, it means by default the button is added to the More (All actions) menu; however, the user can add the button to the bar using a special editor.

7.5.7. Group

When developing a form, you can group items in various ways. You can group fields, form pages, commands or columns.

The form can contain groups of controls. These can be groups of fields, pages or commands. You can also create groups of columns for Table elements.

You can create the following groups in the editor:

„ Regular group is used to group form elements. It can be formatted in various ways:

○     None – the group is not highlighted in any special way;

○ Light marking – the group’s header is displayed in a large green font;

○ Normal marking  – the group’s header is displayed in a large green font; Indents are placed around group elements (on either side);

○ Strong marking – the group’s header is displayed in a large green font; A green line is placed on the left (for the entire height of the group). An indent is placed at the bottom.

A regular group can be setup to enable the user (in 1C:Enterprise mode) to collapse or expand such a group. For instance, you can use such a collapsible group to place information that is not important in terms of the regular form use but may be required every once in a while for data review and analysis.

Group behavior (regular or collapsible) is defined via property Behavior. The initial group state is defined by the Collapsed checkbox. A group cannot be collapsed or expanded if it does not display a header or if the header is empty. The application developer cannot determine the current group state from the script. She or he cannot forcibly collapse or expand a group. Use a special image or a hyperlink to control the group’s state (collapsed or expanded). To specify the element that controls the group’s state, use the Display mode control property. You can also specify the title of the group (the Collapsed title property) to be displayed if the group is collapsed.

If the Collapsed title property is empty, a regular group title will be displayed in the collapsed state.

„ Command bar is a form element that contains buttons and groups. The command bar's Command source property defines the form element (Form or Table form element) that provides its own commands to be displayed in the command bar. The set of commands to be displayed in the command bar is defined by the Command set property of the form element that represents a command source.

You can add one of the following group types to the command bar:

○     Submenu is a group that allows you to create dropdown menus;

○ Button group can be used to create a group of buttons with the following properties:

□ The button group is marked by separators on the left and on the right; □ Each button group can have a separate command source.

○ The Pages group is used to arrange a tabbed bar. Tabs can be located vertically or horizontally. Scroll buttons are shown if tabs do not fit in the dedicated form area (based on the Pages group width or height).When you add pages to the bar of this type, the number of nested groups to be added has to match the number of pages in the bar. The Pages group can only contain Pages groups:

□ Page is a special group used to generate bar pages. This group can contain other nested items.

Column group can be used to group columns in a table. You can use this group to modify the column grouping rule (vertical or horizontal).

Groups can be nested.

You can move the form elements between groups. The system automatically checks if such a movement is possible. If the movement requires any changes in the element properties (e.g. its Type), this change is applied automatically. If this causes changes in requirements to child items, these items are either changed automatically or deleted.

The group's View only property affects all child items in the group.

The Enable content change group property controls how you can change group content when a user configures the form. If the property is disabled, users can't change the content or order of items inside the group. But this property does not affect the ability of users to change the visibility of items inside the group.

If the Title data property is specified for the group, these data are automatically displayed in the group title. If the Title property is set for the group, Title data are displayed in parentheses after the title: Title (Title data).

All button groups (a command bar, popup, button group, context menu) are filled in using the same rules. Buttons are displayed in the following order:

1.     Buttons provided by the command source associated with the group.

2.     Buttons of the command interface if it is enabled for the command source.

3.     Custom commands added to the group.

4.     Commands of the More (All actions) menu (for a command bar only).

5.     The Help command is the last to be displayed (if it is provided by the command source).

If the above auto-ordering of buttons in a group is unacceptable, you can use the following options:

„ Disable the Autofill check box for the form's command bar, context menu or command bar of the element and add the required commands manually (in the appropriate order);

„ Disable the command source of the command bar, add the required commands manually (in the appropriate order), then add a Button group and specify a command source for the group;

„ You can manually position a button associated with a standard command from the command source in the required location of the command bar. In this case the command in question is not automatically added to the command bar.

7.5.8. Special Command Bars

In addition to creating custom command bars (the Group form element of the Command bar type), the form editor can also be used to work with special command bars:

„ Form command bar: The system provides a form command bar. You can manage its visibility, location and content. To manage the bar visibility and location, use the form's Command bar position property; to manage the content, use the Autofill property for a special Command bar group. Apart from the standard commands that can be added to the form command bar, you can also auto-add commands from the Form command bar section of the global command interface.

If the form's main attribute is a dynamic list and the form command bar has its Autofill property set, the commands provided by the dynamic list are auto-added to the bar. If the form also contains a form element that displays as a tree, the form command bar will include the commands provided by the attribute associated with the element.

„ Table command bar: The system automatically provides a command bar for a Table form element. You can manage its visibility, location and content. To manage the bar's visibility and location, use the form's Command bar position property; to manage the content, use the Autofill property for a special Command bar group.

„ Element context menu: You can modify the standard context menu for a form element. To do this, display the context menu in the element tree using the Show context menu command from the context menu for the form element.

If you add a Group-type element in the element's context menu and specify another element as a command source for this group, the group added will be populated with commands (in 1C:Enterprise mode) based on the same rules that are applied for the element's context menu selected as the command source.

You can add custom commands created in the command editor to all of the above listed command bars.

If you want to add commands located in the form command bar (see page 1-89) to another command bar, do the following:

„ Add a Group – Command bar item to the command bar;

„ Select this group as the Global commands of the form commands bar source.

If the command bar or the context menu that contains the group with the Global commands of the form commands bar source also includes a group with the Form command source and you fill in this group, the commands from the form's command interface are not added to the group.

7.5.9. Form Element Behavior

In the ReadOnly mode that is set for both the specific item and the entire form, form fields of the label, picture, label decoration and picture decoration types are displayed as allowed.

If the Hyperlink property is set to True for a label or picture field, selecting the hyperlink (using Enter on the keyboard or double-clicking it) will launch the form element Click event handler. The developer has to process the ReadOnly property for the form or the relevant item and perform the appropriate actions (e.g., locking data to prevent editing).

A Button form element associated with a command with the Modifies saved data property set to True is displayed as disallowed if the ReadOnly property for this element (or the entire form) is True.

If actions that trigger server calls and form rebuild are performed in the OnChange form handler located in the form table, the OnEditEnd and BeforeEditEnd handlers will not be called.

A spreadsheet document located in the form scrolls vertically row by row.

7.5.10. Rules of Form Elements Placement

In the most general case the rules of form elements placement can be defined as follows:

„ Form elements are placed horizontally (each new form element to the right of the previous form element) or vertically (each new form element below the previous form element) depending on the form's Group property, with no restrictions applied to the number of the displayed form elements.

„ The element display order is defined by their order at the Elements tab of the form editor.

„ The form size (and form elements size) can be limited in the Width and Height properties (or the Height in table rows property).

„ If element placement results in exceeding the specified form size, scroll bars are used.

„ If the displayed element is a group, element placement rules within the group are identical to those within the form.

Although this algorithm is simple, the developer can modify it using multiple methods and improve the form's readability:

„ form elements groups

„ form elements sizes

„ child elements width

Below each of the options is described in more detail.

IMPORTANT!

When you place form elements in the form, both the main placement rules and the additional rules covered below are applied.

7.5.10.1. Groups and Form Element Consolidation

Form elements can be consolidated using multiple types of the Group element:

„ Command bar prevents modification of the placement rules selected for the parent form element (another group or form).

„ Page can be used to change the element placement rules.

„ Regular group can be used to change the element placement rules.

„ Column group can be used to change the placement rules for elements (form table columns).

You can set item grouping (the Grouping property) and child item width (the Width of subordinate elements property) for the Regular group or Page groups. Review an example of using this grouping type (see fig. 159).

Consider how a document form is created. The form element grouping is set to Vertical, but you want to place the document's Date and Number attributes in a single row instead of two rows.

To do this, create a group named DateAndNumber, set the Grouping property to Horizontal and add the form Number and Date items to this group (see fig. 160).

Fig. 159. Vertical Grouping

Fig. 160. Horizontal Grouping

NOTE

Please note that groups can have any number of nested levels. The Grouping property can have a different value for each nested group.

7.5.10.2. Form Element Sizes

You can specify the size of each form element: its height and width. The size is measured in abstract units of measure. The actual form element size in the 1C:Enterprise mode can differ from the specified dimensions. When the size of an element is defined, the system considers font (and its size) to be set in the form element properties.

NOTE

Any changes of form element font made with conditional appearance are not considered when element size is determined.

If the size is zero, the platform calculates the value automatically and tries to achieve the best representation of the form on the screen.

If the size is other than zero, the following rules apply:

„ The size of the parent item limits the sizes of the child items;

„ The child item size changes the parent item size until the previous requirement is met.

If the parent item size is too small to hold the child items, the following rules apply:

„ If the items' height value is too large, a vertical scroll bar is added;

„ If the items' width value is too large, their size is reduced to fit them in without using a horizontal scroll bar. However, the horizontal scroll bar appears in the form if its width is reduced to the value that cannot accommodate the widths of the other items.

7.5.10.3. Child Item Width

When you design a form, you might want to place form elements in two columns and use the column width to highlight their importance.

To complete the first task (two-column placement), you should use groups; while the second task requires use of the Width of subordinate elements property (for the groups with horizontal item grouping).

IMPORTANT!

Please keep in mind that the Width of subordinate elements property affects the form element placement only when the parent group has horizontal grouping and there are only two subordinate groups.

This property can have the following values:

„ Auto: Item width is auto-selected by the system.

„ Equal: Equal width is selected for the items.

„ Left wide: The correlation of the left and right item widths is 3:2.

„ Left widest: The correlation of the left and right item widths is 2:1.

„ Left narrow: The correlation of the left and right item widths is 2:3.

„ Left narrowest: The correlation of the left and right item widths is 1:2. Review the following example.

Fig. 161. Child Item Width

Assume you want to have two columns in the document header. One of them (to the left) should include the Buyer and Warehouse attributes, while the other (to the right) should include the Price type and Settlement currency attributes. Since the left-side column is more important, you want to increase its width.

To do this, create a Header group and set the Horizontal grouping type. Create two more groups inside the first group: Left and Right. Each group is assigned the Vertical grouping type. Add the Buyer and Warehouse attribute to the Left group and the PriceType and Currency – to the Right group.

After that set the Width of subordinate elements property of the Header group to Left widest.

NOTE

The main purpose of the Width of subordinate elements property is to specify the dimensions to be used when the platform generates the form.

7.5.11. Form Element Boundaries Alignment

When you place an element in a form, the 1C:Enterprise system automatically aligns the left boundaries of form element data based on the form element type and certain rules. This section discusses form element boundary alignment rules.

A form element consists of a data area – a form element area where data are shown, and a title area (title) – a form element area where the title form is shown (see fig. 162).

Data area standard width specifies the data area width and has the following properties:

„ is determined by attribute data type linked to the form element or by the Width property of the form control

„ does not depend on the Stretch horizontally property of the form element.

Fig. 162. Form element structure

7.5.11.1. Data Area, Left Side Alignment

Common Rules

If you add several elements displayed on the left of the data area to a Regular grouptype or Page-type form or a group with vertical grouping (if the Grouping property is set to Vertical), then the left side of the form element data area will be aligned:

Fig. 163. Left side alignment

But the following rules should be followed for such alignment:

„ Extending the title will not make the data area width less than the default data width:

Fig. 164. Data area width is less than default data area width

In the example shown in the fig. 164 the data width becomes less than default data area width.

Alignment will stop working when the first element title line is extended. The Name field data area width should be less than default data area width, if alignment was applied. This proportion adds one letter i to the title.

The title width will not be significantly larger than the maximum value of default data area width and this field's title width:

Fig. 165. Title larger than default area width

In the example shown in fig. 165, alignment stops working when the second element title line expands in such a way that the First name, patronimyc, last name field title width becomes significantly larger than the default data area width. This proportion changes when patronymic is added to the title.

If it is impossible to determine single title width for several vertically positioned elements based on the above rules, the system will define element sets inside which the conditions are met. Grouping into sets does not depend on element vertical order. Grouping starts with the control with the least width. Elements in one set do not necessarily follow each other.

Fig. 166. Element set alignment

You should note the following when aligning elements:

„ If a form element has no title or the title is not located at the left side, this control is not aligned.

The form table is not aligned, even if it has the title located at the left side.

Fig. 167. Tables are not aligned

„ If there is an element for which alignment is not applicable between the elements, it does not affect the alignment.

Fig. 168. Alignment is not applicable for a form element

„ For a checkbox, displayed data are a rectangular area where the checkbox is shown.

Fig. 169. Checkbox alignment

Nested Groups

If form elements (with titles to the left) are located in a Regular group-type group, elements will be aligned along with border elements only if the Display property for the group is set to None. Otherwise, alignment of elements in the group will not consider elements around the group.

Fig. 170. Alignment with element groups

7.5.11.2. Form Element Right Boundaries Alignment

Alignment of form element right borders does not depend on the Stretch horizontally property of the form element. If the Stretch horizontally property is set to Auto, the system controls element right border alignment.

If the property is set to No, this element does not change horizontal size, and if there are nested elements it does not allow you to change the horizontal size of these elements.

If the property is set to Yes, then:

1.     The right border of the form element changes its position, until it leans against the other element (or form border), thus preventing further change in its position.

Fig. 171. Stretching element to the right until delimiter is reached

2.     Nested form elements with the Stretch horizontally property set to Yes (or Auto for some elements) also change the position of their right border if the parent form element size changes.

Fig. 172. Stretching subordinate elements

3.     If there are other elements that can be changed to the right of the element, the element is relocated until a restriction from p.1 is applied for the rightmost element (the form element "pushes" its right-side neighbors).

Fig. 173. Right-side element movement

4.     If the property Stretch horizontally is set to Yes for two or more adjacent elements, when parent element horizontal size changes these elements adjust their width simultaneously and proportionally.

Fig. 174. Proportional adjustment

In the example in fig. 174, the Cancel button between decorations does not change its size, since it does not have the Stretch horizontally property.

7.5.11.3. Form Element Lower Boundaries Alignment

Alignment of form element lower borders does not depend on the Stretch vertically property of the form element. If the Stretch vertically property is set to Auto, the system controls element lower border alignment.

If the property is set to No, this element does not change vertical size, and if there are nested elements it does not allow you to change the vertical size of these elements.

If the property is set to Yes, then:

1.     The lower border of the form element changes its position until it leans against the other element (or form border), thus preventing further change in its position.

Fig. 175. Element stretching

2.     Nested form elements with the Stretch vertically property set to Yes (or Auto for some elements) also change the position of their lower border if the parent form element size changes.

Fig. 176. Adjusting nesting element

3.     If there are other elements that can be changed under the element, the element is relocated until a restriction from p.1 is applied for the lowest element (the form element "pushes" its lower side neighbors). This situation is shown in fig. 176 (the Warehouse element).

7.5.12. Drag-and-Drop Mechanism

1C:Enterprise supports drag-and-drop operations. You can use these operations to transfer data between various elements. For example, you can drag and drop catalog list items from one folder into another, drag and drop data from a table box to a spreadsheet document field or transfer a list of selected files from Microsoft Windows Explorer to any element.

Drag-and-drop operations are supported by the following elements:

„ Form table

„ Spreadsheet document field

„ Calendar field

„ Picture field

„ Picture decoration

The following terms apply to the drag-and-drop operations:

„ Data source: A form element that is the starting point of the data drag-anddrop;

„ Data target: A form element that is the destination of the data drag-and-drop.

You can enable or disable the element ability to provide or receive data, i.e. to be a data source or target. To do this, you can use the following element properties:

„ Enable start dragging: Enables the element to provide data.

„ Enable dragging: Enables the element to receive data. You can set these properties in the properties palette or the 1C:Enterprise script.

When you click the selected area of the control, it calls the DragStart event handler for the data source. This event passes DragParameters and Stan- dardProcessing objects as its parameters. The DragParameters parameter has the following properties:

„ Values: Contains the value to be dragged-and-dropped, e.g., it can be a reference to an object for a table box or a spreadsheet document area for a spreadsheet document or a date for a calendar. You can assign a custom value to this property (e.g., a structure); in this case this value becomes the object to be dragged-and-dropped. For a managed form table linked to a FormDa- taCollection, FormDataTree or FormDataStructureWithCollection type form attribute the following items are passed as drag-and-drop values:

○ row ID (or ID array), if drag-and-drop is done within one table.

○ collection item (or item array), if drag-and-drop is done between different tables.

„ Action: Specifies the drag-and-drop action and is a value of the DragAction type.

„ AllowedActions: Specifies valid drag-and-drop actions and is a value of the DragAllowedActions type. You can use this property to specify the operations that can be performed with the data from the source (e.g., copying only).

The StandardProcessing parameter enables or disables standard processing of the drag-and-drop operation from the control. Standard processing for the DragStart event is the start of data drag-and-drop.

Then the data target calls the DragCheck event handler. This handler is invoked every time the cursor points to a new object in the data target (e.g., a new table cell or a spreadsheet document field or a new date in the calendar field). A set of parameters for this event depends on the data target; however, the first two parameters are always the same. These are DragParameters and StandardProcessing objects. Other parameters describe the object under the cursor. When processing this event, you can manage the cursor shape; for example, you can specify that dragging into a specific control is not permitted or only copying is allowed. To do this, specify the required action in the Action property of the DragParameters parameter. Please note that the specified drag-and-drop action has to be allowed, i.e. it must not conflict with the value of the AllowedActions property. For example, the Copy action does not conflict with the CopyAndMove value for the allowed actions, while Move conflicts with Copy. The StandardProcessing parameter specifies whether the form element can perform standard processing of the event. Standard processing of drag-and-drop operations depends on the control type:

„ For a table, it checks whether a value can be inserted, i.e. it checks the value type; if the type matches the displayed data type, standard actions are performed. Standard actions for hierarchical dynamic lists include moving to a group; for tables that display record sets or tabular sections these include reordering rows and copying.

If a table has the ChangeRowOrder property set to False, when drag-and-drop is done within the table the Drag event will not be called.

If a table has the ChangeRowOrder property set to True, or drag-and-drop is done outside the table, default handling does not cancel drag-and-drop operation.

Default handling does not cancel drag-and-drop operation if the Selecti- onMode is set to Multiple, the ChangeRowOrder property is set to True or drag-and-drop is done outside the table and only one item is dragged.

„ For a spreadsheet document field, it checks whether the passed value can be inserted.

„ For picture and calendar fields, there is no standard processing.

If you release the mouse button in the form element, it calls the Drag event handler. This event has the same set of parameters as the DragCheck event. The StandardProcessing parameter enables or disables standard processing of the event by the form element. For a description of standard drag-and-drop actions see above.

Then the data source control calls the DragEnd event handler. When processing this event, the form element can delete the moved data or clear some variables.

7.6. FORM COMMAND INTERFACE

The form's command interface includes:

„ The form navigation panel

„ The form command bar

You can edit the form's command interface by adding new or using existing commands, etc.

Please note that the form's command interface should be edited in a separate tab of the form editor; it describes the contents of the navigation panel in the auxiliary window that displays the form and partially describes the contents of the form's command bar. This mechanism is primarily used to set up global interface commands that need to be displayed in these two panels of the form. The contents of the form's command bar is determined both in the item structure directly and in the command interface editor.

A command is automatically added to the form command interface if the parameter type of the parameterized command matches the form main attribute type.

Moreover, you can deliberately add a command to the command interface panel you choose. To do this, you just need to move it to the right group in the required command bar.

If the Autoposition flag is selected, it means the system-generated default sequence of commands will be used. If you uncheck this box, you can edit the command sequence.

To set up visibility for the commands from the command interface panels, you can uncheck the Autovisibility box and change the value in the Visible column.

7.7.                  DIFFERENT APPROACHES TO MODALITY

7.7.1. Overview

One often needs to open a form that would provide several functional capabilities at the same time in the applications developed with the help of 1C:Enterprise.

„ Block working with other application interface fragments.

„ Enable data input (e.g., responding to a question).

„ Stop application code execution before work with an open form is completed.

These forms may be created by the application developer in 1C:Enterprise script and be part of the platform (e.g., the forms that open methods Warning(), Question(), etc.).

1C:Enterprise supports two ways to use such forms:

„ Modal windows

„ Blocking windows

Either a single approach or mixed model can be used for an application. A special configuration property is used to control such functionality – Modality usage mode (see page 1-169).

The first approach to modality usage (modal windows) includes the use of special types of OS windows, i.e. modal windows. If this schema is used, script code execution stops until the modal form is closed. A return value will be received directly where the modal form was opened, and any actions using this value can be performed immediately afterwards (with the same method): analyzing, part of an algorithm, etc. Modal windows can be opened with the help of OpenFormModal() or Warning() methods. However, modal windows are not supported on iPads and are poorly supported in a web client.

In these cases, we recommend that blocking windows be used. A blocking window differs from the modal window as follows: when a blocking window is opened, script code execution goes on. A callback procedure is used to obtain the result of the blocking window’s operations. This peculiarity results in the fact that an algorithm that uses modal calls to control its work will have to be completely reworked to be used with blocking windows. The difference between the two ways of using modal windows, from the point of view of the developer, is shown in the example below. For example, there is a certain client handler that asks the user a question and performs one or another application code branch, depending on the response received.

Modal windows (example):

&OnClient
Procedure  ExecuteAlgorithm()
Result = Question ("Execute fast or not slow?",  DialogModeQuestion.YesNo);
If Result = DialogReturnCode.Yes Then
// First variant of the algorithm
Else
// Second variant of the algorithm
EndIf;
EndProcedure

In this mode (modal windows) script execution will stop at the Result = Question() line and will continue only after the user responds to the question.

Blocking windows (example):

&OnClient
Procedure  ExecuteAlgorithm(Command)
Callback = New NotificationDescription  ("ExecuteAlgorithmCallback", ThisObject);
ShowQuestion(Callback, "Execute fast or not slow?", DialogModeQuestion.YesNo);
EndProcedure

&OnClient
Procedure  ExecuteAlgorithmCallback(Result, AdditionalParameters) Export
If Result = DialogReturnCode.Yes Then
// First variant of the algorithm
Else
// Second variant of the algorithm
EndIf;
EndProcedure

In this example (where blocking windows are used), an algorithm is divided into two parts:

„ A place where a question to the user is displayed

„ A place where the user’s response is processed

However, these are different fragments of the application code. When the ShowQuestion() method is called, script code execution does not stop. However, the user will be able to answer the question only when the script code execution is completed and control is transferred to 1C:Enterprise. That means, the results of a user using an open form cannot be obtained in the point where the method displaying the question form was called.

When the user answers the question, an export procedure will be called. The application developer should transfer the description to the blocking window opening method. The NotifyDescription object is used to describe a callback method. A callback method may be located in a form module, a command module, or a common module. If you need to specify that a callback method and blocking window call method are in the same module, use the ThisObject value. Also, you can transfer different auxiliary data to the callback handler. This data will be available in the handler via a formal parameter, AdditionalParameters. These may be input data for the algorithm operations, different parameters, etc.

As a rule, after any method that is used for working with blocking windows is called, the method that contains such a call shall be completed with immediate effect, and the rest of code shall be placed in a notification handler.

If a cascade call of callback methods is required, use the ExecuteNoti- fyProcessing() method. This method can also be used if an action may be implemented immediately before or after a prompt concerning actions to be taken is displayed. For instance, if you try to reread a data file, the current state of the editor is checked, and if the data in the editor has been changed, the system asks whether it should reread the data.

Example:

&OnClient
Procedure  RereadData(Command)

Callback = New NotifyDescription ("RereadDataEnd",  ThisObject, FileDataName);
If Modified Then
ShowQuestion (Callback, "Data modified. Reread?"  QuestionDialogMode.YesNo);
Else
ExecuteNotifyProcessing(Callback, DialogReturnCode.Yes);
EndIf;

EndProcedure

&OnClient
Procedure  RereadDataEnd(Result, FileName) Export

If Result = DialogReturnCode.Yes Then
// perform data read
Modified = False;
EndIf;

EndProcedure

7.7.2. Using blocking windows

In thin and thick clients (unlike a web client), the BeginPutFile() method stops string code execution. However, it will still be executed after the callback procedure call operation transferred to the BeginPutFile() method is completed. To avoid behavioral differences when working in a thin client and web client, place all the code to be executed upon file placement directly to the callback handler.

If the application build logic requires that the user is asked a question when a form is closed, this should be done in a special way, as shown in the example:

&OnClient
Var  ResponseBeforeClose;

&OnClient
Procedure  BeforeClose(Refusal, StandardProcessing)
If ResponseBeforeClose <> True Then
Refusal = True;
Callback = New NotificationDescription  ("BeforeCloseEnd", ThisObject);
ShowQuestion(Callback, "CloseForm?",  QuestionDialogMode.YesNo);
EndIf;
EndProcedure

&OnClient
Procedure  BeforeCloseEnd(Result, AdditionalParameters) Export
If Result = DialogReturnCode.Yes Then
ResponseBeforeClose = True;
Close();
Else
ResponseBeforeClose = Undefined;
EndIf;
EndProcedure

Actually, a form is closed in two steps:

„ A question on whether a form should (and can) be closed is asked, and form closing is cancelled.

„ When a user answers the question, the system marks, in a special client variable, that the "real" closing of the form will be performed, and the form is closed once again.

A value of the main property of the dialog to be closed is transferred as the first parameter to a callback handler that is transferred when the Show() method is called, if ÎÊ is pressed in the dialog, or in other cases, Undefined. This is true for the StandardPeriodEditDialog, FormatStringWizard, FontChooseDialog, ColorChooseDialog, and ScheduledJobDialog objects. For instance, if a standard period is edited, the StandardPeriod (or Undefined) object functions as the first parameter of the callback handler.

7.7.3. Method mapping

When the existing algorithms that use modal windows are reworked into blocking windows, the following table that maps the modal and blocking methods of the global context and different objects should be consulted:

Object	Modal method	Blocking method
Global context	OpenFormModal()	OpenForm()
	Question()	ShowQueryBox()
	OpenValue()	ShowValue()
	DoMessageBox()	ShowMessageBox()
	InputDate()	ShowInputDate()
	InputValue	ShowInputValue()
	InputString()	ShowInputString()
	InputNumber()	ShowInputNumber()
	InstallAddIn()	BeginInstallAddIn()
	InstallFileSystemExtension()	BeginInstallFileSystemExtension()
	InstallCryptoExtension()	BeginInstallCryptoExtension()
	PutFile()	BeginPutFile()
StandardPeriodEditDialog	Edit()	Show()
FormatStringWizard	DoModal()	Show()
DataCompositionDetailsProcess	ChooseAction(0	ShowActionChoice()
FontChooseDialog	Choose()	Show()
ColorChooseDialog	Choose()	Show()
ScheduledJobDialog	DoModal()	Show()
ValueList	CheckItems()	ShowCheckItems()
	ChooseItem()	ShowChooseItem()
ManagedForm	DoModal()	Open()
	ChooseFromMenu()	ShowChooseFromMenu()
	ChooseFromList()	ShowChooseFromList()

7.8.               WORK WITH FORM FROM 1C:ENTEPRISE SCRIPT

7.8.1. How to Open a Form

You can open a form using one of two methods:

„ Use the OpenForm()/OpenFormModal() method;

„ Use a combination of the GetForm() method and the Open() method or the DoModal() of the ManagedForm object.

In both cases you can pass form parameters to the form you are opening.

You are recommended to use the OpenForm() method in all cases, except when you need to open a form in the modal mode and then retrieve its results through the attributes of a form being opened.

This requirement has to be met because the modal form return value is the data returned by the form, and the developer has no access to the ManagedForm object that retrieves the form attributes. If you first retrieve the form using the GetForm() method, you can access the attribute after the DoModal() method is completed.

Example 1:

//  Open a list form for the Goods catalog
//  as read-only

Parameters  = New Structure("ReadOnly", True);
OpenForm("Catalog.Goods.ListForm",  Parameters);

Example 2:

//  Open a modal form and after it closes
//  access the form attributes

Form  = GetForm("CommonForm.PeriodSelection");

Result  = Form.DoModal();
If  Result = DialogReturnCode.Yes Then

BeginDate = Form.BeginDate;
EndDate = Form.EndDate;

EndIf;

For a description of how to work with form parameters see page 1-384.

NOTE

Do not open and close the same form programmatically in the same script call.

7.8.2. Redefining an Opened Form

There could be a task in application systems to open different forms with different object parameters (or the current environment). For example, you need to open different forms for the Nomenclature catalog item, for products and services. Or for some automated workplaces you need to open different forms based on current user settings.

To perform this task you need to create an FormReceiveProcessing event handler in the object manager module. You need to perform all the required validations in this handler and make a decision about which form to open. This handler is called only if there is an attempt to open a default object form using default form names.

Thus, when a Nomenclature catalog item of the form element is opened, the handler will be called in the following situation:

OpenForm("Catalog.Items.ObjectForm");

But it will not be called if you try to open the form as follows:

OpenForm("Catalog.Goods.Form.ItemForm");

Let's look at the example with different catalog item forms in more detail.

When the form is opened, the View attribute of the Nomenclature catalog is analyzed. If this property is equal to Enumeration.ProductTypes.Service, open the ServiceForm form of the Nomenclature catalog.

Procedure  FormGetProcessing(FormType, Parameters, SelectedForm, AdditionalInformation,  StandardProcessing)

If FormType = "ObjectForm" And Parameters.Key.Type =  Enums.GoodsTypes.Service Then

SelectedForm = Metadata.Catalogs.Goods.Forms.ServiceForm;
StandardProcessing = False;

EndIf;

EndProcedure

This handler should be placed in the Nomenclature catalog manager module.

NOTE

The FormReceiveProcessing handler is not called if you try to open common forms, constant forms, settings storage forms, external reports and external processings.

7.8.3. Modification of Form Elements Properties

While you work with a form you might want to modify certain properties of form elements, e.g., their availability.

To do this, use the Items collection. This collection grants you access to the list of all form elements (regardless of their hierarchy).

You can access the items hierarchy using the Parent and ChildItems properties (for group, table and form elements).

Thus, you can make the form's Driver form element unavailable using the code below:

Elements.Driver.Enabled = False;

Please note how ReadOnly, Enabled and Visible properties are specified for elements with child items. Setting the property for the parent elements affects all the child form elements. However, the value of the modified property in the element does not change. In other words, the actual value of the ReadOnly, Enabled and Visible properties for a specific form element is defined based on AND concatenation of values for these properties of all the element parents.

Assume a DocumentCurrency folder contains Currency and ExchangeRate text boxes. If you want to make the entire group unavailable, you can use the following code:

Elements.DocumentCurrency.Enabled = False;

TIP

When you modify form elements properties programmatically, please avoid unjustified modification of the properties that have the following message in the Syntax Assistant: Calling the server is required on client property modification. It slows down form performance and requires extra requests to the server.

NOTE

If changing a form element changes the control location in the form (e.g., when form control visibility is modified), different event handlers can be called related to element activation (e.g., the OnActivateRow event will be called for a table).

If you change the View property programmatically for a form element with an extension (field, table, group or decoration), a new form element extension will be created. Form element properties related to the extension are set to default values and not propagated from the element extension modified before the View property was changed.

NOTE

Note that form element properties related to data being displayed (e.g., DataPath, TitleDataPath, etc.) can be modified only for new form elements and after the form control view has been changed.

7.8.4. Form Modification

You can modify a form programmatically. The following items can be modified (created, changed or deleted):

„ Form attributes

„ Local form commands

„ Form elements

NOTE

You can only delete the objects created programmatically.

Below is a general outline of how you can work with a form programmatically:

„ Change the contents of the form attributes

„ Change the contents of the form commands

„ Change the contents of the form elements

Please note that addition, change or deletion of the form components can only be performed on the server. It is worth noting that the form program model is not affected by the form user settings and functional options.

When the user sets up custom settings, they apply to the currently displayed form (with regard to the form's program modifications). If a user adds any form elements, accessing these elements from the 1C:Enterprise script is not available. You should remember this also when developing user interaction mechanisms. Thus, for example, if a user adds a page to a Page-type Group form element, when users open this page the CurrentPage property will be set to Undefined. The CurrentControl property of the form will also be set to Undefined if the active control is the user-defined element.

All the form modification steps are reviewed in detail below.

7.8.4.1. Change of Attribute Set

You can use the ChangeAttributes() method of the ManagedForm object to change (add or delete) attributes. In this case addition and deletions operations are included into a single call. Therefore, you can change properties of the form's attributes. Please note that attribute contents change is a resource-intensive operation (it comprises a complete form creation operation); this is why attribute contents change operations are usually batch-based. Review a detailed description of attribute creation methods.

First, you need to create the required number of FormAttribute objects. When an attribute is created, you should indicate its name, type and position in the form attribute hierarchy (see page 1-362).

Thus, to create a value table comprising two columns, you can use the following program code:

MyAttributes  = New Array;
MyAttributes.Add(New  FormAttribute("DataTable",
New  TypeDescription("ValueTable"),
,
"Value  table",
False));
MyAttributes.Add(New  FormAttribute("Vendor",
New  TypeDescription("CatalogRef.Contractors"),
"DataTable",
"Vendor  organization",
False));
MyAttributes.Add(New  FormAttribute("Product",
New  TypeDescription("CatalogRef.Goods"),
"DataTable",
"Product  name",
False));

Please note that for the last two attributes the last but one parameter specifies the attribute for which columns are created. In other words, you can add columns for the attribute types that allow it.

Fig. 177 shows attributes created in the form editor using the code above.

Fig. 177. Program Code Equivalent

After you have created all the required attributes in the form, you have to modify the attribute list:

ChangeAttributes(AddedAttributes, DeletedAttributes);

When this code is executed, the system first deletes the attributes listed in the DeletedAttributes array and then adds the attributes from the AddedAttributes array. After this the form is rebuilt.

When attributes are deleted, data they contain are lost; however, if the added and deleted attributes have compatible types or the added attribute differs from the deleted attribute by properties only (not the type), the data stored in the attribute are preserved.

After the attribute is added, it can only be included in the program code using the ThisObject.AttributeName construct. The ThisObject. expression is mandatory for attributes added programmatically.

If you want to change the contents or properties of the attributes, you should first obtain the attributes to be modified. To do this, you can use the GetAttributes() method.

Please note that the obtained list has two special characteristics:

„ This list is not dynamic; it does not track the attribute changes that take place after the method is called;

„ Although you can modify the obtained list, the changes you make have no effect on the real properties of the form attributes.

After you obtain the form attribute list you want, you can perform actions with the attributes (e.g., modify their titles) and then run the attribute modification method. Attribute changes should be preceded by their deletion.

For example, if you want to change the properties of the OrderParameter attribute, you should use the following code:

AttributeArray  = GetAttributes("OrderParameter");

...
//  Modify the attribute
...

DeletedAttributes  = New Array;
DeletedAttributes.Add("OrderParameter");

ChangeAttributes(AttributeArray,  DeletedAttributes);

7.8.4.2. Change of Command Set

To manage the form's set of commands, use a special Commands collection of the ManagedForm object. This collection can be used to add, delete and change the form's commands.

Thus, if you want to add a StatusSettingCommand with the Set status title that must be called by a handler named ProgramCommandHandler, run the following program code:

&AtServer
Procedure  OnCreateAtServer(Cancel, StandardProcessing)

Command = Commands.Add("StatusSettingCommand");
Command.Action = "ProgramCommandHandler";
Command.Title = "Set status";

EndProcedure

&AtClient
Procedure  ProgramCommandHandler(Command)
EndProcedure

The command handler must exist in the form module and must be preceded by the &AtClient compiler directive.

NOTE

A single handler can be used for multiple commands added programmatically.

7.8.4.3. Work with Form Elements

After all the required attributes and commands are created, you can start to add controls.

To manage form elements, you can use the Items collection of the ManagedForm collection. The latter can be used to add, delete and change properties of the form elements and move form elements between parents.

Using the Items collection you can access a list of form elements that does not account for the possible elements hierarchy. If you need to work with the hierarchy, you can use two properties of the Items collection: Parent and ChildItems.

The first property specifies the parent form element, e.g., the Parent property for a form field included in a group specifies a FormGroup form element.

The ChildItems property exists for the form elements that can have child items. For example, the ChildItems collection for a FormGroup form element will include the items from this group.

If you want to move an element between collections (e.g., between groups), you can use the Move() method. Parameters of this method describe the item to be moved, the new parent of the item and the form element that must follow the moved item.

If the last parameter of the method is not specified, the moved item is added to the end of the new parent item collection.

NOTE

When form element content is changed programmatically, different event handlers can be called related to element activation (e.g., the OnActivateRow event will be called for a table).

Review the control addition method in details.

The example below demonstrates how you can add two elements to a form:

„ A form field associated with a form attribute; „ A button associated with a form command.

&AtServer
Procedure  OnCreateAtServer(Cancel, StandardProcessing)

MyAttributes = New Array;

TypeString = New TypeDescription("String",
,
New  StringQualifiers());

MyAttributes.Add(New FormAttribute("ObjectDescription",
TypeString,
"",
"Object  Description", False));
ChangeAttributes(MyAttributes);

Command = Commands.Add("ChangeRow");
Command.Action = "ProgramCommandHandler";
Command.Title = "Change row";

Item = Items.Add("ObjectDescription",  Type("FormField"));
Item.Type= FormFieldType.InputField;
Item.DataPath = "ObjectDescription";

Item = Items.Add("ChangeRow",  Type("FormButton"));
Item.CommandName = "ChangeRow";

EndProcedure

...

&AtClient
Procedure  ProgramCommandHandler(Command)

ThisForm.ObjectDescription = "Command-generated object  description";

EndProcedure

The form where this code is added will look as shown on fig. 178. This is the form view after the user clicks the Change row button.

Fig. 178. Result of Program Form Modification

7.8.5. Working with Dynamic Lists

This section provides examples of some operations related to a dynamic list located in a form.

NOTE

The examples given below are not exhaustive. They only demonstrate various methods of working with dynamic lists.

7.8.5.1. The Dynamic List Query Parameter

This example shows how to set a dynamic list query parameter.

Assume that the following data query is specified for a dynamic list:

SELECT
Goods.Code As Code,
Goods.Description As Description,
Goods.SKU As SKU,
InventoryBalance.QuantityBalance As Quantity,
GoodsPricesSliceLast.Price As Price,
Goods.IsFolder
FROM
Catalog.Goods As Goods
LEFT JOIN AccumulationRegister.Inventory.Balance(, Warehouse =  &Warehouse) As
InventoryBalance
BY (InventoryBalance.GoodsItem = Goods.Ref)
LEFT JOIN InformationRegister.GoodsPrices.SliceLast(, PriceType =  &PriceType) As
GoodsPricesSliceLast
BY Goods.Ref = GoodsPricesSliceLast.GoodsItem

EndProcedure

Then, to set this query parameter you should (in the OnCreateAtServer() handler) specify the Warehouse and PriceType parameters as follows:

//  ItemsList – form attribute of DynamicList type
//  Parameters.Warehouse and Parameters.PriceType – form parameters of  corresponding types
&AtServer
Procedure  OnCreateAtServer(Cancel, StandardProcessing)

ItemsList.Parameters.SetParameterValue("Warehouse",  Parameters.Warehouse);
ItemsList.Parameters.SetParameterValue("PriceType",  Parameters.PriceType);

EndProcedure

7.8.5.2. Filter

This section provides examples that show you how to set and delete filters in a dynamic list.

Setting

The function adds a filter to a dynamic list and returns the filter item created.

Function  AddFilter(FiltersList, FieldName, Value, ComparisonType = Undefined, Use =  True)

NewItem =  FiltersList.Items.Add(Type("DataCompositionFilterItem"));
NewItem.LeftValue = New DataCompositionField(FieldName);
NewItem.ComparisonType = ?(ComparisonType = Undefined,
DataCompositionComparisonType.Equal,  ComparisonType);
NewItem.RightValue = Value;
NewItem.Use = Use;

Return NewItem;

EndFunction

Usage example:

//  DynamicList – form attribute of "DynamicList" type
//  The "Contractor" column should be in the list

//  Sets a filter by the "Contractor" field , filter value
//  is located in the "ContractorRef" variable, filter is enabled,
//  filter condition – equal.
AddFilter(DynamicList.SettingsComposer.FixedSettings.Filter,  "Contractor", ContractorRef);

Deleting

This procedure deletes a dynamic list filter and returns the deletion result. If a field name with the filter being removed is not specified, the filter list is cleared.

Function  DeleteFilter(FiltersList, FieldName = "")

If IsEmptyString(FieldName) Then

FiltersList.Items.Clear();
Return True;

EndIf;

Field = New DataCompositionField(FieldName);

FilterDeleted = False;
For Each FilterItem In FiltersList.Items Do

If FilterItem.Use And FilterItem.LeftValue = Field Then

FiltersList.Items.Delete(FilterItem);
FilterDeleted = True;

EndIf;

EndDo;

Return FilterDeleted;

EndFunction

Usage example:

//  DynamicList – form attribute of "DynamicList" type
//  The "Contractor" column should be in the list

//  The filter by "Contractor".field is deleted
Result  = DeleteFilter(DynamicList.SettingsComposer.FixedSettings.Filter,  "Contractor");

7.8.5.3. Group

This section provides examples that show how to set and delete groups in a dynamic list.

Setting

This function adds a group to a dynamic list and returns the group item created.

Function  AddGroup(GroupList, FieldName, Use = True, GroupType = Undefined)

Field = New DataCompositionField(FieldName);

NewItem =  GroupList.Items.Add(Type("DataCompositionGroupField"));
NewItem.Use = Use;
NewItem.Field = Field;
NewItem.GroupType = ?(GroupType =  Undefined, DataCompositionGroupType.Items, GroupType);

Return NewItem;

EndFunction

Usage example:

//  DynamicList – form attribute of "DynamicList" type
//  The "Contractor" column should be in the list
//
//  The group by field "Contractor" is created, the created
//  group will be used, group type – only items
AddGroup(DynamicList.SettingsComposer.FixedSettings.Group,  "Contractor");

Deleting

This procedure deletes a dynamic list group and returns the deletion result. If a field name with the group being removed is not specified, the group list is cleared.

Function  DeleteGroup(GroupList, FieldName = "")

If IsBlankString(FieldName) Then

GroupList.Items.Clear();
Return True;

EndIf;

Field = New DataCompositionField(FieldName);

GroupDeleted = False;
ItemsToDeleteArray = New Array;

For Each GroupItem In GroupList.Items Do

If GroupItem.Field = Field Then

ItemsToDeleteArray.Add(GroupItem);

EndIf;

EndDo;

For Each ItemToDelete In ItemsToDeleteArray Do

GroupList.Items.Delete(ItemToDelete);
GroupDeleted = True;

EndDo;

Return GroupDeleted;

EndFunction

Usage example:

//  DynamicList – form attribute of "DynamicList" type
//
//  Deletes all groups in the dynamic list
Result  = DeleteGroup(DynamicList.SettingsComposer.FixedSettings.Group);

7.8.5.4. Order (sorting)

This section provides examples of how to set and delete sortings in a dynamic list.

Setting

This function adds a sorting field to a dynamic list and returns the order item created.

Function  AddOrder(OrdersList, FieldName, Use = True, OrderType = Undefined)

Field = New DataCompositionField(Field);

NewItem = OrdersList.Items.Add(Type("DataCompositionOrderItem"));
NewItem.Use = Use;
NewItem.Field = Field;
NewItem.OrderType = ?(OrderType = Undefined,  DataCompositionSortDirection.Asc, OrderType);

Return NewItem;

EndFunction

Usage example:

//  DynamicList – form attribute of "DynamicList" type
//  The "Description" column should be in the list
//
//  Sets sorting on field "Description",
//  sorting direction – descending , sorting is used

AddOrder(DynamicList.SettingsComposer.FixedSettings.Order, "Description", DataCompositionSortDirection.Desc);

Deleting

This procedure deletes a dynamic list sorting and returns the deletion result.

If a sorting field name is not specified, the order list is cleared.

&AtClient
Function  DeleteOrder(OrdersList, FieldName = "")

If IsBlankString(FieldName) Then

OrdersList.Items.Clear();
Return True;

EndIf;

Field = New DataCompositionField(FieldName);

OrderDeleted = False;
ItemsToDeleteArray = New Array;

For Each OrderingItem In OrdersList.Items Do

If OrderingItem.Field = Field Then

ItemsToDeleteArray.Add(OrderingItem);

EndIf;

EndDo;

For Each ItemToDelete In ItemsToDeleteArray Do

OrdersList.Items.Delete(ItemToDelete);
OrderDeleted = True;

EndDo;

Return OrderDeleted;

EndFunction

Usage example:

//  DynamicList – form attribute of "DynamicList" type
//
//  Performs deletion (not disabling)of order by "Description" field
Result  = DeleteOrder(DynamicList.SettingsComposer.FixedSettings.Order,  "Description");

7.8.5.5. Conditional Appearance

This example shows how to set the dynamic list conditional appearance. The List dynamic list is used in the conditional appearance containing the Organization and Sum fields (Number-type). The example sets three conditional appearance items:

„ If the Sum value is less than 500, the Organization and Sum fields are highlighted in red.

„ If the Sum value is more than 500 but less than 10000, the text of all row fields is highlighted in blue.

„ If the Sum value is more than 10000, the Organization and Sum fields are highlighted in green.

The example also uses the filter setting function (see page 1-434).

Function SetConditionalAppearance(AppearanceList, CustomizedFieldsNames, AppearanceStructure, Use = True) Export

NewItem = AppearanceList.Items.Add();
NewItem.Use = Use;

// Set fields to change appearance, specified by the array of field  names
For Each FieldName In CustomizedFieldsNames Do

CustomizableField = NewItem.Fields.Items.Add();
CustomizableField.Use = True;
CustomizableField.Field = New DataCompositionField(FieldName);

EndDo;

// Set appearance specified by the structure,
// where – Key: appearance parameter name,
// and Value – appearance parameter value
For Each AppearanceItem In AppearanceStructure Do

NewItem.Appearance.SetParameterValue(AppearanceItem.Key,  AppearanceItem.Value);

EndDo;

Return NewItem;

EndFunction

An example of setting a conditional appearance:

ConditionalAppearanceItems  = List.SettingsComposer.FixedSettings.ConditionalAppearance;
CustomizableFields  = New Array;
CustomizableFields.Add("Amount");
CustomizableFields.Add("Organization");

//  ***** Set Red colors for the amount of less 500
Appearance  = New Structure;
Appearance.Insert("TextColor",  New Color(128,0,0));
NewItem  = List.SetConditionalAppearance(ConditionalAppearanceItems,  CustomizableFields, Appearance);

//  Set condition for appearance: Amount < 500
List.AddFilter(NewItem.Filter,  "Amount", 500, DataCompositionComparisonType.Less);

//  ***** Set Green colors for the amount of more than 10 000
Appearance  = New Structure;
Appearance.Insert("TextColor",  New Color(0,128,0));
NewItem  = List.SetConditionalAppearance(ConditionalAppearanceItems,  CustomizableFields, Appearance);

//  Set condition for appearance: Amount > 10000
List.AddFilter(NewItem.Filter,  "Amount", 10000, DataCompositionComparisonType.Greater);

//  Set Blue color, if the amount is in interval from 500 to 10 000
Appearance  = New Structure;
Appearance.Insert("TextColor",  New Color(0,0,128));

//  Transferring empty array as list of fields to change appearance
//  means changing the appearance of all fields in a row
NewItem  = List.SetConditionalAppearance(ConditionalAppearanceItems, New Array,  Appearance);

//  Create the "AND" conditions group
FiltersGroup  = NewItem.Filter.Items.Add(Type("DataCompositionFilterItemGroup"));
FiltersGroup.GroupType  = DataCompositionFilterItemsGroupType.AndGroup;

//  Set appearance condition: Amount > 500 AND Amount < 10000
List.AddFilter(FiltersGroup,  "Amount", 500, DataCompositionComparisonType.Greater);
List.AddFilter(FiltersGroup,  "Amount", 10000, DataCompositionComparisonType.Less);