Page Comparison

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:

Table of Contents

maxLevel	2

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.

Code Block

language	js

<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.

Code Block

language	js

<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.

Code Block

language	js

Questback.portalsApi.isInitialized();

Unregister

You can completely revert the registration of the iFrame and unregister all its handlers by calling unregister.

Code Block
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.

Code Block

language	js

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.

Code Block

language	js

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.

Code Block
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.

Code Block

language	js

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.

Code Block

language	js

Questback.portalsApi.query.user().then(function(result) {
    console.log(result.user);
});

query.language

Get the language object of the currently used language.

Code Block

language	js

Questback.portalsApi.query.language().then(function(result) {
    console.log(result.language);
});

query.deviceInfo

Get information about the client device.

Code Block

language	js

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.

Code Block

language	js

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.

Code Block

language	js

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.

Code Block

language	js

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.

Code Block

language	js

Questback.portalsApi.trigger.logout();

trigger.route

Redirect to the given page slug. The iFrame will be removed from the DOM by this opreation.

Code Block

language	js

Questback.portalsApi.trigger.route('targetPageSlug');

Accessing MySight instances in Portals

Image Removed

Image Added

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.

Code Block

language	js

Questback.portalsApi.mySight.vizGetIsReady(pageModuleIdentifier)
    .then(function(ready) {
        ...
    });

mySight.vizGetAreTabsHidden

Gets whether the tabs are hidden or not.

Code Block

language	js

Questback.portalsApi.mySight.vizGetAreTabsHidden(pageModuleIdentifier)
    .then(function(hidden) {
        ...
    });

mySight.vizGetIsToolbarHidden

Gets whether the tabs are hidden or not.

Code Block

language	js

Questback.portalsApi.mySight.vizGetIsToolbarHidden(pageModuleIdentifier)
    .then(function(hidden) {
        ...
    });

mySight.vizGetUrl

Gets the url of the viz.

Code Block

language	js

Questback.portalsApi.mySight.vizGetUrl(pageModuleIdentifier)
    .then(function(url) {
        ...
    });

mySight.vizGetCurrentUrl

Gets the current url of the viz.

Code Block

language	js

Questback.portalsApi.mySight.vizGetCurrentUrl(pageModuleIdentifier)
    .then(function(currentUrl) {
        ...
    });

mySight.vizGetIsHidden

Gets whether the viz is hidden or not.

Code Block

language	js

Questback.portalsApi.mySight.vizGetIsHidden(pageModuleIdentifier)
    .then(function(hidden) {
        ...
    });

mySight.vizShow

Shows the viz.

Code Block

language	js

Questback.portalsApi.mySight.vizShow(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizHide

Hides the viz.

Code Block

language	js

Questback.portalsApi.mySight.vizHide(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizDispose

Disposes the viz.

Code Block

language	js

Questback.portalsApi.mySight.vizDispose(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizGetAreAutomaticUpdatesPaused

Gets the status of automatic updates.

Code Block

language	js

Questback.portalsApi.mySight.vizGetAreAutomaticUpdatesPaused(pageModuleIdentifier)
    .then(function(paused) {
        ...
    });

mySight.vizPauseAutomaticUpdates

Pauses automatic updates.

Code Block

language	js

Questback.portalsApi.mySight.vizPauseAutomaticUpdates(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizResumeAutomaticUpdates

Resumes automatic updates.

Code Block

language	js

Questback.portalsApi.mySight.vizResumeAutomaticUpdates(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizToggleAutomaticUpdates

Toggles automatic updates.

Code Block

language	js

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.

Code Block

language	js

Questback.portalsApi.mySight.vizRevertAll(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizRefreshData

Refreshes data from the server.

Code Block

language	js

Questback.portalsApi.mySight.vizRefreshData(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizShowDownloadWorkbookDialog

Shows the download workbook dialog.

Code Block

language	js

Questback.portalsApi.mySight.vizShowDownloadWorkbookDialog(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizShowExportImageDialog

Shows the export image dialog.

Code Block

language	js

Questback.portalsApi.mySight.vizShowExportImageDialog(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizShowExportPDFDialog

Shows the export PDF dialog.

Code Block

language	js

Questback.portalsApi.mySight.vizShowExportPDFDialog(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.vizShowExportDataDialog

Shows the export data dialog for the current or a specific sheet.

Code Block

language	js

Questback.portalsApi.mySight.vizShowExportDataDialog(pageModuleIdentifier, sheetName)
    .then(function() {
        ...
    });

mySight.vizShowExportCrossTabDialog

Shows the export cross tab dialog for the current or a specific sheet.

Code Block

language	js

Questback.portalsApi.mySight.vizShowExportCrossTabDialog(pageModuleIdentifier, sheetName)
    .then(function() {
        ...
    });

mySight.vizShowShareDialog

Shows the share dialog for the current or a specific sheet.

Code Block

language	js

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.

Code Block

language	js

Questback.portalsApi.mySight.vizSetFrameSize(pageModuleIdentifier, width, height)
    .then(function() {
        ...
    });

mySight.workbookGetName

Gets the name of the workbook.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetName(pageModuleIdentifier)
    .then(function(name) {
        ...
    });

mySight.workbookGetSheetsInfo

Gets information about all sheets.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetSheetsInfo(pageModuleIdentifier)
    .then(function(sheetsInfo) {
        ...
    });

mySight.workbookGetActiveSheetName

Gets the name of the active sheet.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetActiveSheetName(pageModuleIdentifier)
    .then(function(name) {
        ...
    });

mySight.workbookGetActiveSheetIndex

Gets the index of the active sheet.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetActiveSheetIndex(pageModuleIdentifier)
    .then(function(index) {
        ...
    });

mySight.workbookActivateSheet

Actives a sheet by its name or index.

Code Block

language	js

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.

Code Block

language	js

Questback.portalsApi.mySight.workbookRevertAll(pageModuleIdentifier)
    .then(function() {
        ...
    });

mySight.workbookGetParameterNames

Gets a list of the parameter names.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetParameterNames(pageModuleIdentifier)
    .then(function(names) {
        ...
    });

mySight.workbookGetParameterCurrentValue

Gets the current value of a parameter.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetParameterCurrentValue(pageModuleIdentifier, parameterName)
    .then(function() {
        ...
    });

mySight.workbookGetParameterDataType

Gets the data type of a parameter.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetParameterDataType(pageModuleIdentifier, parameterName)
    .then(function(dataType) {
        ...
    });

mySight.workbookGetParameterAllowableValuesType

Gets the type of allowable values of a parameter.

Code Block

language	js

Questback.portalsApi.mySight.workbookGetParameterAllowableValuesType(pageModuleIdentifier, parameterName)
    .then(function(allowableValuesType) {
        ...
    });

mySight.workbookGetParameterAllowableValues

Gets a list of allowable values of a parameter.

Code Block
Questback.portalsApi.mySight.workbookGetParameterAllowableValues(pageModuleIdentifier, parameterName) .then(function(allowableValues) { ... });

mySight.workbookGetParameterMinValue

Gets the min value of a parameter.

Code Block
Questback.portalsApi.mySight.workbookGetParameterMinValue(pageModuleIdentifier, parameterName) .then(function(minValue) { ... });

mySight.workbookGetParameterMaxValue

Gets the max value of a parameter.

Code Block
Questback.portalsApi.mySight.workbookGetParameterMaxValue(pageModuleIdentifier, parameterName) .then(function(maxValue) { ... });

mySight.workbookGetParameterStepSize

Gets the step size of a parameter.

Code Block
Questback.portalsApi.mySight.workbookGetParameterStepSize(pageModuleIdentifier, parameterName) .then(function(stepSize) { ... });

mySight.workbookGetParameterDateStepPeriod

Gets the date step period of a parameter.

Code Block
Questback.portalsApi.mySight.workbookGetParameterDateStepPeriod(pageModuleIdentifier, parameterName) .then(function(dateStepPeriod) { ... });

mySight.workbookChangeParameterValue

Sets a parameter to a given value.

Code Block

language	js

Questback.portalsApi.mySight.workbookChangeParameterValue(pageModuleIdentifier, parameterName, value)
    .then(function(newValue) {
        ...
    });

mySight.sheetGetName

Gets the name of a sheet by its index.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetName(pageModuleIdentifier)
    .then(function(name) {
        ...
    });

mySight.sheetGetIndex

Gets the index of a sheet by its name.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetIndex(pageModuleIdentifier)
    .then(function(index) {
        ...
    });

mySight.sheetGetIsActive

Gets whether a sheet is active or not.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetIsActive(pageModuleIdentifier, sheetNameOrIndex)
    .then(function(active) {
        ...
    });

mySight.sheetGetIsHidden

Gets whether a sheet is hidden or not.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetIsHidden(pageModuleIdentifier, sheetNameOrIndex)
    .then(function(hidden) {
        ...
    });

mySight.sheetGetType

Gets the type of the currently active or a specific sheet.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetType(pageModuleIdentifier, sheetNameOrIndex)
    .then(function(type) {
        ...
    });

mySight.sheetGetUrl

Gets the url of the currently active or a specific sheet.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetUrl(pageModuleIdentifier, sheetNameOrIndex)
    .then(function(url) {
        ...
    });

mySight.sheetGetSize

Gets the size of the currently active or a specific sheet.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetSize(pageModuleIdentifier, sheetNameOrIndex)
    .then(function(size) {
        ...
    });

mySight.sheetChangeSize

Sets the size of the active sheet.

Code Block

language	js

Questback.portalsApi.mySight.sheetChangeSize(pageModuleIdentifier, sheetSizeOptions)
    .then(function() {
        ...
    });

mySight.sheetGetFilters

Gets the filters of a sheet specified by its name.

Code Block

language	js

Questback.portalsApi.mySight.sheetGetFilters(pageModuleIdentifier, sheetName)
    .then(function(filters) {
        ...
    });

mySight.sheetApplyFilter

Applies the filter for a sheet specified by its name.

Code Block

language	js

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.

Code Block

language	js

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.

Code Block

language	js

Questback.portalsApi.mySight.sheetApplyRelativeDateFilter(pageModuleIdentifier, sheetName, fieldName, options)
    .then(function(fieldName) {
        ...
    });

mySight.sheetApplyHierarchicalFilter

Applies the hierarchical filter for a sheet specified by its name.

Code Block

language	js

Questback.portalsApi.mySight.sheetApplyHierarchicalFilter(pageModuleIdentifier, sheetName, fieldName, values, options)
    .then(function(fieldName) {
        ...
    });

mySight.sheetClearFilter

Clears the filter for a sheet specified by its name.

Code Block

language	js

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:

Code Block

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.

Code Block

language	js

Questback.portalsApi.bus.subscribe(
  Questback.portalsApi.mySight.tableauEventVizResize, function(event) {
    if (event.mysight.pageModuleIdentifier === 'page-module-identifier-to-handle') {
        // Do something
    }
});

Page Comparison

Versions Compared

Old Version 4

New Version 5

Key

Including Portals API in your application

Import

Initialization

Checking initialization status

Unregister

Using the Portals message bus

Listening for messages

Sending messages

Stop listening for messages

Querying data from Portals

query.portalInfo

query.user

query.language

query.deviceInfo

query.ajax (reserved for future use)

Trigger actions in Portals

trigger.height

trigger.autoHeight

trigger.logout

trigger.route

Accessing MySight instances in Portals

mySight.vizGetIsReady

mySight.vizGetAreTabsHidden

mySight.vizGetIsToolbarHidden

mySight.vizGetUrl

mySight.vizGetCurrentUrl

mySight.vizGetIsHidden

mySight.vizShow

mySight.vizHide

mySight.vizDispose

mySight.vizGetAreAutomaticUpdatesPaused

mySight.vizPauseAutomaticUpdates

mySight.vizResumeAutomaticUpdates

mySight.vizToggleAutomaticUpdates

mySight.vizRevertAll

mySight.vizRefreshData

mySight.vizShowDownloadWorkbookDialog

mySight.vizShowExportImageDialog

mySight.vizShowExportPDFDialog

mySight.vizShowExportDataDialog

mySight.vizShowExportCrossTabDialog

mySight.vizShowShareDialog

mySight.vizSetFrameSize

mySight.workbookGetName

mySight.workbookGetSheetsInfo

mySight.workbookGetActiveSheetName

mySight.workbookGetActiveSheetIndex

mySight.workbookActivateSheet

mySight.workbookRevertAll

mySight.workbookGetParameterNames

mySight.workbookGetParameterCurrentValue

mySight.workbookGetParameterDataType

mySight.workbookGetParameterAllowableValuesType

mySight.workbookGetParameterAllowableValues

mySight.workbookGetParameterMinValue

mySight.workbookGetParameterMaxValue

mySight.workbookGetParameterStepSize

mySight.workbookGetParameterDateStepPeriod

mySight.workbookChangeParameterValue

mySight.sheetGetName

mySight.sheetGetIndex

mySight.sheetGetIsActive

mySight.sheetGetIsHidden

mySight.sheetGetType

mySight.sheetGetUrl

mySight.sheetGetSize

mySight.sheetChangeSize

mySight.sheetGetFilters

mySight.sheetApplyFilter

mySight.sheetApplyRangeFilter

mySight.sheetApplyRelativeDateFilter

mySight.sheetApplyHierarchicalFilter

mySight.sheetClearFilter

Listening to MySight Tableau events