416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
This is the support page for the legacy Dundas Dashboard application. For assistance with the current Dundas BI application please click here.
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Using Script Modules

Hide navigation
RSS
Modified on Tue, 18 Sep 2012 10:41 AM Categorized as Design, Scripting
Click to return to: Documentation | Designing Dashboards | Scripting in Dundas Dashboard


Overview

A script module resource contains definitions of DundasScript functions which can be called from other script modules or from a referencing dashboard or dashboard template. Script modules make it possible to build a library of reusable functions that can be shared between dashboards or projects.

In order to call a function within a script module, a dashboard or dashboard template must add the module to its list of module references. Once added, any interaction script defined within the dashboard or dashboard template can call a function within the referenced module simply by qualifying the function call with the name of the script module. Script modules can also reference other script modules; this allows functions defined in one module to call functions defined in other modules.

Here is an example of calling a script function:

// Click interaction script for a Button control on a dashboard that references a script module. int result = MyScriptModule.MyScriptFunction("hello world", 1, 2.0); services.ShowMessage(result);

Tip: Script modules let you centralize code in one place; this can save you from having to make the same code changes across multiple dashboards.

Script module resources

Adding a new script module

Follow these steps to create a new script module resource:

  1. Go to the Design Explorer and expand the Project Resources folder (or Shared Resources folder if you want the script module to be available globally across projects).
  2. Right-click over the Script Modules folder, and then choose New Script Module.
    New Script Module.
  3. Click inside the text box that appears, type a name for the script module or accept the default name, and then press ENTER. A new script module item appears under the Script Modules folder, and a script editor opens in the content area to let you write the corresponding script functions.
    Script Editor opens.
  4. At the top of the script editor, click References if you want to add a reference to another script module. This will let you call functions contained in that other module (or modules). You can choose to reference a module from the same project, or from shared resources.
    References button.
  5. Write one or more script functions. If you need to call a function from a referenced script module, simply qualify the function name with the name of the function's script module.
    Write functions.
  6. Click the Build button in the script editor to verify there are no syntax errors.
  7. Click Save from the application toolbar to save your changes.
  8. Click Check In to check in the script module for the first time.

Tip: In the Design Explorer, you can create sub-folders under the Script Modules folder in order to better organize your script modules.

Note: A script module name must begin with an alphabetic character (&ie; A to Z, or a to z), and its remaining characters must be alphanumeric (&ie; A to Z, a to z, or 0 to 9).

Here is an example script module listing (which you can copy and paste):

// Add three numbers. int Add3(int a, int b, int c) { int s = a + b + c; return s; }

// Multiply two numbers. double Mult2(double a, double b) { double m = a * b; return m; }

// Do something. void DoSomething() { services.ShowMessage("hello world!"); }


Editing a script module

To edit an existing script module:

  1. From the Design Explorer, right-click on the desired script module, and then choose Edit. The script module's functions are displayed in the script editor.
    Edit script module.
  2. If necessary, click Check Out from the application toolbar.
  3. Modify the script functions as desired.
  4. Click the Build button in the script editor to verify there are no syntax errors.
  5. Save and check in your changes.

Renaming a script module

To rename an existing script module:

  1. From the Design Explorer, right-click on the script module, and then choose Rename.
  2. Click inside the text box that appears, type in the new name for the module, and then press ENTER.

Warning: If you rename a script module, you will need to modify scripts in other modules, dashboards or dashboard templates that reference the old module name.

Deleting a script module

To delete an existing script module:

  1. From the Design Explorer, right-click on the script module, and then choose Delete.
    Delete script module.
  2. In the Confirmation dialog, click Delete to perform the actual deletion.

If the script module is referenced by any dashboard or dashboard template, the deletion will not be performed. To check which dashboard items are dependent upon a script module, go to the Dependencies tab of the Properties window for the script module.

Dependencies tab for a script module.

Dependencies tab for a script module.


Using script functions

Adding a reference to a script module

In order for a dashboard or dashboard template to access the functions inside of a script module, it must have a reference to the module. If this is the case, any interaction script at the dashboard-level or dashboard control-level will be able to call functions defined within the module.

To add a reference to a script module from a dashboard or dashboard template:

  1. Edit the dashboard or template.
  2. Click on the canvas outside of any controls in order to access the properties of the dashboard/template.
  3. In the Properties window, click the Show advanced properties button.
  4. Click the ellipsis button of the References advanced property.
    References advanced property.
  5. In the References dialog, select the project or shared resource script modules that you want to use, and then click OK.
    References dialog.

The References property is updated in the Properties window to show the number of modules referenced.

Tip: You can also add references to script modules from within the script editor (⪚ while you are writing an interaction script). Simply click the References button in the script editor toolbar.

Calling a script function

Once references have been added, you can call a script function by qualifying the call with the name of its script module. For example, the figure below shows the calling of a script function from the Click interaction of a Button control on the dashboard.

Calling a script function.

Calling a script function.


Access modifiers: public and private

The access modifiers, public and private, are supported in function definitions. If you omit the modifier, the access level defaults to public, which means that the function is accessible to callers outside of the script module.

Use the private access modifier for functions that should not be visible to calling scripts (⪚ a helper function that performs some intermediate step or calculation).

Below is an example script from a script module (named ScriptModule2) that uses access modifiers:

private int HelperFunction(int x, int y) { int z = x + y; return z; }

public int ComputeSomething(int a, int b) { int c = ScriptModule2.HelperFunction(a, b); return c; }


Notes

Some additional notes:

  • You can create script modules with the same name as long as they exist in different folders.
  • If you reference two script modules that have the same name, you will have access to functions from both modules. However, none of the functions can have the exact same signature (&ie; same function name and same list of parameters).
  • Overloaded functions are supported (&ie; functions with the same name but different list of parameters).
  • Functions can return void.
  • Script modules can only contain static functions. Classes, properties, and events are not supported.
  • Script modules don't have a size restriction; it is not necessary to use the #UNSUPPORTED UNLIMITED statement in your script module code.

Related topics


Click to return to: Documentation | Designing Dashboards | Scripting in Dundas Dashboard

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.