Form data types
The following data type categories are available in managed forms:
- 1C:Enterprise script types intended for use both in managed forms and outside of them. Examples: Number, CatalogRef.<name>, GraphicalSchema, SpreadsheetDocument.
- 1C:Enterprise script types intended exclusively to represent data of applied objects (catalogs, documents, and so on) in forms. Examples: FormDataStructure, FormDataCollection.
- DynamicList type, which is used in managed forms to display lists of applied objects.
All the applied object types (such as CatalogObject and others) do not exist on the thin and web client ends as they are only available on the server end. But developers need to display data of such objects in managed forms.
The following managed form data types are used for solving this task:
- FormDataStructure. This object stores a set of properties that can have any types. Available types include structures, collections, or structures with collections. For example, this type represents CatalogObject in forms.
- FormDataCollection. This object stores a list of typed values, similar to an array. Its elements can be accessed by index or by identifier. In some cases access by identifier is not available (this is determined by the type of applied object represented by the collection). Any integer can serve as an identifier. For example, this type represents tabular sections in forms.
- FormDataStructureAndCollection. This object is a structure and a collection simultaneously. It can be handled as any of these entities. For example, this type represents record sets in a form.
- FormDataTree. This object is used to store hierarchical data.
An applied object is presented by one or more form data items. In general, the hierarchy and content of form data depend on complexity of applied objects and on their interconnections.
For example, a document that contains a tabular section is represented by an object of the FormDataStructure type (the document itself) that has FormDataCollection (document tabular section) as a subordinate object.
Attention! Remember that applied objects are only available on the server, while you can use form data objects both on the server and on the client.
Actually form data is a unified presentation of various applied objects that is available both on the server and on the client. Forms use unified methods of processing this data.
The form attributes pane of the form editor usually displays the applied types stored in the attributes rather than form data types.
For example, if an Object attribute contains data of a Customers catalog item, the Type column does not display the actual form attribute type (DataFormStructure) and instead displays the type of the applied object whose data is stored in the attribute (CatalogObject.Customers). To indicate that it is not the actual attribute type, the applied object type is enclosed in parentheses.
Hence, a form contains some projection of applied object data as its own data types and automatically makes conversions between these types if required.
But if you implement a custom data processing algorithm, you have to include data conversion between applied object types and form data types to that algorithm.
A set of global methods is available for converting applied objects into form data and back:
- ValueToFormData() converts an applied object to a form data item
- FormDataToValue() converts a form data item to an applied object
A managed form itself also has similar methods for converting values of form attributes into applied objects and back:
- ValueToFormAttribute() converts an applied object into a managed form attribute
- FormAttributeToValue() converts a managed form attribute into an applied object value
The methods that process applied objects are only available in server form procedures.
When you perform standard form operations on the main attribute (opening the form, execution of the standard Write command, and so on), the conversion is performed automatically.
Let us review an example of data conversion within a custom algorithm.
Suppose you have a special form where one of the attributes (ProductToModify) uses data of the Products catalog. When a form is created on the server, some algorithm determines the product whose data should be stored to the form attribute, reads the product data, converts its type, and stores it to the form attribute. This includes a call of the ValueToFormData() method (listing 27.1).
Listing 27.1. Example of converting applied object data into form data
&AtServer Procedure OnCreateAtServer(Cancel, StandardProcessing) ObjectProduct = Catalogs.Products.FindByDescription("Coffee pot").GetObject(); ValueToFormData(ObjectProduct, ProductToModify); EndProcedure &AtClient Procedure Write() WriteAtServer(); EndProcedure &AtServer Procedure WriteAtServer() ObjectProduct = FormDataToValue(ProductToModify, Type("CatalogObject.Products")); ObjectProduct.Write(); EndProcedure
At some point of form operations you decide that modified product data should be recorded to the database. So you convert form data back into an applied object by calling FormDataToValue(), and then write it.
As we mentioned above, a form also has methods for converting applied data into form attributes and back.
Such methods are generally more convenient because they have access to form attribute type. Besides, the FormAttributeToValue() method sets a correspondence between form data and the object that is used to generate messages.
Let us review an example of using this method.
Suppose you get an applied object from a form attribute in a server form procedure and then use the Recalculate() method of this applied object. Then the object data is modified according to the recalculation and converted back into a form attribute (listing 27.2).
Listing 27.2. Example of converting applied object data into form data
&AtServer Procedure RecalculateAtServer() // Converting the Object attribute to an applied object. Document = FormAttributeToValue("Object"); // Recalculating using a method defined in the document module Document.Recalculate(); // Converting the applied object back to an attribute. ValueToFormAttribute(Document, "Object"); EndProcedure