416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
Dashboard v5.0

This site makes extensive use of JavaScript.

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

Interaction and Scripting

Hide navigation
RSS
Modified on Tue, 29 Apr 2014 06:25 PM Categorized as Design, Scripting
Click to return to: Documentation | Designing Dashboards | Scripting in Dundas Dashboard


Scripting

Dundas Dashboard lets you run small scripts to provide customized behavior based on the user's interactions with elements in your dashboard. The scripting language is closest to C# or Java but includes some features similar to those of JavaScript, and it will look familiar to anyone who has used JavaScript, C, Perl or other modern script/programming languages. There are some possible differences and limitations to be aware of.

Scripts are attached to interactions, which can be triggered by events such as a user clicking or holding the mouse pointer over an element (hovering), or by events such as the dashboard loading.

Hello world!

Let's begin with a basic example:

  1. Create a new dashboard.
  2. Drag a Label control from the toolbox (under General Controls) to the dashboard canvas.
  3. Go to the Properties grid for the label and locate its Click Interactions property.
  4. Click on the property value, then choose Add from the resulting menu.
    Label interactions menu.
  5. A new Click interaction script is added to the label and the Script Editor is displayed, overlaying the Dashboard Designer screen.
    Script editor opens.
  6. In the Script Editor, type the following script:

    Label1.Text = "Hello world!";

  7. Click the Build button in the toolbar to make sure you haven't made any mistakes.
    Build button.
  8. Click the Apply button (green checkmark) in the toolbar to apply the changes to your script.
  9. Click the Close button in the top-right corner to exit the Script Editor.
  10. Save, then preview your dashboard.
  11. In the Preview window, click the label to see its text change from Label to Hello world!.

Next, try these additional steps:

  1. Go to the Properties grid for the label and locate its Click Interactions property again.
  2. Click the property value, then choose Click(1) from the resulting menu. The existing Click interaction script is displayed in the Script Editor for editing.
    Edit label Click interaction.
  3. In the Script Editor, change the script to:

    var tmp = Label1.ToolTip;
    Label1.ToolTip = Label1.Text;
    Label1.Text = tmp;

  4. In the Properties grid for the label, set the Tooltip property to Hello world!.
  5. Save, then preview your dashboard again.

Now when you click the label in the Preview window, it swaps the displayed text and the tooltip text.

What just happened?

You've just quickly and easily created two different custom behaviors in a dashboard. This will be nothing new if you have used scripting or programming languages before, but DundasScript is designed to ease in users who are less familiar.

Why is this interesting?

  • The dashboard's controls are automatically available to the script to access and set properties.
  • Script allows you to make your dashboard interactive, set properties based on some custom logic, and do more than the script that is generated by the wizards.

The DundasScript engine

The DundasScript engine lets you use a scripting language which can be thought of as a subset of the C# programming language, but it shares most syntax with other modern languages including Java, JavaScript and C, and supports dynamic types like most scripting languages. Dashboard scripts are triggered by a user interaction and each script runs as a method body; there's no need to define methods or functions, classes, structures, etc. yourself.

Each control in the dashboard is available to script, as well as a number of global objects, often depending on the kind of interaction. You can also create new objects using the new keyword for any classes that have been registered with the DundasScript engine. Only registered classes can be used, providing a sandbox that makes it almost impossible for a script to make your dashboard misbehave or crash.

Syntax

The DundasScript engine supports the following keywords:

break, catch, continue, do, else, false, finally, for, foreach, if, in, is, new, null, return, true, try, var, while

and the following built-in data types:

bool, byte, char, decimal, double, float, int, long, object, string

The DundasScript engine also supports the following operators, with the standard order of operations:

+, -, * , / , (, ), !, %, =, ==, != <, >, <=, >=, +=, -=, *=, /=, ++, --

In addition, the DundasScript engine supports:

  • Indexers, to access items in a collection, list or array.
  • Exceptions, to handle errors when script does something unsupported.

string[] parts;

try { parts = someVariable.Split(); } catch( /* NullReferenceException */ ) { parts = new string[]; }

  • Generics, if a generic type is registered with the engine.

List<int> myIntList = new List<int>();
myIntList.Sort();

  • Access to all of an object's public methods, properties and fields.
  • Single dimensional arrays (note that inline array initialization isn't supported).

int[] bunchOfValues = new int[7];
bunchOfValues[0] = 1;
bunchOfValues[1] = 1;
bunchOfValues[2] = 2;
bunchOfValues[3] = 3;
bunchOfValues[4] = 5;
bunchOfValues[5] = 8;
bunchOfValues[6] = 13;

  • Both styles of comments are supported:

// Describe your code.
/* Comments are useful. */

Tip: Comments that span a whole line aren't counted against your script length. Comments inline with code are counted.

Numeric values

Numeric values default to int, or integral numbers. Include the decimal point, or use f or d to explicitly declare numeric literals as float or double values:

  • 12 — integer
  • 12f — floating-point (12.0)
  • 12d — double-precision (12.0)

Note: The division of two integers always results in an integer value (as in most programming languages). For example, the resulting value of r in the script below is 2.0.

double r = 12 / 5;

Use the following script instead to get the desired result, r = 2.4.

double r = 12.0 / 5;

Or:

double r = 12d / 5;

The #TRACE directive

The #TRACE directive lets you add debugging statements to your scripts, to print the values or variables or properties to the script console when previewing a dashboard.

int x = 5;
#TRACE "Current value of x: ", x;

Will print “Current value of x: 5” to the script console trace pane.

#TRACE "Number of points: ", LineChart1.Series[0].Points.Count;

Will print “Number of points: 441” to the script console trace pane for a line chart named LineChart1 with 441 points in its first series.

Tip: In Dundas Dashboard 5 or later, TRACE statements can be issued from scripts within a dashblock that is hosted inside a dashblock viewer.

Short-circuit evaluation

DundasScript supports short-circuit evaluation of Boolean expressions, the same as most languages. This applies to both && and || operators.

For example, you can safely write an if statement as follows:

if ( e.VisualElementArgs != null && e.VisualElementArgs.Visibility == Visibility.Visible )
{
    ...
}

In the above example, if e.VisualElementArgs is null, the second expression is never evaluated, and no error occurs.

Features and limitations

The DundasScript engine implements a custom interpreter written specifically for Dundas Dashboard.

Although close in syntax with C#, it is a dynamically-typed script language. This means you don't need to know the type of an object or cast it to access one of its properties. For example, if you know that your script only runs against a chart's click interaction, you can assume that the VisualElementArgs property of the event arguments is a DashboardDataPoint and access its properties:

if ( e.VisualElementArgs != null )
{
    e.VisualElementArgs.LabelText = "Clicked";
}

A chart's Y axes usually have a scale with the type DashboardNumericScale, and if you did not change this you can set its scale Maximum property directly even though it is specific to numeric scales:

BarChart1.YAxes[0].Scale.Maximum = 50;

You can use the var keyword in place of any type name to simplify script:

foreach (var series in LineChart1.Series)
{
    series.ChartType = DashboardSeriesChartType.Bar;
}

Other features:
  • You can call static methods on an instance variable.
  • There is no variable scoping. This means that you can redefine a variable, but note that if you do the previous value will be overwritten/lost. For example:

// Create a new string:
string foo = new string( "Hello world" );

...

if( someCondition ) { // From now on, foo is an int, not a string! int foo = 10; ... }

DundasScript has a few limitations that you may need to be aware of. The following are not supported:

  • Multidimensional arrays
  • Indexers with multiple parameters
  • throw statement
  • delegates
  • Multiple variable declarations per line
  • Creating user-defined events
  • Nullable types and the ?? operator
  • Numeric hex literals such as: 0x00
  • switch/case/default statements
  • ref and out parameters
  • Lambda expressions
  • Operators below are not supported:

&, |, ^, &=, |=, ^=, >>, <<, >>=, <<=, typeof, sizeof
~x, ++x, --x

  • The conditional operator (x ? y : z) is not supported
  • Array creation using initializer as shown below is not supported:

int[] a = new int[] { 1, 2, 3 };

Multi-line strings

The value of a string variable can span multiple lines using the ‘@’ character as shown in this example:

string s = @"Dundas Data
Visualization, Inc.";
services.ShowMessage(s);

A multi-line string variable.

A multi-line string variable.


Script size

Scripts are limited to 2048 characters. Scripts larger than this will not compile in the script editor unless you include the #UNSUPPORTED UNLIMITED statement at the start of your script:

#UNSUPPORTED UNLIMITED
// Really huge script with more than 2048 characters
// goes here.

Note that this is unsupported by Dundas; if you experience performance issues or other problems related to huge scripts, we might not be able to help you.

Tip: Comments starting with // are not counted against the script size limit.

Available classes

The classes described in this section are available in the DundasScript engine.

Standard .NET classes

The following classes are exposed in the DundasScript engine. They access the .NET classes directly and have not been reimplemented in the engine. All public methods, properties and fields will work as documented at the MSDN site:

  • bool — Boolean value (true or false)
  • Boolean — Same as bool.
  • Byte — An 8-bit unsigned integer.
  • char — A single UTF-8 character.
  • Collection<T> — A generic collection.
  • Color — Describes a color in terms of alpha, red, green, and blue channels.
  • Colors — A set of predefined colors such as CornFlowerBlue.
  • Convert — Converts a base data type to another base data type.
  • DateTime — A date and time value.
  • DateTimeKind — Specifies whether a DateTime object represents a local, UTC or unknown time.
  • DayOfWeek — Specifies the day of the week.
  • Decimal — A fixed-precision decimal value.
  • Dictionary<TKey,TValue> — A collection of keys and values.
  • double — A double precision floating-point value.
  • Enum — The base class for enumerations.
  • Exception — Errors that occur during application execution.
  • float — A single precision floating-point value (faster but less accurate).
  • Guid — Represents a globally unique identifier.
  • IConvertible — Defines methods that convert the value of the implementing reference or value type to a common language runtime type that has an equivalent value.
  • Int16 — A 16-bit integer value.
  • int — A 32-bit integer value.
  • List<T> — A list of objects that can be accessed by index.
  • long — A 64-bit integer value.
  • Math — Provides constants and static methods for common mathematical functions.
  • Object — The base class of all .NET class hierarchies.
  • Point — an x- and y-coordinate pair in two-dimensional space.
  • Random — A pseudo-random number generator.
  • string — A character string.
  • String — Same as string.
  • TimeSpan — Represents a time interval.

Dundas Dashboard classes

Most Dundas Dashboard classes either define general controls or data controls or are used by one of their properties or interactions. Browse or search for a control to explore the classes used, or search for a class name to find its documentation directly.

These are just some of the classes available in Dundas Dashboard; follow the link for class library documentation:


Global objects

These objects always exist, and can be accessed by any interaction script.

  • services — Application-style services, such as pop-up message boxes.

Examples

Custom drill-down

This code sample performs a drill-down with filtering to change the grain when clicked:

if (e.DataPoint != null)
{
    ParameterInfoCollection params = new ParameterInfoCollection();
    ParameterInfo param = new ParameterInfo();
    int newAxisLevel = e.AxisLevel + 1;
    param.ParameterName = "DrillDownParameter";
    param.ValueLevelAxis = newAxisLevel;

Collection<int> dimKeyIndexes = e.KpiDescriptor.DataResult.GetDimensionKeyIndexes(e.KpiDescriptor.Dimension); if (dimKeyIndexes.Count > 0) { param.ValueLevelFilter = e.AxisLevel; foreach (int keyIndex in dimKeyIndexes) { param.ValueStartCollection.Add(e.DataPoint.FieldValues[keyIndex]); param.ValueEndCollection.Add(e.DataPoint.FieldValues[keyIndex]); } }

params.Add(param);

services.NavigateToDashboard("8c165033-a278-4039-9672-7e7ddebc47ad", params); }

Note that:

  • If the user drills-down past the "end" of the hierarchy, the last level will be redisplayed
  • If the user clicks on the chart, but not on a data-point, nothing will happen.

Click handling in the legend

To handle clicks in a legend:

  1. Add a chart with one or more series to a dashboard.
  2. Add a Legend and connect it to the chart.
  3. Set the legend's Item Checkbox Visible property (under the Appearance category) to True.

A script is generated for you automatically. To change it, click the right column of the legend's Item Check Changed Interactions property, then choose ItemCheckChanged(1) from the menu that appears. The existing script will look like:

if (e.ParentControlElements.Count > 0)
{
  for(int i=0;i<e.ParentControlElements.Count;i++)
  {
    if (e.IsChecked)
    {
      e.ParentControlElements[i].Visibility = Visibility.Visible;
    }
    else
    {
      e.ParentControlElements[i].Visibility = Visibility.Collapsed;
    }
  }
}

You can now save and preview the dashboard. Click the checkbox in the legend to toggle the display of the chart series.

Customizing properties

Here’s an example of how to make a drop-down menu with two color choices, and have it change the color of a chart’s first series:

  1. Add a chart to your dashboard.
  2. Add a KPI to the chart so that it has at least one series.
  3. Add a DropDownList general control to the dashboard.
  4. In the Properties grid for the dropdown list, open the Items property. Add Red and Blue items.
  5. Add a script like this to the dropdown list's Selection Changed Interactions property.

if (e.NewValue == "Red")
{
    BarChart1.Series[0].Fill = new DashboardSolidColorBrush(Colors.Red);
}
else
{
    BarChart1.Series[0].Fill = new DashboardSolidColorBrush(Colors.Blue);
}

You could put this script in your dashboard's click event to set its foreground color to a solid blue:

sender.Foreground = new DashboardSolidColorBrush(Colors.Blue);

Handling script errors

A script error which occurs while you are viewing or previewing a dashboard is displayed in an Error dialog:

Script error dialog.

Script error dialog.


  • Click Details to see the detailed error message in a popup window. You will have the option of copying the message text to your Windows clipboard.

  • Click Close to close the script error dialog.

  • If you have multiple scripts or a complex script running, you may encounter a case where more than one script error dialog is displayed at the same time. Click Abort to close all script error dialogs and disable their scripts. If you are in preview mode note that this will also close the Preview window. Once a script is disabled, it won't run again until the next time you preview or view the dashboard.

  • Select the “Ignore this error next time” option, then click Close to avoid showing this same error if it occurs again.

Changing brush properties

When you change the properties of a brush object via scripting, note that the changes won't take effect until the brush is set back to its parent control. For example, suppose you have a Rectangle control on the canvas. Use the following script to modify the rectangle's Fill property as follows:

DashboardSolidColorBrush brush = (DashboardSolidColorBrush)Rectangle1.Fill;
brush.Opacity = 0.1;
Rectangle1.Fill = brush;

Changing properties of type Thickness

If you have a dashboard control with a Thickness property (such as the Character Padding property of a display indicator), note that you cannot modify the thickness fields directly inline. For example, the following code will not work.

DisplayIndicator1.CharacterPadding.Bottom = 10;
DisplayIndicator1.CharacterPadding.Left = 10;
DisplayIndicator1.CharacterPadding.Right = 10;
DisplayIndicator1.CharacterPadding.Top = 10;

Use the following script instead which modifies the thickness object and then assigns it back to its parent control.

Thickness t = DisplayIndicator1.CharacterPadding;
t.Bottom = 10;
t.Left = 10;
t.Right = 10;
t.Top = 10;
DisplayIndicator1.CharacterPadding = t;

Typecasting

The code below shows how to cast an object to a more specific type and use its properties in the same line:

double val = ((DundasDataPoint)point).XValue;

Using params in method calls

The code below shows how to pass a params parameter to a method such as string.Split:

string s = "123a456b789";
char[] c = new char[2];
c[0] = 'a';
c[1] = 'b';
string[] tokens = s.Split(c);

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.