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.

services - Global object

Hide navigation
RSS
Modified on Wed, 12 Mar 2014 11:38 AM Categorized as Library Reference, Scripting, Viewer


The services global object gives you access to application-style services.

Properties

ImageImageProperty Name [Script Name]TypeDescription
CurrentDashboard [CurrentDashboard]DashboardContentGets the current dashboard.
CurrentDashboardTemplateChild [CurrentDashboardTemplateChild]DashboardContentGets the current dashboard template child. This will be the content dashboard if the current dashboard is a template and has a content dashboard. It will be null otherwise.
CurrentDashboardTemplateParent [CurrentDashboardTemplateParent]DashboardContentGets the current dashboard template parent. This will be the dashboard template if the dashboard has one, or null.
CurrentNavigationFolderId [CurrentNavigationFolderId]GuidGets or sets the ID of the currently selected folder in the navigation pane.
CurrentSession [CurrentSession]Nullable<Session>Gets the current session.

Tip: Make sure CurrentSession isn't null before using it.
Globals [Globals]Dictionary<string,object>Gets the globals. This is the same as a property bag in the session, for storing variables for the script across dashboards (within the same browser session). See this article for a practical example: Save and Restore Grouping State in a Data Grid.
Tip: watch the how to video: Global Variable
IsHtmlMode [IsHtmlMode]boolGets a value indicating whether dashboards are being viewed using the HTML Viewer or the Silverlight Viewer.
IsPreviewMode [IsPreviewMode]boolGets a value indicating whether the environment is in preview mode.
NamedTokenHelper [NamedTokenHelper]NamedTokenHelperGets the named token helper.
ParentDashboard [ParentDashboard]DashboardContentGets the parent dashboard. This is used when a dashboard is embedded in another via the DashBlock viewer.
ScreenHeight [ScreenHeight]doubleThe height of the screen.

Note: This property is not supported for HTML viewing.
ScreenWidth [ScreenWidth]doubleThe width of the screen.

Note: This property is not supported for HTML viewing.
ServerUri [ServerUri]stringGets the server URI in a convenient form for building links (e.g. for a request to http://www.dundas.com/DemoInstance/Viewer.aspx?Dd_ContentId=MyId it would return http://www.dundas.com/DemoInstance/)

Note: ScreenWidth and ScreenHeight represent the width/height of the application, not just the dashboard being viewed.

Methods

Tip: In Dundas Dashboard 5 or later, the Dashboard Designer Preview window uses our Enhanced Viewer, which means all of the services methods below also work when previewing a dashboard (unless the method indicates specifically otherwise).

AddDashBlock

Adds the specified dashblock to the current mashup. This will start a new mashup if a dashboard is currently being viewed. This will throw an exception if mashups are not enabled on this viewer.

  • void AddDashBlock( string dashBlockId )

Example:

// Add a dashblock to the current viewer mashup (this only works if you know the user
// is looking at a mashup).
services.AddDashBlock("9d688311-572c-4a8c-abf7-4d8980d68cd1");

ClearClientDataCache

Clears all items, or the specified item, from the client data cache.

  • void ClearClientDataCache()
  • void ClearClientDataCache( Guid itemId )

Where:

  • itemId - The ID of a KPI/dataset or virtual cube corresponding to an item to be cleared from the client data cache.

CloseAllDashboardDialogs

Closes all existing dashboard dialogs.

  • void CloseAllDashboardDialogs()

Example:

services.CloseAllDashboardDialogs();

CloseDashboardDialog

Closes the specified dashboard dialog.

  • void CloseDashboardDialog( string id )

Where:

  • id - The ID of a dashboard dialog that was specified when constructing a DialogDisplayOptions instance to be passed into the ShowDashboardDialog method.

Example:

services.CloseDashboardDialog("dashdlg1");

CopyToClipboard

Copies the specified text to the clipboard. This method must be invoked from a user-initiated interaction (e.g. Click interaction).

  • void CopyToClipboard( string text )

Note: This method is not supported for HTML viewing.

DisableDataLoading

Disables data loading in the dashboard and each of its data visualization controls.

  • void DisableDataLoading()

EnableDataLoading

Enables data loading in the dashboard and each of its data visualization controls.

  • void EnableDataLoading()

EnterAnnotateMode

Enters the annotate mode:

  • void EnterAnnotateMode()

Enters the annotate mode and pre-populates the default selection:


Where:

  • dashboard - The dashboard.
  • selectedDataDescriptor - The selected data descriptor.
  • selectedDataPoints - The selected data points.
  • columnId - The column id if the annotation only applies to a specific column in the data. Set to Guid.Empty if it is not specified.

Example:

// Enter annotation mode and pre-select the first data-point on BarChart1 as
// the selected item to annotate.
Collection<DataPoint> dataPoints = new Collection<DataPoint>();
dataPoints.Add(BarChart1.DataDescriptors[0].DataResult.DataPoints[0]);
services.EnterAnnotateMode(services.CurrentDashboard, BarChart1.DataDescriptors[0], dataPoints, Guid.Empty);

EvalJavaScript

Evaluates the specified JavaScript code. When using the Silverlight viewer, the result of the evaluated code is returned. When using the HTML viewer, the result is always null.

  • object EvalJavaScript( string scriptText )

Example:

bool result = services.EvalJavaScript("confirm('hello?');");
#TRACE result;

Note: This method is not supported for Silverlight out-of-browser mode.

ExitAnnotateMode

Exits the annotate mode.

  • void ExitAnnotateMode()

GetAllOpenDashboardDialogs

Gets all of the open dashboard dialogs.


GetCalculatedControlPosition

Gets the X and Y position of the given control on the dashboard, taking re-sizing into account (e.g. using Resize mode with guidelines). If the control isn't pinned the return value should match the control's normal Top and Left properties.


Where:

  • control - The control to find the position of.
  • dashboard - The dashboard this control is in.

Example:

Point point = services.GetCalculatedControlPosition(Rectangle1, services.CurrentDashboard);

Note: This method is available in Dundas Dashboard 5.0.2 or later.

GetCurrentParameters

Gets the parameters that are acting on the dashboard with their current values. For mashups, the parameters for each content item is applied by id.


Returns the parameters and their current values.

GetCurrentShownDashboards

Gets the current shown dashboards. This can be used to get the dashboards when the user is viewing a mashup.

Collection<DashboardContent> GetCurrentShownDashboards()

Returns the collection of the dashboards, or an empty collection.

GetDashboardShortLinkId

Gets the id of a short link to a dashboard. This is useful for HTML viewing where query string limits can be exceeded by passing too many parameter values.


Where:

  • dashboardId - The dashboard ID.
  • parameters - The parameters.

Example:

if (services.IsHtmlMode)
{
    Guid guid = services.GetDashboardShortLinkId("10404473-7b0f-4400-93c8-0c72fa8acf01", params);
    DialogDisplayOptions dialogOptions = new DialogDisplayOptions();
    dialogOptions.Width = 1000;
    dialogOptions.Height = 550;
    services.ShowDashboardDialogShortLink(guid, dialogOptions);
}

GetDialogDisplayOptions

Gets the dialog display options from the dashboard dialog Id given.


Where:

  • id - The ID of a dashboard dialog that was specified when constructing a DialogDisplayOptions instance to be passed into the ShowDashboardDialog method.

Returns the DialogDisplayOptions corresponding to the referenced Id, or null.

GetLinkUriString

Gets the link URI.


Returns the link URI or null. The baseUri value can be null, in which case it will be determined automatically for the link URI.

GetRelatedParametersFromGrainParameter

Gets a collection of parameters which act on the same dimension as the provided grain parameter.

This method should be used when modifying the grain level of data and filtering it at the same time. It will return all of the other parameters that are acting on the dimension that the grain parameter acts on so they may be updated.


Where:

  • grainParameter - The grain parameter.

Returns a collection of parameters related to the given grain parameter. This list may be empty.

Note: This method is available in Dundas Dashboard 5.0.2 or later.

HtmlDecode

Decodes an HTML-encoded string.

  • string HtmlDecode( string html )

HtmlEncode

Encodes an HTML-encoded string.

  • string HtmlEncode( string html )

LogoutCurrentUser

Logs the current user out of the system at viewing-time. When previewing a dashboard, this method does nothing.

  • void LogoutCurrentUser()

NavigateToDashboard

Navigates from the currently displayed dashboard to the specified dashboard.


The NavigateToDashboard method navigates from the currently displayed dashboard to the dashboard specified by dashboardId (a dashboard's GUID). The parameters in the specified ParameterInfoCollection are passed as parameters to the new dashboard.

Set the isBrowserPopup flag to True if you want to navigate to the dashboard in a new browser window.

// Navigate to a new dashboard, with parameters.
ParameterInfoCollection params = new ParameterInfoCollection();
ParameterInfo param;
int newAxisLevel = e.AxisLevel + 1;
param = new ParameterInfo();
param.ParameterName = "Parameter1";
param.ValueLevelAxis = newAxisLevel;
params.Add(param);

services.NavigateToDashboard("3e6d5c6b-4a9b-4389-a01f-84e69d2b0e7d", params);

NavigateToDashboardShortLink

Navigates to a dashboard specified by a short link.

  • void NavigateToDashboardShortLink( Guid shortLinkId )

Where:

  • shortLinkId - The short link id.

NavigateToMashup

Navigates to the specified mashup. The new mashup replaces what was previously displayed in the viewer.

  • void NavigateToMashup( Guid mashupId )

Where:

  • mashupId - The mashup id.

NavigateToUrl

Navigates from the currently displayed dashboard to the specified URL.

  • void NavigateToUrl( string url )
  • void NavigateToUrl( string url, string target )
  • void NavigateToUrl( string url, string target, string features )

The NavigateToUrl method navigates from the currently displayed dashboard to the URL specified by url. target is the name of the window or tab that url should be opened in. features is a comma-delimited list of browser-specific features.

// Navigate to a new page.
services.NavigateToUrl( "http://support.dundas.com/" );

Note: This will only work when Dundas Dashboard is running in a web browser.

RemoveDashBlock

Removes the DashBlock from the mashup. This will throw an exception if mashups are not enabled on this viewer.


Example:

Collection<DashboardContent> allDashblocks = services.GetCurrentShownDashboards();
services.RemoveDashBlock(allDashblocks[0]);

RunDashboardInteraction

Runs the specified dashboard interaction.


Where:

  • interactionName - Name of the interaction.
  • sender - The sender.
  • eventArgs - The DashboardEventArgs instance containing the event data.
  • dashboard - The dashboard.

SetCurrentParameters

Sets the parameters to values specified on the corresponding content item (for mash-ups), or the first item. The parameters are set in the order they are in the collection, so in the case where more than one parameter is acting on the same KPI filter, order is important. As well, for drill-down (where a grain parameter also filters), it will take precedence over other filter parameters that are set with default values (but not those which are specified in the parameters collection). If the enhanced viewer is showing a mashup, then the ContentItemId on ParameterInfo will apply. If not, then the first content item will just be used.


SetupNotification

Shows the Notifications wizard.


Where:

  • dashboard - The dashboard that it should use by default.
  • defaultSelectedControl - The control selected by default.
  • defaultSelectedDataDescriptor - The default selected descriptor.
  • defaultSelectedColumns - The name of the column selected by default.
  • displayOptions - The display options for this dialog.

Example:

// Open the 'Setup Notification' wizard pre-selected to 'BarChart2'.
services.SetupNotification(services.CurrentDashboard, BarChart2, null, null);

// Open the 'Setup Notification' wizard pre-selected to 'DataGrid1' and the // first descriptor, with the metric on it 'OrderQty'. services.SetupNotification(services.CurrentDashboard, DataGrid1, DataGrid1.DataDescriptors[0], "OrderQty");

Note: This method is not supported for HTML viewing.

SetupScheduledReport

Shows the Scheduled Report Definition wizard.

  • void SetupScheduledReport()
  • void SetupScheduledReport( DashboardContent dashboard )

Where:

  • dashboard - The dashboard that it should use by default.

Note: This method is available in Dundas Dashboard 5.0.1 or later for the Silverlight Viewer. It is not available for HTML viewing.

ShowAnnotationGroupFilterDialog

Shows the annotation group filter dialog.

  • void ShowAnnotationGroupFilterDialog()
  • void ShowAnnotationGroupFilterDialog( WizardDisplayOptions displayOptions )

Where:

  • displayOptions - The display options for this dialog.

ShowBookmarkDialog

Displays the bookmark dialog so the user can bookmark the currently viewed item.


Where:

  • displayOptions - The display options for this dialog.

ShowContentManager

Shows the content manager.


Where:

  • displayOptions - The display options for this dialog.

ShowDashboardDialog

Shows a dashboard dialog, which is a non-modal pop-up that the user can interact with and move around.


Where:

  • dashboardId - The dashboard id.
  • e - The DashboardMouseEventArgs instance containing the event data.
  • displayOptions - The display dialog options.
  • parameters - The parameters.

Example (button Click interaction):

// Center the dialog.
DialogDisplayOptions options = new DialogDisplayOptions("dashdlg1", true, null, double.NaN, double.NaN);
options.IsHeaderVisible = false;
services.ShowDashboardDialog("7bcebd59-d425-4f29-9ea4-73033d50d515", e, options);

ShowDashboardDialogShortLink

Shows a dashboard dialog, which is a non-modal pop-up that the user can interact with and move around.

  • void ShowDashboardDialogShortLink ( Guid shortLinkId )
  • void ShowDashboardDialogShortLink ( Guid shortLinkId, DialogDisplayOptions displayOptions )

Where:

  • shortLinkId - The short link id.
  • displayOptions - The display options used for this dialog.

ShowDashboardPopup

Show a dashboard popup (often used for previews).


Where:

  • dashboardId - The dashboard ID.
  • element - The element.
  • e - The DashboardMouseEventArgs instance containing the event data.
  • callbackScript - The callback script.
  • callbackEventArgs - The DashboardMouseEventArgs instance containing the callback event data.
  • displayOptions - The popup display options.
  • parameters - The parameters.

Tip: You can use specific elements, such as chart series or data points, as the element. By default, the hover-over script uses the entire control.

// Navigate to a new dashboard, with parameters.
ParameterInfoCollection params = new ParameterInfoCollection();
ParameterInfo param;
int newAxisLevel = e.AxisLevel + 1;
param = new ParameterInfo();
param.ParameterName = "Parameter1";
param.ValueLevelAxis = newAxisLevel;
params.Add(param);

services.ShowDashboardPopup("3e6d5c6b-4a9b-4389-a01f-84e69d2b0e7d", this, e, params);

ShowExportWizard

Shows the export wizard where the user has to select the dashblock (if there is more than one).


Where:

  • dashboard - The dashboard to export based on. This is a good short cut if the script is run on a dashblock, otherwise the user still has to select which dashblock to use.
  • defaultSelectedDashboardControls - The dashboard controls selected by default.
  • defaultSelectedExportPluginName - The name of the export plugin selected by default.
  • displayOptions - The display options for this dialog.

Example:

// Show the export wizard with 'BarChart1' selected and the 'CSV Data Export'
// export plug-in selected by default.
Collection<DashboardControl> controls = new Collection<DashboardControl>();
controls.Add(BarChart1);
services.ShowExportWizard(services.CurrentDashboard, controls, "CSV Data Export");

ShowMessage

Displays a modal dialog box with a specified message and optional caption.

  • ShowMessage ( string message )
  • ShowMessage ( string message, string caption )

A message without a caption.

A message without a caption.


The ShowMessage() method pops up a simple dialog box with an OK button. The message disappears when the user clicks OK.

ShowMessage() returns immediately; several ShowMessage() calls will display each new message on top of the previous one. For example:

// Message with default caption:
services.ShowMessage( "You clicked on the other label.");

// Message with custom caption: services.ShowMessage("No, click the other one!", "Not this one.");

Will display the message with a custom caption on top of the one with the default caption, without stopping your script.

ShowPerformanceDialog

Shows the performance dialog.


Where:

  • displayOptions - The display options for this dialog.

ShowPrintDialog

Shows the print dialog where the user has to select the dashblock (if there is more than one) and then the option to print.


Where:

  • dashboard - The dashboard to show the print dialog for.
  • elementToPrint - The element to print.

Example:

// Show the print dialog for BarChart1 (this won't print the whole dashboard, just BarChart1).
services.ShowPrintDialog(services.CurrentDashboard, BarChart1);

ShowSaveMashupDialog

Shows the save mashup dialog.


Where:

  • displayOptions - The display options for this dialog.

ShowShareDialog

Shows the share dialog so that the user can share the currently viewed item.


Where:

  • displayOptions - The display options for this dialog.

Example:

// Show the share dialog.
services.ShowShareDialog();

StartTutorial

Starts the tutorial given the name of the tutorial file.

  • void StartTutorial( string tutorialFileName )

UpdateDashboardDialogDisplayOptions

Updates the dashboard dialog display options.


UrlDecode

Decodes a URL-encoded string.

  • string UrlDecode( string url )

UrlEncode

URL-encodes a string.

  • string UrlEncode( string url )

Notes

Obsolete methods

The following methods were made obsolete. They will still work, but will not appear in the script editor's type/object explorers.

Obsolete starting with Dundas Dashboard v4.0.5:

  • string GetLinkUri(string baseUri, string contentId, ViewerContentItemType contentType, ParameterInfoCollection parameters)

Obsolete starting with Dundas Dashboard v4:

  • void ShowDashboardDialog(string dashboardId, DashboardMouseEventArgs e, double width, double height)
  • void ShowDashboardDialog(string dashboardId, DashboardMouseEventArgs e, ParameterInfoCollection parameters, bool isDialogCentered, Nullable<Point> initialDialogPosition)
  • void ShowDashboardDialog(string dashboardId, DashboardMouseEventArgs e, ParameterInfoCollection parameters, double width, double height)
  • void ShowDashboardDialog(string dashboardId, DashboardMouseEventArgs e, ParameterInfoCollection parameters, double width, double height, bool isDialogCentered, Nullable<Point> initialDialogPosition)
  • void ShowDashboardPopup(string dashboardId, DashboardElement element, DashboardMouseEventArgs e, double width, double height)
  • void ShowDashboardPopup(string dashboardId, DashboardElement element, DashboardMouseEventArgs e, double width, double height, string callbackScript, DashboardEventArgs callbackEventArgs)
  • void ShowDashboardPopup(string dashboardId, DashboardElement element, DashboardMouseEventArgs e, ParameterInfoCollection parameters, double width, double height)
  • void ShowDashboardPopup(string dashboardId, DashboardElement element, DashboardMouseEventArgs e, ParameterInfoCollection parameters, double width, double height, string callbackScript, DashboardEventArgs callbackEventArgs)

Related topics


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

Copyright © 2009-2014 Dundas Data Visualization, Inc.