Messages displayed to users

1C:Enterprise 8 provides tools for displaying messages. The UserMessage script object is intended for displaying errors, while the ShowUserNotification() method is intended for displaying notifications.

Let us consider a scenario where you need to check whether specific form fields are filled.

The platform provides a way to set up automatic fill checks for specific configuration object attributes. When a user attempts to write an object, if some of the attributes are not filled, the platform displays an error message. This message is linked to a form item. If you click the message, the focus is moved to the linked field and a balloon with the error message is displayed next to the field.

You can implement similar behavior using the script. The following example describes how automatic fill checks are performed during document posting.

When an object form starts executing the write command, control is passed to the server that converts object data into an actual object. After converting the object, the platform records the mapping between the object and the form attribute that stores object data to a location accessible for both client and server. Then the writing and posting process continues until a message must be displayed.

When an actual object "needs" to generate a message, it does not "know" it own location, it only "knows" that the attribute is not filled. So it creates a new UserMessage object, fills its Text property with the message text, and fills its Field property with the name of the unfilled attribute.

Then the following data must be passed to the form: which object generated the message and which object attribute the message is related to. This data is required for linking the message to a form item. To establish a link, the data object calls the SetData() method of the UserMessage object and passes itself as a parameter. This includes a search in available "object—form attribute name" mappings. If the object is found in the mappings, the SetData() method records the form attribute name to the DataPath property of the UserMessage object, and records the reference to the object (or register record key) to the DataKey property of the UserMessage object.

The message is now complete and ready for display. Once all of the server operations are completed, a package that contains messages is sent from the server to the client, and then the messages are displayed in the message window.

NOTE. While control is not yet returned to the client, you can get the array of messages using the GetUserMessages() global context method.

When a user double-clicks a message in the message window, the form checks the DataKey and DataPath properties. If a form has an attribute whose name matches the DataPath property value and the attribute reference matches the DataKey property value, an attempt to find the form item linked to the attribute is made. If the item is found, the focus is moved to it and the message is displayed next to the item.

If the DataKey property is filled but the form does not have an attribute whose name matches the DataPath property value, a new object form is opened and all messages having this data key (which is a reference to an object or a register record key) are displayed in this new form.

Creating messages using a script

Let us recreate this behavior using the script.

First, register the mapping between the object and the form attribute name. Use the SetObjectAndFormAttributeConformity() global context function, as in the following example:

&AtServer
Procedure ProcedureCalledFromClient(DataObject)    
    Document = FormDataToValue(Object, Type("DocumentObject.GoodsReceipt")); // Converting form data into an object
    SetObjectAndFormAttributeConformity(Document, "Object"); // Creating the mapping
    ObjectOperation(Document); // Opeartions on the object that might require displaying messages
EndProcedure

This script fragment converts form object data to an actual object and creates a mapping between the actual object and the "Object" form attribute.

To generate a message, use the following example:

&AtServer
Procedure ObjectOperation(DataObject)

    // Some operations that require displaying a message
    // Creating a message
    Message = New UserMessage();
    Message.Text= ShortageCount + " " + ItemUnitOfMeasurement + "shortage in row 11 of the ""Items"" tabular section";
    Message.Field = "Items[10].Count";

    // Mapping the actual object to a form attribute was performed
    // earlier by executing the SetObjectAndFormAttributeConformity method
    Message.SetData(DataObject);

    // The message properties DataPath and DataKey are now filled 
    // DataPath value changed from an empty string to the form attribute name
    // DataKey value changed from Undefined to the reference to the document

    // Displaying the message in the form.
    Message.Message();

    // The message will be displayed in the form
    // and linked to the Count field 
    // in the 11th row of the Items table 
    

EndProcedure;

This script fragment creates a UserMessage object that stores message Text and the object Field whose incorrect value caused the message generation. It takes the object position in the form from the "Object—FormAttributeName" mapping that was created earlier. Next, the message will be added to the form message window and linked to the corresponding form item.

IMPORTANT. The mapping between the object and the form attribute is only created for a specific object instance (not for its reference). The mapping is available until the object instance is deleted.

The platform also allows linking a message to a form manually. You might need this for displaying a message at client where object data is not available.

&AtClient
Procedure ObjectOperationOnClient(DataObject)

    // Some operations that require displaying a message
    // Creating a message
    Message = New UserMessage();
    Message.Text= ShortageCount + " " + ItemUnitOfMeasurement + "shortage in row 11 of the ""Items"" tabular section";
    Message.Field = "Items[10].Count";

    // Linking the object to the form manually
    Message.DataKey = DataObject.Reference;
    Message.DataPath = "Object";

    // Displaying the message in the form.
    Message.Message();

    // The message will be displayed in the form
    // and linked to the Count field 
    // in the 11th row of the Items table 

    ...

EndProcedure; 

NOTE. In both examples, the Text property refers to the 11th row while the Field value refers to the 10th row. This is because table row numbering in the user interface begins with 1, while the same numbering in the script begins with 0.

Examples of filling the Field property of the UserMessage object

Type Template Example

Attribute

AttributeName

Counterparty

Tabular section

TabularSectionName

Discounts

Tabular section attribute

TabularSectionName[RowIndex].AttributeName

Items[10].Count

Record set attribute

[RowIndex].AttributeName

[10].ExchangeRate


Next page: Nontransactional data reading

Be the first to know tips & tricks on business application development!

A confirmation e-mail has been sent to the e-mail address you provided .

Click the link in the e-mail to confirm and activate the subscription.