Using doCalculations() or "Run Calculations" in JavaScript Buttons

doCalculations() is a Helper Function in CallScripter Synergy which re-evaluates all fields and values on a page. It is included automatically in most instances where it is required, and only normally needs to be invoked manually in specific uses of a JavaScript Button. Unnecessary use can create additional load on the client, whereas failure to use it at the appropriate points can lead to unexpected results such as the page appearing outdated.
Note: as of Synergy version 18, there is now a "Run Calculations" option within the JavaScript Button's configuration menu, which when enabled causes doCalculations() to be run when the button code completes.


As part of a script, an agent clicks a button that builds some text based on the caller's choices, which is then displayed as a Text Label for the agent to read. Writing a value to a variable which is then displayed on a text label is a good example of when doCalculations() is required for the page to display correctly.


The execution of this example is simple, simply place a Text Box, Text Label, and JavaScript Button on a script page, and create a new variable called [var_labelText]. Place [var_labelText] in your Text Label so that the contents of the variable will be displayed:


If we then add the following code to our JavaScript Button, then any text entered in the Text Box should be displayed on the Text Label when the JavaScript Button is clicked:

[var_labelText] = [Text Box];


However, if you try this you will find that clicking the button seemingly doesn't do anything - until you type in the Text Box again and then click out of the field, at which point the Text Label will display the outdated text!


This is because the JavaScript Button isn't causing the page to be re-evaluated when it is clicked or when it completes its contained code. The reason the button seems to cause the display of the outdated label when clicked for the second time is actually because clicking out of the Text Box causes the page to be re-evaluated before [var_labelText] has been updated.


We can remedy this in one of two ways: adding doCalculations() to the code in the JavaScript Button, or enabling Run Calculations in its options:

[var_labelText] = [Text Box];


This makes the page re-evaluate as soon as the contents of the JavaScript Button have been completed, giving us the expected behaviour:



When Not to Use

In almost all circumstances, the use of doCalculations() is not suggested - specifically, it should never be used in a Calculate field (as this automatically runs doCalculations() at the end of the specified code), and generally shouldn't be used in JavaScript buttons that aren't setting the value of a variable.

In the case of a JavaScript Button that sets a variable, it may not be necessary even then, if the JavaScript Button is calling another field that automatically runs doCalculations() - for instance, if the JavaScript Button also clicks an External Data Source field (as the External Data Source field will run doCalculations() upon its completion).

If unsure as to whether to use it, it's recommended to test the page in preview, and only include doCalculations() manually if it appears that the set variable isn't being updated at the correct time.