The Portals Extension Module has been created to allow 3rd party content and applications to be integrated inside Portals. This documentation is split into several parts and each relevant section also includes a list of API functions:
Including Portals API in your application
The Extension module allows integration of your application into portals by providing an iFrame for your content and an API for communication with Portals. The module accepts an url and allows dynamic GET parameters to be passed to your application through that url. Just select the participant variables and master data you want to pass to your application and provide names for the GET keys.
A portals page can have several Extension modules on a single page and all modules can communicate with each other through the provided message bus in the Portals API.
For enhanced data exchange with EFS, we recommend that your application uses the EFS ServiceLayer in the backend to query and update data in EFS.
Import
In your application, you have to import the PortalsAPI JavaScript file in order to be able to use the message bus or other Portals API functions.
<script src="https://{yourEFSInstallation}/public/modules/portals/dist/portalsApi/portalsApi-1.0.js"></script>
Initialization
After your document has finished loading you need to initialize the api. This registers your document with Portals for messaging.
<script> Questback.portalsApi.initialize() .then(function() { ... } .catch(function(error) { ... }); </script>
Checking initialization status
You can check the initialization status by calling isInitialized, though it is generally recommended to do your api operations in the then-handler of the initialize method as shown above.
Questback.portalsApi.isInitialized();
Unregister
You can completely revert the registration of the iFrame and unregister all its handlers by calling unregister.
Questback.portalsApi.unregister();
Using the Portals message bus
The message bus is intended for communication between extension module iFrames. You can send and listen to your own events and transfer any data you want.
Listening for messages
After the initialization has been completed you can start to register handlers for events from other iFrames. The example code registers a handler for an event called "myEvent". This is an event name that you expect other iFrames to send messages for.
Questback.portalsApi.initialize().then(function() { Questback.portalsApi.bus.subscribe('myEvent', function(data) { ... }); };
Sending messages
Sending a message to other iFrames is just as simple. You just call the send method with an eventname that you chose and a data object as second parameter.
Questback.portalsApi.bus.send('myEvent', { foo : "bar"});
Just note that you do not get a result back from this call, as it works like a broadcast. Also note that by default the sending iFrame will not receive its own event back, even if it has registered a handler for it. You can supply a third parameter to send with a value of true to force sending the event to the sender iFrame, too.
Stop listening for messages
You can remove handlers for events by an eventname.
Questback.portalsApi.bus.unsubscribe('myEvent');
Note that this removes all handlers for the given eventname for this iFrame at once.
Querying data from Portals
The api supplies a set of methods to request specific data from Portals.
query.portalInfo
Get information about the portal.
Questback.portalsApi.query.portalInfo().then(function(result) { console.log(result.portal.id); });
query.user
Get the user object of the currently logged in user. Returns null if there is no logged in user.
Questback.portalsApi.query.user().then(function(result) { console.log(result.user); });
query.language
Get the language object of the currently used language.
Questback.portalsApi.query.language().then(function(result) { console.log(result.language); });
query.deviceInfo
Get information about the client device.
Questback.portalsApi.query.deviceInfo().then(function(result) { console.log(result.device.isMobile); });
query.ajax (reserved for future use)
Makes an ajax call to the internal portals server API and returns the result. Since Portals itself does not provide a public portals server API, this function is reserved for future use.
Questback.portalsApi.query .ajax('GET', '/api/portal/client/pages') .then(function(result) { console.log(result); }) .catch(function(error) { console.log(error); });
Trigger actions in Portals
The api supplies a set of methods to trigger specific actions in Portals.
trigger.height
Set the iFrames height to a specified value, given as a string including the unit.
Questback.portalsApi.trigger.height('300px');
trigger.autoHeight
Set the iFrames height to the height of its content. This is done once per call, not repeatedly. So you have to react to resize events yourself.
Questback.portalsApi.trigger.autoHeight();
trigger.logout
Log out the current user from Portals and thus redirect to the configured landing page. The iFrame will be removed from the DOM by this opreation.
Questback.portalsApi.trigger.logout();
trigger.route
Redirect to the given page slug. The iFrame will be removed from the DOM by this opreation.
Questback.portalsApi.trigger.route('targetPageSlug');
Accessing MySight instances in Portals
There are a number of methods to interact with Tableau in a MySight module. For all of these you need the pageModuleIdentifier of a MySight module to target your requests. This identifier is set in the Portals CMS in the settings for the MySight page module and can be reused on other pages for the same or even different Tableau instances.
mySight.vizGetIsReady
Gets whether the onFirstInteractive event has been fired yet.
Questback.portalsApi.mySight.vizGetIsReady(pageModuleIdentifier) .then(function(ready) { ... });
mySight.vizGetAreTabsHidden
Gets whether the tabs are hidden or not.
Questback.portalsApi.mySight.vizGetAreTabsHidden(pageModuleIdentifier) .then(function(hidden) { ... });
mySight.vizGetIsToolbarHidden
Gets whether the tabs are hidden or not.
Questback.portalsApi.mySight.vizGetIsToolbarHidden(pageModuleIdentifier) .then(function(hidden) { ... });
mySight.vizGetUrl
Gets the url of the viz.
Questback.portalsApi.mySight.vizGetUrl(pageModuleIdentifier) .then(function(url) { ... });
mySight.vizGetCurrentUrl
Gets the current url of the viz.
Questback.portalsApi.mySight.vizGetCurrentUrl(pageModuleIdentifier) .then(function(currentUrl) { ... });
mySight.vizGetIsHidden
Gets whether the viz is hidden or not.
Questback.portalsApi.mySight.vizGetIsHidden(pageModuleIdentifier) .then(function(hidden) { ... });
mySight.vizShow
Shows the viz.
Questback.portalsApi.mySight.vizShow(pageModuleIdentifier) .then(function() { ... });
mySight.vizHide
Hides the viz.
Questback.portalsApi.mySight.vizHide(pageModuleIdentifier) .then(function() { ... });
mySight.vizDispose
Disposes the viz.
Questback.portalsApi.mySight.vizDispose(pageModuleIdentifier) .then(function() { ... });
mySight.vizGetAreAutomaticUpdatesPaused
Gets the status of automatic updates.
Questback.portalsApi.mySight.vizGetAreAutomaticUpdatesPaused(pageModuleIdentifier) .then(function(paused) { ... });
mySight.vizPauseAutomaticUpdates
Pauses automatic updates.
Questback.portalsApi.mySight.vizPauseAutomaticUpdates(pageModuleIdentifier) .then(function() { ... });
mySight.vizResumeAutomaticUpdates
Resumes automatic updates.
Questback.portalsApi.mySight.vizResumeAutomaticUpdates(pageModuleIdentifier) .then(function() { ... });
mySight.vizToggleAutomaticUpdates
Toggles automatic updates.
Questback.portalsApi.mySight.vizToggleAutomaticUpdates(pageModuleIdentifier) .then(function() { ... });
mySight.vizRevertAll
Restores the initial state. Note that url parameters will be ignored in this operation and as such the restored state may differ from the real initial state.
Questback.portalsApi.mySight.vizRevertAll(pageModuleIdentifier) .then(function() { ... });
mySight.vizRefreshData
Refreshes data from the server.
Questback.portalsApi.mySight.vizRefreshData(pageModuleIdentifier) .then(function() { ... });
mySight.vizShowDownloadWorkbookDialog
Shows the download workbook dialog.
Questback.portalsApi.mySight.vizShowDownloadWorkbookDialog(pageModuleIdentifier) .then(function() { ... });
mySight.vizShowExportImageDialog
Shows the export image dialog.
Questback.portalsApi.mySight.vizShowExportImageDialog(pageModuleIdentifier) .then(function() { ... });
mySight.vizShowExportPDFDialog
Shows the export PDF dialog.
Questback.portalsApi.mySight.vizShowExportPDFDialog(pageModuleIdentifier) .then(function() { ... });
mySight.vizShowExportDataDialog
Shows the export data dialog for the current or a specific sheet.
Questback.portalsApi.mySight.vizShowExportDataDialog(pageModuleIdentifier, sheetName) .then(function() { ... });
mySight.vizShowExportCrossTabDialog
Shows the export cross tab dialog for the current or a specific sheet.
Questback.portalsApi.mySight.vizShowExportCrossTabDialog(pageModuleIdentifier, sheetName) .then(function() { ... });
mySight.vizShowShareDialog
Shows the share dialog for the current or a specific sheet.
Questback.portalsApi.mySight.vizShowShareDialog(pageModuleIdentifier, sheetName) .then(function() { ... });
mySight.vizSetFrameSize
Sets the vizs frame size. Note that the min-width might be set to 100% by Portals, taking precedence over any width that is set here.
Questback.portalsApi.mySight.vizSetFrameSize(pageModuleIdentifier, width, height) .then(function() { ... });
mySight.workbookGetName
Gets the name of the workbook.
Questback.portalsApi.mySight.workbookGetName(pageModuleIdentifier) .then(function(name) { ... });
mySight.workbookGetSheetsInfo
Gets information about all sheets.
Questback.portalsApi.mySight.workbookGetSheetsInfo(pageModuleIdentifier) .then(function(sheetsInfo) { ... });
mySight.workbookGetActiveSheetName
Gets the name of the active sheet.
Questback.portalsApi.mySight.workbookGetActiveSheetName(pageModuleIdentifier) .then(function(name) { ... });
mySight.workbookGetActiveSheetIndex
Gets the index of the active sheet.
Questback.portalsApi.mySight.workbookGetActiveSheetIndex(pageModuleIdentifier) .then(function(index) { ... });
mySight.workbookActivateSheet
Actives a sheet by its name or index.
Questback.portalsApi.mySight.workbookActivateSheet(pageModuleIdentifier, sheetNameOrIndex) .then(function() { ... });
mySight.workbookRevertAll
Restores the initial state of the workbook. Note that url parameters will be ignored in this operation and as such the restored state may differ from the real initial state.
Questback.portalsApi.mySight.workbookRevertAll(pageModuleIdentifier) .then(function() { ... });
mySight.workbookGetParameterNames
Gets a list of the parameter names.
Questback.portalsApi.mySight.workbookGetParameterNames(pageModuleIdentifier) .then(function(names) { ... });
mySight.workbookGetParameterCurrentValue
Gets the current value of a parameter.
Questback.portalsApi.mySight.workbookGetParameterCurrentValue(pageModuleIdentifier, parameterName) .then(function() { ... });
mySight.workbookGetParameterDataType
Gets the data type of a parameter.
Questback.portalsApi.mySight.workbookGetParameterDataType(pageModuleIdentifier, parameterName) .then(function(dataType) { ... });
mySight.workbookGetParameterAllowableValuesType
Gets the type of allowable values of a parameter.
Questback.portalsApi.mySight.workbookGetParameterAllowableValuesType(pageModuleIdentifier, parameterName) .then(function(allowableValuesType) { ... });
mySight.workbookGetParameterAllowableValues
Gets a list of allowable values of a parameter.
Questback.portalsApi.mySight.workbookGetParameterAllowableValues(pageModuleIdentifier, parameterName) .then(function(allowableValues) { ... });
mySight.workbookGetParameterMinValue
Gets the min value of a parameter.
Questback.portalsApi.mySight.workbookGetParameterMinValue(pageModuleIdentifier, parameterName) .then(function(minValue) { ... });
mySight.workbookGetParameterMaxValue
Gets the max value of a parameter.
Questback.portalsApi.mySight.workbookGetParameterMaxValue(pageModuleIdentifier, parameterName) .then(function(maxValue) { ... });
mySight.workbookGetParameterStepSize
Gets the step size of a parameter.
Questback.portalsApi.mySight.workbookGetParameterStepSize(pageModuleIdentifier, parameterName) .then(function(stepSize) { ... });
mySight.workbookGetParameterDateStepPeriod
Gets the date step period of a parameter.
Questback.portalsApi.mySight.workbookGetParameterDateStepPeriod(pageModuleIdentifier, parameterName) .then(function(dateStepPeriod) { ... });
mySight.workbookChangeParameterValue
Sets a parameter to a given value.
Questback.portalsApi.mySight.workbookChangeParameterValue(pageModuleIdentifier, parameterName, value) .then(function(newValue) { ... });
mySight.sheetGetName
Gets the name of a sheet by its index.
Questback.portalsApi.mySight.sheetGetName(pageModuleIdentifier) .then(function(name) { ... });
mySight.sheetGetIndex
Gets the index of a sheet by its name.
Questback.portalsApi.mySight.sheetGetIndex(pageModuleIdentifier) .then(function(index) { ... });
mySight.sheetGetIsActive
Gets whether a sheet is active or not.
Questback.portalsApi.mySight.sheetGetIsActive(pageModuleIdentifier, sheetNameOrIndex) .then(function(active) { ... });
mySight.sheetGetIsHidden
Gets whether a sheet is hidden or not.
Questback.portalsApi.mySight.sheetGetIsHidden(pageModuleIdentifier, sheetNameOrIndex) .then(function(hidden) { ... });
mySight.sheetGetType
Gets the type of the currently active or a specific sheet.
Questback.portalsApi.mySight.sheetGetType(pageModuleIdentifier, sheetNameOrIndex) .then(function(type) { ... });
mySight.sheetGetUrl
Gets the url of the currently active or a specific sheet.
Questback.portalsApi.mySight.sheetGetUrl(pageModuleIdentifier, sheetNameOrIndex) .then(function(url) { ... });
mySight.sheetGetSize
Gets the size of the currently active or a specific sheet.
Questback.portalsApi.mySight.sheetGetSize(pageModuleIdentifier, sheetNameOrIndex) .then(function(size) { ... });
mySight.sheetChangeSize
Sets the size of the active sheet.
Questback.portalsApi.mySight.sheetChangeSize(pageModuleIdentifier, sheetSizeOptions) .then(function() { ... });
mySight.sheetGetFilters
Gets the filters of a sheet specified by its name.
Questback.portalsApi.mySight.sheetGetFilters(pageModuleIdentifier, sheetName) .then(function(filters) { ... });
mySight.sheetApplyFilter
Applies the filter for a sheet specified by its name.
Questback.portalsApi.mySight.sheetApplyFilter(pageModuleIdentifier, sheetName, fieldName, values, updateType, options) .then(function(fieldName) { ... });
mySight.sheetApplyRangeFilter
Applies the range filter for a sheet specified by its name.
Questback.portalsApi.mySight.sheetApplyRangeFilter(pageModuleIdentifier, sheetName, fieldName, range) .then(function(fieldName) { ... });
mySight.sheetApplyRelativeDateFilter
Applies the relative date filter for a sheet specified by its name.
Questback.portalsApi.mySight.sheetApplyRelativeDateFilter(pageModuleIdentifier, sheetName, fieldName, options) .then(function(fieldName) { ... });
mySight.sheetApplyHierarchicalFilter
Applies the hierarchical filter for a sheet specified by its name.
Questback.portalsApi.mySight.sheetApplyHierarchicalFilter(pageModuleIdentifier, sheetName, fieldName, values, options) .then(function(fieldName) { ... });
mySight.sheetClearFilter
Clears the filter for a sheet specified by its name.
Questback.portalsApi.mySight.sheetClearFilter(pageModuleIdentifier, sheetName, fieldName) .then(function(fieldName) { ... });
Listening to MySight Tableau events
The api supports registering for a number of Tableau events. The supported events are:
FIRST_INTERACTIVE
VIZ_RESIZE
TAB_SWITCH
FILTER_CHANGE
PARAMETER_VALUE_CHANGE
MARKS_SELECTION
To register a listener for an event use the apis bus methods together with the apis tableau event constants:
Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventFirstInteractive, function(event) { console.log(event); }); Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventVizResize, function(event) { console.log(event); }); Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventFilterChange, function(event) { console.log(event); }); Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventTabSwitch, function(event) { console.log(event); }); Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventParameterValueChange, function(event) { console.log(event); }); Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventMarksSelection, function(event) { console.log(event); });
Note that you will receive events coming from any MySight Tableau instance on the page, so upon receiving an event you might have to make sure that you are only handling events coming from a specific instance by checking the pageModuleIdentifier in the event object.
Questback.portalsApi.bus.subscribe( Questback.portalsApi.mySight.tableauEventVizResize, function(event) { if (event.mysight.pageModuleIdentifier === 'page-module-identifier-to-handle') { // Do something } });