Use Script Variables

As an application designer or story developer, you use script variables, which are useful for storing intermediate results repeatedly used in a script, for example.

About Script Variables

Script variables are reusable elements that store a value of a certain type, which exist throughout the runtime. The script variables you create in an application or story are available to itself only. You can define their values not only in the application or story, but also in its URL by adding a specific URL parameter.

For each script variable, you can define name, optional description, type and a default value, which is optional and depends on the variable type. A script variable can be defined as an array, which represents a set of values of the specified type. You can use the following primitive types:

  • string

    Represents text as a sequence of characters.

  • boolean

    Represents a logical value, either true or false.

  • number

    Represents a floating-point numerical value.

    Can be entered in ordinary format or scientific notation format such as 1e+20 or 1e20. If the number is longer than 21 digits, it will be automatically displayed in scientific notation format.

  • integer

    Represents a non-fractional numerical value.

    Scientific notation format isn't supported for entering values. However, at runrime if the number is longer than 21 digits, it'll be displayed in scientific notation.

In addition to the primitive types described above, you can select a wider variety of non-primitive types for the script variable, such as button, category, chart, clock, data source and table.

Create a Script Variable

Procedure

  1. In the Scripting area of the Outline panel, (for analytic applications) choose right next to Script Variables, or (for optimized stories) choose Start of the navigation path Next navigation step  Script VariablesEnd of the navigation path to add a new script variable.

    You can see the variable beneath Script Variables, and a new panel, Script Variable, is opened.

  2. In the panel, change the name of the script variable.
  3. (optional) Enter the description for the script variable.
  4. Choose the type of the script variable and whether to set it as an array.
  5. Specify the default value depending on the type.
  6. Choose Done to close the panel.

    You can now use the variable in scripting within this application or story.

Define a Script Variable's Value via URL Parameter

You can initialize the application or story based on your needs by simply making some changes to its URL. The value defined in the URL parameter can be passed to the corresponding script variable.

Procedure

  1. Choose the script variable you want to define, and go to the Scipt Variable panel.
  2. Select Expose variable via URL parameter.
    Note

    This option isn't available for array type variables and non-primitive type variables (types other than string, boolean, integer and number).

  3. Save the application or story with the changes and choose Run Analytic Application or View.
  4. In the URL of the analytic application or story, enter a new parameter that starts with ;p_ and is followed by the script variable's name and value.

    For example, if you want to set the value of ScriptVariable_1 to 3.14, add the following parameter to the original URL:

    ;p_ScriptVariable_1=3.14

  5. Reopen your application or story URL.

Use a Script Variable

You can use a script variable in your script as a local variable. For example, you change the value by assigning a new one and use this value by passing it as argument when calling a function.

If you write scripts in the application or story, you can insert the script variable you've created by selecting it from the value help in the script editor. You can activate the value help at any place in the script by pressing CTRL + Space .

If you need to use the script variable in calculation, you can type @ in the formula in Calculation Editor to insert it. All the available script variables will be automatically displayed in the dropdown list. Note that only global variables of string, integer and number types can be referenced in the calculation editor, while the array type isn't supported.

Note
When you use the script variable as the judging expression in an If statement and the expression returns a null value, the If statement will also return a null result. For example, if you write a script like this and set the script variable to undefined in runtime, the data returned and displayed in the chart isn't -100, but null.

if (ScriptVariable_1 = "xxx"; 100 ; -100)

You can also define script variables as the source of dynamic text in a text widget.

Change or Delete a Script Variable

To change an existing scripting variable, select it in the Outline panel. You can see the Scipt Variable panel open again where you can also make the changes there.

To delete an existing scripting variable, choose beside the script variable in the Outline panel, and select Delete.

Note

If the variable’s been used in a calculated measure, you need to modify the calculation first before deleting the variable.