Understanding JavaScript context in form design

About this topic

This topic assumes a basic understanding of how to use JavaScript variables and create protocols in the VWorks software.

About JavaScript context and form design

The JavaScript variables used in protocols and in the forms that run the protocols can be in either the global context or the context of the running protocol.

When designing a form, you specify the JavaScript context in three locations:

1	Protocol. In the Protocol Options area, you select or clear the Use global context for this protocol check box to specify the context for the variables in the protocol.

2	Form. In the Form Designer window, you select or clear the Use global context for variables check box to specify the context for the variables in the form.

3

Individual controls in the form. If the form’s Use global context for variables check box is selected, the context setting for all the controls that use JavaScript is already set. If the form’s Use global context for variables check box is not selected, you can select the Always use global context check box in the control properties for individual controls that use JavaScript.

 

Protocol’s JavaScript context

For each protocol, you specify the context in the Protocol Options area:

•	Global context. Variables of the same name in the given protocol will be available across all protocols that also specify the global context.

•	Context of the running protocol. Prevents the variables in a given protocol from being impacted by changes to variables of the same name in other protocols.

Form’s JavaScript context

In the Form Designer window, you select or clear the Use global context for variables check box to specify the context for the form.

•	Global context. All variables throughout the entire form will be in the global context.

•

Context of the running protocol. The variables in each individual control in the form will be in the context of the associated (running) protocol, unless the control specifies the global context. When no protocol association exists (the protocol is not running or scheduled to run), the individual controls that do not specify global context will retain their most recent previous value.

The global context may not be necessary if the variable in question will communicate with the protocol after the protocol is running or is scheduled to run.

No JavaScript objects that exist in a context other than the global context and the protocol's context will be accessible from either kind of form. For example, plate objects, plates[] array objects, and task objects will not be accessible. If you want the data from any of these objects to be shown on the form, the protocol must contain JavaScript statements at appropriate points to copy the relevant data into JavaScript variables that you devise.

Individual control’s JavaScript context

In the Form Designer window, when you set the properties for a control that has an assigned JavaScript variable, you select or clear the Always use global context check box to specify the context.

•	Global context. The variable in question will be available to the protocol and to other controls that also use the global context before the protocol is running or is scheduled to run.

If two controls on the form must communicate with each other, the global context is required for each control. For example, the following figure shows a Slider control and a display (Static text control). As the slider moves, the value in the display updates to match the slider’s position.

 

•	Context of the running protocol. The variable in question will be available to the protocol only after the protocol is running or is scheduled to run.

Runsets and the global context

If you have a set of protocols designed to be a runset that will be launched by a form, you use the global context for both the protocols and the form.

Note: Alternatively, you can use the JavaScript function, GetGlobalObject, to access the global context for any variable within the protocol that should interact with the form. See VWorks-defined functions.

IMPORTANT Multiple protocols designed to run together in the same runset should not reuse the same JavaScript variable names unless the variables are intended to share data.

Context scenarios

The following figure shows four protocols (A, B, C, and D). Form 1 runs protocol A, and protocols B, C, and D run without using a form.

•	Protocol A uses its own context for variables.

•	Protocols B, C, and D use the global context for variables.

•	Form 1 uses the context of the running protocol, except for two of its controls, a pushbutton and a file browsing control, which use the global context.

Figure. Example of relationships between the protocol, form, and control context settings

 

Suppose that protocol A does not use the global context because it uses a variable x to count the number of times a loop has executed. But, protocol D also uses a variable called x for something completely different. Even though both protocols may run at the same time, their JavaScript variables will not interfere with each other because protocol A uses its own private context.

Suppose that protocols B, C, and D must use the global context because each of these protocols keeps track of the total volume dispensed by all protocols in a variable called totVol. Whenever any of these protocols executes a Dispense task, it also executes the JavaScript: "totVol += task.volume;". When all three protocols are done, the total volume dispensed in all three protocols can be accessed in a single variable.

In Form 1, the File Browsing control and Pushbutton control are in the global context so that so that the two controls can communicate with each other. The Pushbutton control executes a script that uses a JavaScript variable of fileName, which must also be specified by the File Browsing control. Now imagine that the user has typed, C:\myfile.txt in this control. When the user presses the Pushbutton control, whatever string happens to be showing in its File Browsing control at that time is assigned to the variable fileName in the global context. Now, not only does the script in the Form 1 Pushbutton control recognize the variable fileName as having a value of C:\myfile.txt, so would all the scripts throughout protocols B, C, and D.

Related information

 

For information about...	See...
Creating or editing a form	Workflow for creating or editing a form
Controls under General Controls in the Form Designer window	Adding form controls that allow editing or runtime data display
Form properties in the Form Designer window	Setting the form properties
Creating a basic protocol	Workflow for creating or editing a form
Working with JavaScript	Creating a protocol: advanced topics