Understanding 1C:Enterprise script
In the previous lesson you wrote the handler of the MaterialsQuantityOnChange event (listing 4.1) and we provided a brief description of its functioning.
Now we will describe two approaches to understanding numerous unfamiliar configuration object properties and methods, which will help you study script fragments and create custom 1C:Enterprise script procedures.
The Syntax Assistant is a developer tool. It stores descriptions of all script objects available in the platform along with their methods, properties, events, and other related information.
To open the Syntax Assistant
- Click the button on the Designer mode toolbar (fig. 5.20).
On the Help menu, click Syntax Assistant.
Fig. 5.20. Opening the Syntax Assistant
Same as any other help system, the Syntax Assistant has a tree-like structure with chapters, sections, subsections, and so on. Using the Syntax Assistant is more convenient than using any of the printed 1C:Enterprise script documentation because it is readily available and supports context-sensitive help (Ctrl+F1).
In addition to that, each Syntax Assistant page has a Methodical information hyperlink at the bottom (see fig. 5.20). Clicking this link opens a browser window with a list of methodical materials related to the current topic. These may include 1C:Enterprise knowledge base articles, 1C:Developer Network articles and forum topics, and more. New methodical materials are added as soon as they become available online. This provides developers with additional options for getting answers to their questions without interrupting their work.
Using Syntax Assistant to analyze script
The Syntax Assistant is handy when you need to understand the script written by another developer. We will explain how to use it on the example of the MaterialsQuantityOnChange event handler that you wrote earlier (see listing 4.1).
Analyzing script with Debugger
The Debugger tool comes handy when you write custom script. While the Syntax Assistant requires you to understand the execution context, the object structure, and more, Debugger requires none of these.
You can simply stop at any point of your program and view the available properties or script objects.
Debugger is a tool that facilitates development and debugging of 1C:Enterprise modules. It provides the following capabilities:
- Step-by-step module execution
- Setting breakpoints
- Pausing and resuming module execution
- Debugging multiple modules simultaneously
- Calculating expressions to analyze variable states
- Viewing procedure and function call stack
- Pausing upon error
- Editing modules during the debugging
For now we will not discuss all these features in detail but will instead discuss Debugger use cases on the example of the MaterialsQuantityOnChange event handler (listing 4.1).
When you are editing module script in Designer, the commands of the Debug menu that set and clear breakpoints are available. The script execution is paused at lines that have breakpoints. During a pause you can analyze the current values and types of module expressions and variables and continue the execution up to the next breakpoint, and so on.
- Open the GoodsReceipt document form, click the Module tab, and look at the MaterialsQuantityOnChange procedure.
Note that the commands for breakpoint operations are now available in the Debug menu and on the Designer mode toolbar (fig. 5.36).
Fig. 5.36. Breakpoints toolbar
To set a breakpoint
- Double-click in the vertical bar to the left of the script line.
Move the cursor to the module line and then, on the Debug menu, click Breakpoint.
Click the Breakpoint button on the toolbar.
This adds a breakpoint icon to the left of the script line.
- Double-click the breakpoint icon to the left of the script line.
Move the cursor to the script line with the breakpoint and then, on the Debug menu, click Breakpoint.
Click the Breakpoint button on the toolbar.
- On the Debug menu, click Clear all breakpoints.
Click the Clear all breakpoints button on the toolbar.
- Double-click in the vertical bar to the left of the script line.
- Double-click in the vertical bar to the left of the first line of the MaterialsQuantityOnChange procedure (fig. 5.37).
Fig. 5.37. Setting a breakpoint in the MaterialsQuantityOnChange procedure
To debug a 1C:Enterprise script algorithm, you have to run the application that executes that algorithm in the debug mode.
- On the Debug menu, click Start debugging.
Click the Start debugging button on the toolbar.
Designer starts 1C:Enterprise in the debug mode. Actually this is exactly what you have done before but you have not set any breakpoints and the applied solution execution was never paused.
- Open the list of Goods receipt documents and open any of the two documents that you created.
- Edit the Quantity field in any document row.
Once you do it, the program execution is interrupted and the MaterialsQuantityOnChange procedure is opened in Designer at the breakpoint location. An arrow over the breakpoint icon indicates the module line that is being executed (fig. 5.38).
Fig. 5.38. Pausing a program at a breakpoint
Note that the commands for debugging the configuration are now available in the Debug menu and on the Designer mode toolbar (fig. 5.39).
Fig. 5.39. Configuration debugging toolbar
The Step Over, Step In, and Step Out buttons continue step-by-step script execution.
The Continue Debugging button continues debugging up to the next breakpoint.
The Immediate Window and Evaluate expression buttons are intended for viewing expression values at the current breakpoint.
The Call Stack button is intended for tracing the sequence of procedure and function calls.
But for now the program is already paused at the specified line of the MaterialsQuantityOnChange procedure. Note that this line has not been executed yet so the variable values are not assigned yet. You can use the Step Over button to view their values after the line is executed.
Let us look at the Items.Materials.CurrentData expression and view the content of that object at the current breakpoint.
- Double-click the Items word and then click the Evaluate expression button (Shift+F9) on the configuration debugging toolbar.
The Items value is added to the Expression field. The Value and Type columns display the value and type of this object. You can see that the Items object is a FormAllItems value collection, which stores all of the form controls. Expand this object branch (fig. 5.40).
Fig. 5.40. The Items object
Above the Result pane you can see the Show Values in Separate Window button. If you click this button (or press F2), you will be able to view the collection contents.
Next, let us check the Materials expression.
- Find Materials in the list of form controls.
You can see that it is a FormTable object. Expand this object and review its properties. The property we are interested in is CurrentData.
- Find the CurrentData branch and expand it.
You can see the data stored in the current tabular section row, with values and types. Note that Quantity has the value that you have just set (fig. 5.41).
Fig. 5.41. Items.Materials.CurrentData object
- Close the Expression window.
Then let us step to the procedure of the common DocumentProcessing module where the TabularSectionRow value is calculated.
- Click Step In on the configuration debugging toolbar twice. This program execution is now paused at the CalculateTotal procedure of the common DocumentProcessing module.
- Double-click TabularSectionRow to select it and then click Evaluate expression.
- Expand the TabularSectionRow object (fig. 5.42).
Fig. 5.42. The TabularSectionRow object
You can see that the TabularSectionRow variable contains a FormDataCollectionItem object. But the values in the Total column are not recalculated because the second line has not been executed yet.
- Close the Expression window and click the Step In button on the configuration debugging toolbar.
The platform executes the CalculateTotal procedure of the common DocumentProcessing module and pauses at the end of the procedure.
- Move the pointer over the Quantity or Total word to view a tooltip with its current value (fig. 5.43).
Fig. 5.43. The TabularSectionRow object
You can see that the values in the Total column are recalculated, so the Items.Materials.CurrentData object now contains new values.
After you analyze the variables and expressions, you can continue with debugging.
To continue debugging
- Click the Continue Debugging button.
To stop debugging
- On the Debug menu, click Stop.
Note that you can set a breakpoint inside a loop and see how values are changed during each iteration.
You can edit the configuration and save the changes during the debugging.
Important! Although you can edit a module that is being debugged, Debugger does not compile the modified script, and debugging is continued for the database configuration script (the script that was available at the moment when Debugger was started or when the connection was opened). To debug the changes that you made, you have to update the database configuration first.
Finally, let us discuss some handy debugging techniques.
When you are in a form module and you want to write a handler, you can use the ThisObject property to view the context properties of the current form along with its available extensions and other available items.
To view ThisObject property
- After you stop at a breakpoint, click the Evaluate expression button (Shift+F9) on the configuration debugging toolbar.
- In the Expression field, enter ThisObject and click Evaluate (fig. 5.44).
Fig. 5.44. ThisObject property of a managed form
If you expand this item, you will see the type and properties of the 1C:Enterprise script objects available at the current breakpoint.
And when you are in an object or record set module, you can use ThisObject property in a similar manner to view the properties of the object or record set module context.
The first method is searching for a topic in the table of contents by following down the tree while expanding the subsections, properties, links, and so on.
Let us take a look at the first line of our handler (listing 5.19).
Listing 5.19. MaterialsQuantityOnChange procedure (first line)
TabularSectionRow = Items.Materials.CurrentData;
To understand this script, you need to know the execution context. The program context depends on the module where the script is located. In this case the handler procedure is located in the form module, so we are in the form module context.
Let us review this script line from left to right. What is TabularSectionRow? If something is located to the left of the assignment operator (=), it is either a property that is available directly in this context or a variable.
According to the algorithm described in the previous section, you have to make the following checks:
- Is the TabularSectionRow variable declared in the form module?
Open the form module (to learn how to open a module, see Module types). There is no variable description line (Variable TabularSectionRow;) so this is not a form module variable.
- Does the form have the TabularSectionRow attribute?
Open the form of the GoodsReceipt document and check the form attributes pane located in the upper right part of the form editor (fig. 5.21).
Fig. 5.21. List of attributes of the GoodsReceipt document form
You see that this form has a single Object default attribute (displayed in bold). This means that the form does not have the TabularSectionRow attribute.
- Does the ManagedForm object have the TabularSectionRow property?
Let us look at the list of the managed form properties in the Syntax Assistant.
Open the Syntax Assistant and click the Contents tab.
A managed form is an interface object of a managed application, so expand the Interface (managed) / Managed form section, then expand the ManagedForm object and its Properties (fig. 5.22).
Fig. 5.22. List of ManagedForm object properties in the Syntax Assistant
The properties are sorted alphabetically. You can see that there is no TabularSectionRow property among them.
- Does the form extension have the TabularSectionRow property?
You know that the default form attribute stores data of the DocumentObject.GoodsReceipt object (see fig. 5.21). This means that the properties and methods of the 1C:Enterprise script object Managed form extension for documents (Syntax Assistant / Interface (managed) / Managed form / Managed form extension for documents) are available in the form module. Let us review them (fig. 5.23).
Fig. 5.23. List of properties of the managed form extension for documents in the Syntax Assistant
You can see that there is no TabularSectionRow property among them.
- Does the TabularSectionRow global context property exist?
Open the global context properties in the Syntax Assistant (fig. 5.24).
Fig. 5.24. List of global context properties in the Syntax Assistant
You can see that there is no TabularSectionRow property among them.
The TabularSectionRow expression also cannot be a name of a nonglobal common module because its procedures should be called using a dot (TabularSectionRow.).
This expression also cannot be an exported procedure of a global common module because in this case one would call the procedure as TabularSectionRow() instead of assigning anything to it.
- Does the managed application module contain the TabularSectionRow exported variable?
Open the managed application module (to learn how to open a module, see Module types). There is no variable description line (Variable TabularSectionRow Export), so this is not a variable of a managed application module.
Now you see that the TabularSectionRow expression is a local variable of the MaterialsQuantityOnChange procedure. During the script execution a value is assigned to the variable. The 1C:Enterprise script type system allows assigning a value of any type. If a variable is local, i.e. it is only used in the context of this particular procedure, it does not require explicit declaration. The variable is declared when it is first used.
To the right of the assignment operator you can see the Items.Materials.CurrentData expression. To learn the meaning of Items, let us use the same algorithm as with the TabularSectionRow local variable.
- Is the Items variable declared in the form module? No.
- Does the form have the Items attribute? No.
- Does the ManagedForm object have the Items property?
Let us look at the list of properties of the ManagedForm object again. There is the Items property among them, so Items is one of the managed form properties. To learn its meaning, double-click it (fig. 5.25).
Fig. 5.25. Description of the Items property of the ManagedForm object in the Syntax Assistant
The bottom pane of the Syntax Assistant window displays the description of the selected property. This description states that the Items property contains the FormAllItems object that stores a collection of all form controls.
To learn its meaning, click the FormAllItems link. This opens the description of the FormAllItems collection (fig. 5.26).
Fig. 5.26. Description of the FormAllItems collection in the Syntax Assistant
Note. The Syntax Assistant tree above is not changed. To locate the tree branch that stores the current topic, in the Syntax Assistant, click the Find current element in the tree button above the object description pane.
This collection contains the controls available in a managed form. You can access an item by its name.
So now you know what Items mean. The next word is separated from Items by a dot: Items.Materials. The collection has a <Control name> property, so Materials is a form control name. Let us look at the structure of form controls. Open the GoodsReceipt document form and look at the form controls pane located in the upper left part of the form editor (fig. 5.27).
Fig. 5.27. Structure of form controls of the GoodsReceipt document
The form controls include the Materials table. If you open the property palette of this table, you can see that its title is Properties: Table (fig. 5.28).
Fig. 5.28. Property palette of a table form control
It means that this form control is a table, so we need an object of the FormTable collection. To learn its meaning, click the FormTable link (see fig. 5.26). You will see a list of properties of the FormTable object. The properties are sorted alphabetically (fig. 5.29).
Fig. 5.29. List of properties of the FormTable object in the Syntax Assistant
So now you know what Items.Materials mean. The next word is separated from Items.Materials by a dot: Items.Materials.CurrentData. Scroll through the list of managed form table properties to find the CurrentData property. It is one of the properties of the FormTable object. To learn its meaning, double-click it (fig. 5.30).
Fig. 5.30. Description of the Current Data property of the FormTable object in the Syntax Assistant
The bottom pane of the Syntax Assistant window displays the description of the selected property. This description states that the CurrentData property contains the FormDataStructure object that contains data stored in the current table row.
So once the first line of the handler (TabularSectionRow = Items.Materials.CurrentData;) is executed, the TabularSectionRow variable contains an object of the FormDataStructure type.
Now let us review the next line of the handler (listing 5.20).
Listing 5.20. MaterialsQuantityOnChange procedure (second line)
TabularSectionRow.Total = TabularSectionRow.Quantity * TabularSectionRow.Price;
It is reasonable to suggest that Total, Quantity, and Price are properties of the FormDataStructure object that is recorded to the TabularSectionRow variable during the execution of the first line. To learn its meaning, click the FormDataStructure link (see fig. 5.30, 5.31).
Fig. 5.31. Description of the FormDataStructure object in the Syntax Assistant
The description of this object states that you can use the FormDataStructure object to access the data of a specific tabular section column using the column name as the object property. So using the expression TabularSectionRow.Total you access the data stored in the Total column of the current table row. And the product of data in the Quantity column and data in the Price column is recorded to the Totals column.
The second method involves using context help provided by the Syntax Assistant. You can do it by opening a module, moving the cursor to a 1C:Enterprise script clause, and pressing Ctrl+F1.
- Open the GoodsReceipt document form, click the Module tab, and find the code of the MaterialsQuantityOnChange procedure.
You already know that the TabularSectionRow expression located to the left of the assignment operator is a local variable.
To the right of the assignment operator you can see the Items.Materials.CurrentData expression.
- Move the cursor to the Items word and press Ctrl+F1.
The Syntax Assistant searches all of the 1C:Enterprise script expressions for Items and sorts the results alphabetically (fig. 5.32).
Fig. 5.32. Opening context help in the Syntax Assistant
You can see that the expression is found because a new window with the list of topics that contain the expression is displayed. Each topic includes its full path in the Syntax Assistant tree structure. Slash (/) is used as a separator between structure levels. You can move the pointer over the list of topics to find the one you need.
But the list of topics is quite lengthy so it may be difficult to search through it manually. Let us find the Items property that is used in the managed form.
- In the list of topics, press Ctrl+F and then, in the Find field, enter ManagedForm.
- Click Find.
The selection is moved to the required topic (fig. 5.33).
Fig. 5.33. Searching the list of topics in the context help
- Click Show.
The selected topic is opened in the bottom pane of the Syntax Assistant (fig. 5.34). Note that the Syntax Assistant tree above is not changed. You can locate the topic in the tree by clicking the Find current element in the tree button above the pane that displays the topic.
Fig. 5.34. Description of the Items property of the ManagedForm object
The Contents tab of the Syntax Assistant displays the topic position in the tree. So you can see that Items is a property of the ManagedForm object.
Then, when you click the links as described in method #1, you will learn what is assigned to the TabularSectionRow variable and how you can access data in its columns.
The Syntax Assistant has another handy feature. You can filter the assortment of objects included in the Syntax Assistant. Since you are currently in a client and in a form, it is reasonable to view only the 1C:Enterprise script objects that are available in the thin client and web client modes.
- On the Tools menu, click Options.
Click the Enables you to change settings button above the object topic in the Syntax Assistant.
- On the Help tab, select or clear the check boxes that represent available modes (fig. 5.35).
Fig. 5.35. Filtering objects displayed in the Syntax Assistant
Important! If you want to use the Syntax Assistant when you are writing a procedure that will be executed, for example, on the server, remember to select the respective run mode to have the Syntax Assistant display objects available in this mode.