Dashboard API
- Variable functions (DDVariables)
- Data filtering and navigation functions
- Data query functions
- Dashboard functions
- Event handling
- Miscellaneous functions
There are two ways to add customised behaviour to dashboards. The first is to use the global JavaScript editor available in the dashboard editor. The second is the Text Editor portlet. This element allows you to add a block of text (and/or HTML) to a dashboard page. The possibilities are expanded thanks to an application programming interface (API) that allows you to add JavaScript calls to dashboard functions to hyperlinks within a text editor.
Using these functions, you can trigger a page change, apply a filter to a given dimension, change a DigDash variable, and so on.
Each function is called on an implicit ddCtrl object defined by the dashboard engine. Here is the list of functions:
Variable functions (DDVariables)
void ddCtrl. changeVariable(name, value)
Description: Changes the value of the variable <name>.
Example:
<a href="javascript:ddCtrl.changeVariable('ratioEuro', 1.30)">EuroDollar: 1.30</a>
(Number) ddCtrl.getDDVar(name)
Description: Returns the value of the variable <name>.
Example:
<a href="javascript:ddCtrl.changeVariable('ratioEuro', ddCtrl.getDDVar('ratioEuro') + 0.1)">Increase EuroDollar</a>
Data filtering and navigation functions
FilterOperand (dimension, member, hierarchy, level, formattedMember, bAddFilter, bExcludeFilter)
Description: Object used to specify the filter to be applied.
Example:
<a href="javascript:ddCtrl.filter('Geo Dim', new FilterOperand('Geo Dim', 'France', 'Geo', 'Country', false, false))">France filter</a>
FilterOperandContinuous (dimension, min, max, bExcludeFilter)
Description: Object used to specify the interval filter to be applied to a continuous dimension.
Example:
<a href="javascript:ddCtrl.filter('Country', new FilterOperandContinuous('Date', new Date(2018, 0, 1).getTime()/1000, new Date(2019, 0, 1).getTime()/1000, false))">Filter: Year 2018</a>
FilterOperandMatch (dimension, hierarchy, level, [values], [operators], mode, ExcludeFilter)
Description: Object used to specify a ‘Rule’ type filter to be applied to a continuous dimension.
Example:
<a href="javascript:ddCtrl.filter('Geo Dim', new FilterOperandMatch('Geo Dim', 'Geographical', 'Country', ['A'], [13], 0, false))">Filter: Countries starting with A</a>
void ddCtrl.filter (dimension, member)
Description: filters by a dimension.
Example:
<a href="javascript:ddCtrl.filter('Pays', 'France')">Filter France</a>
void ddCtrl.filter (oFilterOperand)
Description: Filters on a dimension by specifying a hierarchy and a level.
Example:
<a href="javascript:ddCtrl.filter(new FilterOperand('Lieu', 'FR', 'Géographique', 'Pays'))">France Details</a>
void ddCtrl.filterOnChart (portlet, oFilterOperand, doNotRefresh)
Description: Filters a chart by a dimension by specifying a hierarchy and a level.
Example:
<a href="javascript:ddCtrl.filterOnChart('portletId1', new FilterOperand('Lieu', 'FR', 'Géographique', 'Pays'))">Details for France</a>
void ddCtrl.filterAndChangePage (page, dimension, member)
Description: filters by a dimension and changes the page.
Example:
<a href="javascript:ddCtrl.filterAndChangePage('Production.Details Country', 'Country', 'France')">France Details</a>
void ddCtrl.changePageAndFilter (page, dimension, member)
Description: changes the page and filters by a dimension.
Example:
<a href="javascript:ddCtrl.changePageAndFilter('Production.Details Country', 'Country', 'France')">France Details</a>
void ddCtrl.setFilterMinMax (dimension, min, max)
Description: Filters by a continuous dimension by specifying a minimum and maximum value. Note: A DigDash date is a timestamp in seconds.
Example:
<a href="javascript:ddCtrl.setFilterMinMax('Date', new Date(2014, 0, 1).getTime()/1000, new Date().getTime()/1000)">2014 to date</a>
(String Array) ddCtrl.getDimensionFilter (dimension [, bContinue])
Description: Returns the list of elements filtered by the dimension (continuous or discrete).
Example:
<a href="javascript:alert(ddCtrl.getDimensionFilter('Pays'))">Filters by Country</a>
void ddCtrl.isDimensionFiltered (dimension [, bContinue])
Description: Returns true if the dimension (continuous or discrete) is filtered. Returns false otherwise.
Example:
<a href="javascript:alert(ddCtrl.isDimensionFiltered('Pays'))">Is the country filtered?</a>
void ddCtrl.removeAllFilters ()
Description: Removes all filters from the dashboard.
Example:
<a href="javascript:ddCtrl.removeAllFilters()">Reset</a>
void ddCtrl.removeAllFiltersCurrentPage ()
Description: Removes the filters from the current page.
Example:
<a href="javascript:ddCtrl.removeAllFiltersCurrentPage()">Reset</a>
void ddCtrl.removeFilters (dimension [, bContinue])
Description: Removes the current filters on the dimension (continuous or discrete).
Example: <a href="javascript:ddCtrl.removeFilters('Pays')">All countries</a>
void ddCtrl.beginSelection ()
void ddCtrl.commitSelection ()
Description: Used in conjunction with the ddCtrl.filter function. Allows multiple filters on different dimensions to be combined without having to run each filter individually (optimisation).
Example:
<a href="javascript:ddCtrl.beginSelection(); ddCtrl.filter('Country', 'France'); ddCtrl.filter('Year', '2013'); ddCtrl.commitSelection()">France in 2013</a>
void ddCtrl.setDimensionNavigation (dimension, Flow, bNavigation)
Description: Changes the permission to navigate by a dimension for the specified flow.
Example:
<a href="javascript:ddCtrl.setDimensionNavigation('Region', 'chart1', true)">Enable navigation by Region</a>
(String array) ddCtrl.getCurrentDrill (portlet, dimension[, hierarchy])
Description: Returns the dimension, hierarchy and current level of a chart as an array.
Example:
if (chart.title == 'Mon graphique') {
var curDrill = ddCtrl.getCurrentDrill(doc.frameId, 'Région', 'Géographique');
var dim = curDrill[0];
var hier = curDrill[1];
var lvl = curDrill[2];
alert("L'exploration est " + hier + " / " +lvl + " sur la dimension " + dim);
}
});
(BreadPath) ddCtrl.getBreadPath (portlet, dimension)
Description: Returns the current navigation path (BreadPath) for a dimension in a chart. This object can be used by `drillTo` (see below).
Example:
<a href="javascript:ddCtrl.drillTo('portletId2', 'Lieu', ddCtrl.getBreadPath('portletId1', 'Location'))">Current Location Details (Chart 2)</a>
void ddCtrl.drillTo (portletId, dimension, oBreadPath)
Description: Navigates within a chart along a hierarchy of the selected dimension, using a navigation path defined by the BreadPath object.
Example:
See example above (getBreadPath)
void ddCtrl.drillDown (portletId, dimension, hierarchy, level, member, formattedMember)
Description: Navigates down a hierarchy of the selected dimension to the specified member at the lower level.
Example:
<a href="javascript:ddCtrl.drillTo('portletId', 'Location', 'Geographic', 'FR', 'France')">France Details</a>0
void ddCtrl.resetDrill (portlet, dimension, [hierarchy])
Description: Resets navigation on the dimension hierarchy.
Example:
<a href="javascript:ddCtrl.resetDrill('portletId', 'Location')">Back to the world map</a>
void ddCtrl.selectMeasuresOnChart(portlet, [measures])
Description: Displays the specified measures on the chart; the other measures on the chart will be hidden.
Example:
<a href="javascript:selectMeasuresOnChart('portletId2', ['Turnover', 'Margins'])">Display Turnover and Margins</a>
(Number | String) ddCtrl.getDataModelDate (dmId, bFormat)
Description: Returns the synchronisation date of a data cube. The parameters are the data model ID and a Boolean value to format the date (true) or return the corresponding timestamp (false).
Example:
<a href="javascript:alert(ddCtrl.getDataModelDate('a1234567890..', true))">Display the data date</a>
(Number | String) ddCtrl.getDataModelLinesCount (dmId)
Description: Returns the number of rows in a data cube. The parameter is the data model identifier.
Example:
<a href="javascript:alert(ddCtrl.getDataModelLinesCount('a1234567890..'))">Display the number of rows in the data</a>
(Number | String) ddCtrl.getFlowDate (Flow, bFormat)
Description: Returns the synchronisation date of a flow. The parameters are the flow ID and a Boolean value to format the date (true) or return the corresponding timestamp (false).
Example:
<A href="javascript:alert(ddCtrl.getFlowDate('fluxId', true))">Display the Flow date</A>
Data query functions
(Number | String) ddCtrl.getResultCubeValue (Flow, measure, lMembers, bFormatted)
Description: Returns the value of the measure for the specified axis members from a visible chart. Returns the value as a number or as a formatted string.
Note: The list of axis members must specify one and only one member for each axis used in the chart, in the natural order of the chart’s axes. The measure parameter is the measure ID.
Example: To retrieve a value from a histogram defined as follows: Measure ‘Margin’ on the stack axis, dimension ‘Year’ on the column axis and ‘Country’ on the group axis:
<a href="javascript:alert(ddCtrl.getResultCubeValue('chart1', 'Margin', ['2023', 'France'], true))">Show the margin for France in 2023</a>
(Row table) ddCtrl.getResultCubeRowSet (Flow, oAxisMemberQuery [, bFormatted])
Description: Returns the flattened rows of the result cube for the specified axis members from a visible chart. Returns the result as an array of rows, each row being an array of cells. The cells consist of the chart’s dimensions/axes followed by the measure values.
Example: To retrieve the rows corresponding to the year 2024 and the person ‘John’ from a result cube of a chart named ‘chart1’:
<a href="javascript:alert(ddCtrl.getResultCubeRowSet('chart1', {'Year' : '2024', 'Person': 'John'})[0][2])">Show John’s first value in 2024</a>
(Number) ddCtrl.getResultCubeLinesCount (Flow)
Description: Returns the number of flattened rows in the result cube.
Example:
<a href="javascript:alert(ddCtrl.getResultCubeLinesCount('chart1')" >Number of rows</a>
ddCtrl.getLastDimensionDate('data model ID', 'Time dimension')
Description: Returns the maximum date of a time dimension as a timestamp.
Example:
<a href="javascript:alert(ddCtrl.getLastDimensionDate('a866caa04fabdd35687fa3bd3758d6a8', 'Date')" >Maximum date</a>
ddCtrl.getCubeValue ("data model ID", [filters], 'dimension or measure name', bUseContext)
Description: Retrieves the value of a measure or the member of a dimension in a data model with the filters applied (so that only one row of data is returned by the server).
The UseContext parameter, which is a Boolean, allows you to specify whether or not the dashboard’s filtering context should be taken into account when calculating the data.
Example: To retrieve the value of the ‘Communication Cost’ measure with the filtered elements ‘Mobile’ for Line Type and ‘Samsung Galaxy’ for Hardware, in the data model with the identifier " 0b2583609f86d37754ce2ada372f31ae", and taking into account the dashboard’s filter context:
<a href="javascript:alert(ddCtrl.getCubeValue("0b2583609f86d37754ce2ada372f31ae", [{"dim":"Line type", "member":"Mobile"}, {"dim":"Hardware", "member":"Samsung Galaxy"}], 'Communication cost', true)">Communication cost value</a>
ddCtrl.getFlowValue ("flow ID", [filters], 'dimension or measure name', bUseContext)
Description: Retrieves the value of a measure or the member of a dimension in a Flow with the filters applied (so that only one row of data is returned by the server).
The UseContext parameter, which is a Boolean, allows you to specify whether or not to take the dashboard’s filtering context into account when calculating the data.
Example: To retrieve the member of the ‘Line Type’ dimension with the filtered element “Samsung Galaxy” for Hardware, in the flow with the identifier “ b312f6be”, and without taking the dashboard’s filter context into account:
<a href="javascript:alert(ddCtrl.getFlowValue("b312f6be", [{"dim":"Hardware", "member":"Samsung Galaxy"}], 'Line Type', false)>Line Type member</a>
Dashboard functions
void ddCtrl.loadJS (urlJS)
Description: Loads a JavaScript file from a URL.
Example (in the JavaScript editor):
var hash = CryptoJS.MD5("Le message");
void ddCtrl.includeJS (JS_name)
Description: Loads a JavaScript file from the DigDash Enterprise configuration folder. The file must have been created beforehand using the JavaScript editor in the dashboard editor.
Example (in the JavaScript editor):
void ddCtrl.drawFlowInElement ('HTML element or widget ID', 'Flow ID');
Description: Displays a flow within an HTML element
Example (in the JavaScript editor):
<A href="javascript:ddCtrl.drawFlowInElement ('elementHTMLId', 'fluxId')">Display Flow</A>
💡The ID is that of the portlet. You can copy it from the Information tab in the element’s Settings panel.
For example: <A href="javascript:ddCtrl.drawFlowInElement ('Retail_Coûts_editor', '1898358537')">Display flow</A>
void ddCtrl.changePage (page)
void ddCtrl.switchPage (page)
Description: Changes the current page to <page>.
Example:
<a href="javascript:ddCtrl.changePage('Général.Index')">Back to index</a>
void ddCtrl.nextPage ()
Description: Moves to the next page (same function).
Example:
<a href="javascript:ddCtrl.nextPage()">Next page</a>
void ddCtrl.prevPage ()
Description: Moves to the previous page (same role).
Example:
<a href="javascript:ddCtrl.prevPage()">Previous page</a>
(Boolean) ddCtrl.isCurrentPage (page)
Description: Returns true if the current page is the page with the ID specified as a parameter. Returns false otherwise.
(String) ddCtrl.getCurrentPage ()
Description: Returns the name of the current page in the following format: <Role name>.<Page name>.
(Boolean) ddCtrl.isPageLoaded(page)
Description: Returns true if the specified page has already been loaded. Returns false otherwise.
(Boolean) ddCtrl.isCurrentPageLoaded()
Description: Returns true if the current page has already been loaded. Returns false otherwise.
(Object) ddCtrl.getPage(page)
Description: Returns an object containing certain properties (ID, name, title, list of objects, etc.) of the specified page.
(Array) ddCtrl.getPagePath (page)
Description: Returns an array containing the page path (role / page group / page).
(Array) ddCtrl.dashboardPages
Description: An array containing all the pages for all roles of the logged-in user.
Example:
{
console.log(ddCtrl.dashboardPages);
});
(Boolean) canChangeCurrentPage (page)
Description: Returns true if it is possible to switch to the page <page>. Returns false otherwise.
void ddCtrl.hidePage (page)
Description: Hides the tab for page <page> if it is visible, without changing the current page.
Example:
<a href="javascript:ddCtrl.hidePage('Production.Détails Pays'); ddCtrl.changePage('Production.Global')">Exit details</a>
void ddCtrl.showPage (page)
Description: Displays the tab for page <page> if it is hidden, without changing the current page.
Example:
<a href="javascript:ddCtrl.showPage('Production.Détails Pays'); ddCtrl.changePage('Production.Détails Pays')">Show details</a>
void ddCtrl.openFlowInWindow (flow, iWidth, iHeight)
Description: Opens a flow in a pop-up window with the specified width and height.
Example:
<a href="javascript:ddCtrl.openFlowInWindow('fluxId', '250', '200')">Display product breakdown</a>
void ddCtrl.openPortletInWindow (portlet, iWidth, iHeight)
Description: Opens a portlet in a pop-up window with the specified width and height.
Example:
<a href="javascript:ddCtrl.openPortletInWindow('portletId', '250', '200')">Display product breakdown</a>
void ddCtrl.openFlowInWindowWithFilter (flow, iWidth, iHeight, dimension, member [, dimension, member, ...])
Description: Opens a flow in a pop-up window with specified width and height, and filters it by the dimension(s) and member(s) specified as parameters (a list of dimension/member pairs).
Example:
<a href="javascript:ddCtrl.openFlowInWindowWithFilter('fluxId', '250', '200', 'Année', '2014', 'Pays', 'France')">Display details for France 2014</a>
void ddCtrl.openPortletInWindowWithFilter (portlet, iWidth, iHeight, dimension, member [, dimension, member, ...])
Description: Opens a portlet in a pop-up window with the specified width and height, and applies a filter based on the dimensions and members specified as parameters (a list of dimension/member pairs).
Example:
<a href="javascript:ddCtrl.openPortletInWindowWithFilter('portletId', '250', '200', 'Année', '2014', 'Pays', 'France')">Display details for France 2014</a>
void ddCtrl.closeFlowInWindow (flow)
Description: Allows you to programmatically close a pop-up displayed using the openFlowInWindow, openPortletInWindow and openFormInWindow functions.
This function takes as a parameter the identifier that was passed to the function used to display the pop-up.
Example:
ddCtrl.closeFlowInWindow('716abf12')
void ddCtrl.openDocument (serverName, fileName)
Description: Opens a document in a new window.
Example:
<a href="javascript:ddCtrl.openDocument('Common Datasources', 'catalogue_produits.pdf')">Display the product catalogue</a>
void ddCtrl.uploadDocument (serverName, fileName)
Description: Uploads a document to a document server. Opens a file selection window on the workstation.
Example:
<a href="javascript:ddCtrl.uploadDocument('Common Datasources', 'catalogue_produits.pdf')">Upload the product catalogue</a>
void ddCtrl.deleteDocument (serverName, fileName)
Description: Deletes a document from the document server.
Example:
<a href="javascript:ddCtrl.deleteDocument('Common Datasources', 'catalogue_produits.pdf')">Delete the product catalogue</a>
void ddCtrl.downloadDocument (serverName, fileName)
Description: Downloads a document from the document server.
Example:
<a href="javascript:ddCtrl.downloadDocument('Common Datasources', 'catalogue_produits.pdf')">Download the product catalogue</a>
void ddCtrl.refreshDashboard ()
Description: Refreshes the dashboard (same behaviour as the Refresh button in the dashboard header).
Example:
<a href="javascript:ddCtrl.refreshDashboard()">Refresh</a>
void ddCtrl.refreshFlow (flow, [event])
Description: Refreshes the specified flow with an optional event name.
Example:
<A href="javascript:ddCtrl.refreshFlow('flowId', 'MAJ_QUOTIDIENNE')">Refresh Flow</A>
void ddCtrl.refreshFlows ([event])
Description: Refreshes all flows on the dashboard with an optional event name.
Example:
<a href="javascript:ddCtrl.refreshFlows('MAJ_QUOTIDIENNE')"> Refresh all </a>
(String) ddCtrl.getCurrentRole ()
Description: Returns the role ID of the current page or the user’s name for a user page.
(String) ddCtrl.getRole(page)
Description: Returns the role ID of the specified page (e.g. previously retrieved by ddCtrl.getCurrentPage()) or the user’s name if this page is a user page.
void ddCtrl.hidePortlet (portlet)
void ddCtrl.showPortlet (portlet)
Description: Hides or displays the specified chart portlet. The portlet parameter is an identifier that can be retrieved in the dashboard editor via the portlet’s ‘Information’ menu.
Example:
<a href="javascript:ddCtrl.showPortlet('portletId')">Show Details</a>
void ddCtrl.setPortletPos (portlet, x, y)
void ddCtrl.setPortletSize (portlet, width, height)
Description: Positions or resizes the portlet to the specified coordinates or dimensions. The `portlet` parameter is an identifier that can be retrieved in the dashboard editor via the portlet’s ‘Information’ menu.
Example:
<a href="javascript:ddCtrl.setPortletPos('portletId', '100', '100'); ddCtrl.setPortletSize('portletId', '600', '400')">Expand Details</a>
void ddCtrl.setPortletMargins (portlet, marginTop, marginRight, marginBottom, marginLeft)
Description: Specifies the margins to be added to the portlet. The `portlet` parameter is an identifier that can be retrieved from the dashboard editor via the portlet’s Information menu.
Example:
<a href="javascript:ddCtrl.setPortletPos('portletId', '10', '10', '10', '10'); ddCtrl.setPortletMargins('portletId', '600', '400')">Change the margins</a>
(Boolean) ddCtrl.chartIsHidden (portlet)
Description: Returns true when the portlet is hidden (see hideChart) and false otherwise.
void ddCtrl.genTemplatePPT (Flow)
Description: Runs a PowerPoint document builder flow (saves the PPT) with the identifier flowId using the current selection from the dashboard. The user is offered the option to download the generated PPT.
Example:
<A href="javascript:ddCtrl.genTemplatePPT('Id Fabrique De Document')">Download PPT</A>
void ddCtrl.exportCurrentPageAsPPT ()
Description: Saves the current dashboard page in PPT format. The user is offered the option to download the generated PPT.
Example:
<a href="javascript:ddCtrl.exportCurrentPageAsPPT()">Download this page as a PPT</a>
void ddCtrl.exportPageAsPPT (role, page)
Description: Saves the page corresponding to the role and page ID specified as parameters. The user is prompted to download the generated PPT. The page ID can be retrieved in the dashboard editor (right-click on a page tab).
Example:
<a href="javascript:ddCtrl.exportPageAsPPT('Telecom', 'telecom_ventes_1')">Load the telecoms sales PPT</a>
void ddCtrl.genTemplatePDF(flow)
Description: Runs a ‘PDF builder’ flow (saves the PDF) with the identifier flowId using the current selection from the dashboard. The user is prompted to download the generated PDF.
Example:
<A href="javascript:ddCtrl.genTemplatePDF('Id Fabrique De Document')">Download the PDF</A>
void ddCtrl.exportCurrentPageAsPDF ()
Description: Saves the current dashboard page in PDF format. The user is offered the option to download the generated PDF.
Example:
<a href="javascript:ddCtrl.exportCurrentPageAsPDF()">Download this page as a PDF</a>
void ddCtrl.exportPageAsPDF (role, page)
Description: Saves the page corresponding to the role and page ID specified as parameters. The user is offered the option to download the generated PDF. The page ID can be retrieved in the dashboard editor (right-click on a page tab).
Example:
<a href="javascript:ddCtrl.exportPageAsPDF('Telecom', 'telecom_ventes_1')">Download the telecoms sales PDF</a>
void ddCtrl.genTemplateXLS (Flow)
Description: Runs an Excel document builder flow (saves the XLS file) with the identifier flowId using the current selection from the dashboard. The user is prompted to download the generated XLS file.
Example:
<A href="javascript:ddCtrl.genTemplateXLS('Id Fabrique De Document')">Download the XLS</A>
void ddCtrl.genTemplateHTML (Flow)
Description: Runs an HTML Builder flow (saves the HTML) with the identifier flowId using the current selection from the dashboard. The user is offered the option to download the generated HTML.
Example:
<A href="javascript:ddCtrl.genTemplateHTML('Id Fabrique De Document')">Download the HTML</A>
void ddCtrl.exportAsPDF (Flow)
Description: Saves the flow as a PDF. The user is offered the option to download the generated PDF.
void ddCtrl.exportAsPPT (Flow)
Description: Saves the flow as a PPT. The user is offered the option to download the generated PPT.
void ddCtrl.exportAsXLS (Flow)
Description: Saves the flow as an XLS file. The user is offered the option to download the generated XLS file.
void ddCtrl.exportAsXLSWithoutStyles (Flow)
Description: Saves the flow as an XLS file without applying table styles to improve performance. The user is prompted to download the generated XLS file.
void ddCtrl.exportAsCSV (Flow)
Description: Saves the flow as a CSV (Comma-Separated Values) file. The user is prompted to download the generated CSV file.
void ddCtrl.saveDashboardState (name, default)
Description: Saves the current state of the dashboard (page, filters, drill-down, variables). This is identical to the action triggered by the ‘Save Selection’ button in the dashboard toolbar. The name parameter is the name of the selection; the bDefault parameter enables the selection to be loaded when the dashboard starts.
(String) ddCtrl.getCurrentPortletInGroupOfTabs (portletTabId)
Description: Returns the ID of the current portlet in the Tab Group object. The `portletTabId` parameter is the ID of the Tab Group.
void ddCtrl.changePortletInGroupOfTabs (portletTabId, portletId)
Description: Changes the current portlet of the Tab Group object. The `portletTabId` parameter is the identifier of the Tab Group; the `portletId` parameter is the identifier of the portlet to be selected.
(Array) ddCtrl.getCurrentPagePath ()
Description: Returns the path of the current page (Role / Page / Subpage) as an array of objects. Each object has the following attributes: id, title, name, type (role/container/page).
void ddCtrl.expandCollapseNavigationMenu()
Description: Collapses the navigation menu if it is expanded, and vice versa.
Scale Mode Functions
These functions relate to zoom selection in Scale or Grid + Scale mode.
void ddCtrl.setScalingZoom(zoom)
Description: Sets the zoom level to the specified value.
Example:
<a href="javascript:ddCtrl.setScalingZoom(0.65)">Set the page zoom to 65%</a>
void ddCtrl.setScalingAdaptWidth()
Description: applies the ‘Adapt to width’ zoom.
void ddCtrl.setScalingAdaptHeight()
Description: applies the ‘Adapt to height’ zoom.
void ddCtrl.setScalingZoomRange(min, max)
Description: sets the minimum and maximum zoom limits. The user will not be able to set a zoom level outside these values.
Example:
<a href="javascript:setScalingZoomRange(0.4,1.2)">Set a zoom range between 40 and 120%</a>
Event handling
These listener functions are called by the system when specific events are triggered. You can therefore create new behaviours depending on different situations: a chart is refreshed or drawn, a page is changed, a dimension is filtered, etc. The best place to implement these behaviours is in the global JavaScript editor, accessible via the options menu in the dashboard editor.
Dashboard Events Diagram
void ddCtrl.addChartBeforeRefreshListener (Function)
Description: Adds a listener function for the event triggered before the chart is refreshed.
Example:
ddCtrl.addChartBeforeRefreshListener(function(doc, dm, dmsel, chart, errorMsg) { alert("The chart " + chart.title + " is about to be refreshed"); });
void ddCtrl.addChartRefreshListener (Function)
Description: Adds a function to listen for the event triggered after the chart has been refreshed.
Example:
ddCtrl.addChartRefreshListener(function(doc, dm, dmsel, chart, errorMsg) { alert("The chart " + chart.title + " has been refreshed"); });
void ddCtrl.addChartDrawnListener (Function)
Description: Adds a function to listen for the event triggered when the chart has finished being drawn (first display).
Example:
ddCtrl.addChartDrawnListener(function(doc, dm, dmsel, chart, errorMsg) { alert("The chart " + chart.title + " has been drawn"); });
void ddCtrl.addChartModelReadyListener (Function)
Description: Adds a listener function for the event triggered before the chart is drawn (first display).
Example:
ddCtrl.addChartModelReadyListener(function(doc, dm, dmsel, chart, errorMsg) { alert("The chart " + chart.title + " is about to be drawn"); });
void ddCtrl.addDimensionFilterListener (Function)
Description: Adds a listener function for the event triggered after a dimension has been filtered.
Example:
ddCtrl.addDimensionFilterListener(function(dimension, hierarchy, level, members, membersFormatted, bExclude, min, max) { alert("The dimension " + dimension + " has been filtered to " + membersFormatted); });
void ddCtrl.addVariableChangeListener (Function)
Description: Adds a listener function for the event triggered after a variable has been changed.
Example:
ddCtrl.addVariableChangeListener(function(variable, value) { alert("The variable " + variable + " has changed; new value: " + value); });
Dashboard Event Handling
void ddCtrl.addDashboardLoadListener (Function)
Description: Adds a listener for the event triggered once the dashboard has loaded but has not yet been rendered.
Example:
ddCtrl.addDashboardLoadListener(function(currentPage) { alert("Initialising the dashboard"); });
void ddCtrl.addCurrentPageLoadListener (Function)
Description: Adds a function to listen for the event triggered once the dashboard page has fully loaded.
Example:
ddCtrl.addCurrentPageLoadListener(function(currentPage) { alert("Page " + currentPage + " has been loaded"); });
void ddCtrl.addCurrentPageChangeListener (Function)
Description: Adds a function to listen for the event triggered when a page changes.
Example:
ddCtrl.addCurrentPageChangeListener(function(currentPage, bFirstTime) { alert("The page is now " + currentPage); });
void ddCtrl.addUserLoggedListener (Function)
Description: Event triggered once the user has been authenticated. May be useful when using the ddCtrl.getUserAttribute function.
Example:
ddCtrl.addUserLoggedListener(function() { alert("You are logged in"); });
void ddCtrl.addPortletHiddenListener (Function)
Description: Event triggered when the object’s status changes from visible to hidden.
Example:
ddCtrl.addPortletHiddenListener(function(portletId) { alert("The object is hidden"); });
void ddCtrl.addPortletVisibleListener (Function)
Description: Event triggered when the object’s status changes from hidden to visible.
Example:
ddCtrl.addPortletVisibleListener(function(portletId) { alert("The object is visible"); });
void ddCtrl.addPortletCollapseListener (Function)
Description: Event triggered when the user clicks the icon to hide a retractable element.
Example:
ddCtrl.addPortletCollapseListener(function(portletId) { alert("The object is about to be hidden"); });
void ddCtrl.addPortletCollapsedListener (Function)
Description: Event triggered once the retractable element has been hidden.
Example:
ddCtrl.addPortletCollapsedListener(function(portletId) { alert("The object is hidden"); });
void ddCtrl.addPortletExpandListener (Function)
Description: Event triggered when the user clicks the icon to expand a retractable element.
Example:
ddCtrl.addPortletExpandListener(function(portletId) { alert("The object is about to be displayed"); });
void ddCtrl.addPortletExpandedListener (Function)
Description: Event triggered once the retractable element has been displayed.
Example:
ddCtrl.addPortletExpandedListener(function(portletId) { alert("The object is displayed"); });
void ddCtrl.addGroupOfTabsChangeListener (Function)
Description: Event triggered when the user changes the chart within a group of tabs. The first parameter is the identifier of the group of tabs object; the second is the identifier of the current portlet.
Example:
ddCtrl.addGroupOfTabsChangeListener(function(portletTabId, curPortletId) { alert("The current portlet is: " + curPortletId); });
void ddCtrl.addDocumentUploadListener (Function)
Description: event triggered when the user adds a file via the dashboard.
Example:
ddCtrl.addDocumentUploadListener(function(serverName, filesName) { alert("The file " + filesName[0] + " has been successfully added"); });
void ddCtrl.addScalingZoomListener(function(zoomConfig){}) (Function)
Description: Adds a listener for the event triggered after a change in the zoom level for a page in Scale or Grid + Scale mode.
Example:
ddCtrl.addScalingZoomListener(function(zoomConfig){
console.log("The zoom level has been changed: " + JSON.stringify(zoomConfig));
});
Miscellaneous functions
(String array) ddCtrl.getUserRoles ()
Description: Returns the list of role IDs for the logged-in user.
(Associative array of strings / booleans) ddCtrl.getUserACLs ()
Description: Returns a list of the access control list (ACL) IDs for the logged-in user. The returned list is an associative array linking the ACL ID to a Boolean (true) if the ACL is granted to the user.
Example:
if (ddCtrl.getUserACLs()['SaveAsPPT']) alert("You can save as PPT");
List of all possible authorizations:
AccessDBV, AccessDBE, EditDashboardForGroup, LoadWalletForGroup, SaveWalletForGroup, AddFlow, AddRoleFlow, RefreshFlow, RefreshRoleFlow, AccessServerSettings, AccessUserSettings, AccessLicenseSettings, AccessContentManagement, Scheduler, EditDataSourceForGroup, EditDataSource, SaveAsPDF, SaveAsPPT, SaveAsXLS, SaveAsXLSWithoutStyles, SaveAsCSV, ChartNavigation, SendSMS, UploadDocument, UpdateDocument, ListDocumentServers, ListDocuments, ViewComments, AddCommentDataModel, RemoveCommentDataModel, AddCommentFlow, RemoveCommentFlow, AllowIgnoreDMResivion, DashboardCustomization, DashboardJSCustom, DashboardTheme, EditProtectedDashboardPages, DashboardOfflineMode, DashboardNavigationMenu, DictionaryManager, DeviceManager, FormatManager, DBConnectionManager, ColorPaletteManager, PredefinedFunctionManager, StylesManager, HierarchyManager, IconManager, MapManager, ManageACLGroup, ManageProfil, AccessServerStatus, AccessBackup, AccessRestore, ManageScripts, ManageSentences, ManageRole, ManageAllRoles, ManageSchedules, ManageD3, PrintChart, EditUserAttributes, EditUserVariables, AssignProfil, ManageACL, EditProtectedUserVariables, UseAdHocAnalysis, SaveView, SavePublicView, ViewRestrictedData, DependencyAnalyser, TextQuery, AccessStudio, AccessDashboardAssistant, ViewAllComments, DownloadFromCMDR, CreateForm, AddFormData, ManageFormData, ManageAllForms, AllowImpersonate, ManageCommonItems, ManageRoleItems, ExportUsers, ImportUsers, ViewAllUsersInfo, SendMail, AddRole, EditFileDataSource, EditDBDataSource, EditReportDataSource, EditUnionDataSource, EditJoinDataSource, EditTransformerDataSource, EditColTransformerDataSource, EditIODataSource, EditDataCatalogDataSource, AllowSetQuotaByModel, ManageUserParams
(String) ddCtrl.getUserAttribute (attr)
Description: Returns the user’s LDAP attribute <attr>.
(String) ddCtrl.getUserAttribute (attr, Function)
Description: Returns the user’s LDAP attribute <attr> via an asynchronous call function.
Example:
ddCtrl.getUserAttribute('displayName', function (attrVal) {alert(attrVal)});
(String) ddCtrl.getSessionAttribute (attr)
Description: Returns the <attr> attribute of the user’s session.
See the Session Variables Tutorial for more information on session variables.
(String) ddCtrl.getSessionAttribute (attr, Function)
Description: Returns the <attr> attribute of the user session via an asynchronous callback function.
Example:
ddCtrl.getSessionAttribute('regionSelected', function (attrVal) {alert(attrVal)});
See the Session Variables Tutorial for more information on session variables.
void ddCtrl.setSessionAttribute (attr, value)
Description: Updates the <attr> attribute of the user session with the specified value.
Example:
ddCtrl.setSessionAttribute('regionSelected', ‘France’);
See the Session Variables Tutorial for more information on session variables.
(String) ddCtrl.getServerAttribute (attr)
Description: Returns the <ATTR> attribute of the server. Server attributes (or variables) allow you to specify constants used in data models and Flows via the keyword ${server.<ATTR>}.
See the Advanced System Settings for more information on server variables.
(String) ddCtrl.getServerAttribute (attr, Function)
Description: Returns the <attr> server attribute via an asynchronous call.
Example:
ddCtrl.getSessionAttribute('serverMode', function (attrVal) {alert(attrVal)});
See the Advanced System Settings for more information on server variables.
(String) ddCtrl.getUserStorage (attr)
Description: Returns the <attr> attribute of the specified user that was previously saved.
Example:
var value = ddCtrl.getUserStorage('attribute');
void ddCtrl.setUserStorage (attr, value)
Description: Saves the user’s <attr> attribute persistently on the server for future use.
Example:
ddCtrl.setUserStorage('attribute', 'value');
void ddCtrl.fireRefreshEvent (event)
Description: Triggers a server-side refresh of the data associated with the specified event
Example:
ddCtrl.fireRefreshEvent('DAILY_UPDATE');
void ddCtrl.newAuthToken ()
Description: Returns an authentication token generated for the current session.
Example:
var token = ddCtrl.newAuthToken();
window.open("http://localhost:8080/digdash_dashboard/index.html?user=mon_user&authToken=token");
void loadCSS(cssFile)
Description: Loads a CSS file.
void ddCtrl.loadTheme (cssTheme)
Description: Loads a DigDash CSS theme onto the dashboard.
Example:
ddCtrl.loadTheme(‘digdash’);
void ddCtrl.removeTheme (cssTheme)
Description: Removes the DigDash CSS theme from the dashboard.
Example:
ddCtrl.removeTheme('digdash');
void openFormInWindow (portlet, width, height, dimension, member [, dimension, member, ...])
Description: Opens a form (where `portlet` is the form object added to a dashboard page) in a pop-up window and filters it by the dimension(s) and member(s) specified as parameters (a list of dimension/member pairs).
Example:
<a href="javascript:ddCtrl.openFormInWindow('portletId', '80%', '80%', 'Year', '2024', 'Country', 'France')">Displays the form with the values ‘France 2024’</a>
void initFormData (portlet, field name, field value [, name, value, ...])
Description: Initialises a form with the values specified as parameters (a list of key-value pairs for the form fields).
Example:
<a href="javascript:ddCtrl.initFormData('1906313430','f_project_name','DigDash')">Initialises the form with the value ‘DigDash’ for the ‘Project Name’ field</a>
- To retrieve the portlet ID, open the portlet’s Information tab in the Dashboard Editor and copy the Unique ID.
- To retrieve the key for a form field: edit the form, click the ‘Edit JSON ’ button in the top right-hand corner of the form and copy the ‘key’ value: in this example, ‘f_project_name’.
void logout ()
Description: Logs out the current user.