Embedded Dashboard Events

Contents:

Application State Events

You can use application state events to monitor changes in the application state, for example:

  • When the GoodData platform is down for maintenance, you can set a custom page to load when triggered by a notification of this event (in place of GoodData’s maintenance page).
  • When an error state renders a project inaccessible, you can display a custom error page.

The application loaded successfully

Event trigger: The application successfully loaded.

{
	gdc: {
		name: 'platform.info',
		type: 'app.ok'
	}
}

The report loaded successfully

Event trigger: The report successfully loaded.

{
	gdc: {
		name: 'report.info',
		type: 'app.ok'
	}
}

A user is active

Event trigger: A user is active in the embedded dashboard (listening to click and scroll events); the emit interval is 10 seconds.

{
	gdc: {
		name: 'ui.active',
		type: 'app.ok'
	}
}

A user has no access to a project

Event trigger: A user tries to access an embedded dashboard in a project that they do not have access rights to.

{
	gdc: {
		name: 'project.info.no.permission',
		type: 'app.ok'
	}
}

The frame size changed

Event trigger: The height of the content of the embedded dashboard changes, which happens when a tab is switched.

{
	gdc: {
		name: 'ui.frameinfo',
		type: 'app.ok'
		data: {
			height: {Number}, // pixel height of the contents
			width: {Number} // pixel width of the contents
		}
	}
}

Dashboard export initiated - embedded content started loading

Event trigger: The content of the embedded dashboard starts loading after a user chose to export to PDF the dashboard that hosts the embedded dashboard.

The dashboard export is paused until the content loading completes (the timeout is 30 seconds), which is indicated by the event 'Dashboard export initiated - embedded content completed loading'.

If the event 'Dashboard export initiated - embedded content completed loading' is not triggered for 30 seconds, the dashboard export to PDF resumes anyway, and the resulting PDF file is generated. To change the timeout, update the 'embedReadyTimeout' platform setting (see Platform Settings).

gdc: {
	name: 'embedded.init',
	type: 'app.ok'
}

Dashboard export initiated - embedded content completed loading

Event trigger: The content of the embedded dashboard completes loading.

The dashboard export to PDF resumes, and the resulting PDF file is generated.

This event follows the event 'Dashboard export initiated - embedded content started loading'.

gdc: {
	name: 'embedded.ready',
	type: 'app.ok'
}

Dashboard attribute and date filters changed

Event trigger: Attribute filters and date filters on the embedded dashboard (or the dashboard with embedded content) have changed.

See also: 'Apply attribute and date filters to a dashboard' in Embedded Dashboard Methods.

{
    gdc: {
        name: "filter.value.changed",
        type: "app.ok",
        data: [
            {
                label: "attribute.filter",
                type: "attribute",
                value: "attribute.value.1"
            },
            {
                label: "date.filter",
                type: "date",
                from: "2017-01-01", // (format: yyyy-mm-dd)
                to: "2017-12-31" // (format: yyyy-mm-dd)
            }
        ]
    }
}

The GDC_SELECT_ALL value for an attribute filter indicates that the filter is no longer applied to the dashboard (that is, all filter values are selected, which is similar to clicking Select all for an attribute filter in the GoodData Portal UI):

{
    gdc: {
        name: "filter.value.changed"
        type: "app.ok",
        data: [
            {
                label: "attribute.filter",
                type: "attribute",
                value: "GDC_SELECT_ALL"
            }
        ]
    }
}

Application servers are locked - maintenance

Event trigger: Application servers are locked for maintenance.

{
	gdc: {
		name: 'platform.maintenance',
		type: 'app.down'
	}
}

Application servers are locked - upgrade

Event trigger: Application servers are locked for upgrading to a new version.

{
	gdc: {
		name: 'platform.upgrade',
		type: 'app.down'
	}
}

A project is undergoing maintenance

Event trigger: The project is under maintenance.

{
	gdc: {
		name: 'project.maintenance',
		type: 'app.down',
		data: {
			projectUri: URISTRING
		}
	}
}

SST expired

Event trigger: The SuperSecure Token (SST) has expired.

{
	gdc: {
		name: 'sst.expired',
		type: 'app.ok'
	} 
}

A general error occurs

Event trigger: A general error occurs.

{
	gdc: {
		name: 'platform.error',
		type: 'app.down',
		data: {
			errorId: ID,
			errorCode: STRING
		}
	}
}

User Action Events

By default, all user actions are handled internally by the dashboard. You can override them by custom behavior.

  • Override the default behavior of a user action event
    To override the default behavior of a user action event, list its name in the override parameter in the embedded code, for example:

    <iframe src="....&override=ui.link">

    You can specify multiple events in the URL. Separate individual event names by comma.

  • Force the default event behavior
    To force the dashboard to handle a user action event using its default behavior, send the following message (ID must match the original action event ID):

    {
    	gdc: {
    		handleEvent: ID
    	}
    }

Event trigger: A user clicks a link, which opens a page in an external window. For example, if you click a text link in a dashboard, it may trigger the opening of a new page in a new browser tab. This event is also triggered when a drill action on a report opens an external page.

{
	gdc: {
		name: 'ui.link',
		type: 'app.event',
		data: {
			uri: 'https://support.gooddata.com/'
		}
	}
}

A user drills into an embedded report or an embedded dashboard

This event is initiated only when you change the default behavior and make your system handle a report drill event (see Handle Drilling Report Requests through Your Web Application). Otherwise, the event is not emitted.

Event trigger: A user clicks a value within an embedded report, or in a report in the embedded dashboard. This event can be passed to the parent web application. The parent web application detects:

  • The report and the report filters
  • The value that the user clicked
  • (For embedded dashboards only) The filters that were applied to the dashboard (on top of the report filters) at the moment when the user drilled into the report.

Based on the obtained information, the parent web application can build the target report with the data from your system. This way, the user can drill into the report in the context of their system’s data. This is especially useful for displaying the most granular data in the source application’s web user interface.

{	
	gdc: {
		name: 'ui.drill',
		type: 'app.event',
		data: {
			executionContext: {...serializedExecutionContext},
			reportUri: URISTRING
		}
	}
}

where:

  • executionContext is the event execution parameters:
    • Metadata about the clicked value, such as what value was clicked (the value URI), the value type (attribute or metric), and others
    • (For embedded dashboards only) The filters that are applied to the dashboard
  • reportUri is the URI that points to the definition of the report that the user clicked. The report definition contains information on the report filters.

For more information on how to use this event, see Handle Drilling Report Requests through Your Web Application.

For similar behavior in embedded Analytical Designer and KPI dashboards, see Setting up Events for Drilling in Embedded Analytical Designer and KPI Dashboards.

A user exports a report

This method is in beta release and is still subject to changes.

Event trigger: A user clicks the button to export a report from the dashboard.

Make sure that you have listed the event name (report.export) in the override parameter in the embed URL.

{
	gdc: {
		eventId: ID,
		name: 'report.export',
		type: 'app.event',
		data: {
			reportUri: ..., % URI of the original report
			exportRequest: ...
		}
	}
}

where:

  • reportUri is the URI of the original report in the dashboard or the URI of the drill-across report that is to be exported.
  • exportRequest is the JSON of the report export request.

Example

The following is an example of the code that you can implement into your web application to manage event triggered by an embedded dashboard.

This example does not work in Internet Explorer 9 due to addEventListener incompatibility. For cross-browser compatibility, use jQuery or other JS library to add event listeners.


For this example, your iframe URL must be appended with the following:

&override=ui.link,report.export
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Parent app</title>
</head>
<body>
<iframe id="gooddata" src="https://secure.gooddata.com/dashboard.html#project={Project_URI}&dashboard={Dashboard_URI}&override=ui.link,report.export" width="100%" height="600px" frameborder="0"></iframe>
<script>
	// Initialize variables for the parent app and dashboard windows
	var dashboardWindow = document.getElementById('gooddata').contentWindow;
	var parentAppWindow = window;

	// Handles the application down events 
	function handleApplicationStateEventDown(message) {
		var reason;
		switch (message.name) {
			case 'platform.upgrade':
				reason = 'GoodData platform is being upgraded to a newer version';
				break;

			case 'platform.maintenance':
				reason = 'GoodData platform is under maintenance';
				break;

			case 'project.maintenance':
				reason = 'Project is under maintenance';
				break;

			case 'platform.error':
				default:
				reason = 'An error occurred while loading the GoodData application';
				break;
		}
		window.alert('Oh no, application is down ' + reason + '!', true);
	}

	// Handles user action events 
	function handleUserActionEvent(message) {
		switch(message.name) {
			case 'ui.link':
				window.alert('Handling click to link for ' + message.data.uri);
				break;

			case 'report.export':
				window.alert('Handling export of report ' + message.data.reportUri);
				break;
			default:
				window.alert('Unknown user action event');
				return;
		}

		// Change this to false if you want the event be handled by GoodData the default way
		var defaultHandling = true;

		if (defaultHandling) {
			var confirmMessage = {
				gdc: {
					handleEvent: message.eventId
				}
			};

			dashboardWindow.postMessage(JSON.stringify(confirmMessage), '*');
		}
	}

	// Listen for messages in the parent app window
	parentAppWindow.addEventListener('message', function(e) {
		var message = JSON.parse(e.data);
		if (message.gdc) {
			message = message.gdc;

			switch (message.type) {
				case 'app.ok':
					if (message.name == 'platform.info') window.alert('Application loaded successfully');
					if (message.name == 'ui.active') window.alert('User activity');
					if (message.name == 'ui.frameinfo') window.alert('Frame size changed, height:' + message.data.height);
					break;

				case 'app.down':
					handleApplicationStateEventDown(message);
					break;

				case 'app.event':
					handleUserActionEvent(message);
					break;

				default:
					window.alert('Unknown GoodData event');
			}
		}
	}, false);
</script>
</body>
</html>