Erweiterung

Einbindung der Portals API in Ihre Anwendung

Open

Das Seitenmodul Erweiterung ermöglicht die Integration Ihrer Anwendung in Portals, indem es einen iFrame für Ihre Inhalte und eine API für die Kommunikation mit Portals bereitstellt. Das Modul akzeptiert eine URL und ermöglicht die Übergabe dynamischer GET-Parameter an Ihre Anwendung über diese URL. Eine Portal kann mehrere Erweiterungsmodule auf einer einzigen Seite haben und alle Module können über den bereitgestellten Nachrichtenbus in der Portal-API miteinander kommunizieren. Für einen erweiterten Datenaustausch mit EFS empfehlen wir Ihnen, dass Ihre Anwendung den EFS ServiceLayer im Backend verwendet, um Daten in EFS abzufragen und zu aktualisieren.

Einbindung

In Ihrer Anwendung müssen Sie die PortalsAPI JavaScript-Datei einbinden, um den Nachrichtenbus oder andere Funktionen der Portals-API nutzen zu können.

Initialisierung

Nachdem Ihr Dokument fertig geladen ist, müssen Sie die API initialisieren. Dadurch wird Ihr Dokument in Portals für das Messaging registriert.

Überprüfung des Initialisierungsstatus

Sie können den Initialisierungsstatus durch den Aufruf von isInitialized überprüfen, es wird jedoch generell empfohlen, Ihre API-Operationen im then-Handler der Initialisierungsmethode wie oben gezeigt durchzuführen.

API deinitialisieren

Sie können die Initialisierung des iFrame vollständig rückgängig machen und alle seine Handler durch Aufruf von unregister abmelden.

Verwendung des Portals Nachrichtenbusses

Der Nachrichtenbus ist für die Kommunikation zwischen den Erweiterungsmodulen vorgesehen. Sie können Ihre eigenen Events senden und empfangen und beliebige Daten übertragen.

Auf Nachrichten hören

Nach Abschluss der Initialisierung können Sie mit der Registrierung von Handlern für Events aus anderen iFrames beginnen. Der Beispielcode registriert einen Handler für ein Event namens "myEvent". Dies ist ein Eventname, der von anderen iFrames versendet wird.

Nachrichten senden

Das Senden einer Nachricht an andere iFrames ist genauso einfach. Sie rufen die send-Methode einfach mit einem von Ihnen gewählten Eventnamen und einem Datenobjekt als zweiten Parameter auf.

Beachten Sie nur, dass Sie von diesem Aufruf keinen Rückgabewert erhalten, da er wie ein Broadcast funktioniert. Beachten Sie auch, dass der sendende iFrame standardmäßig kein eigenes Ereignis zurück erhält, auch wenn er einen Handler dafür registriert hat. Sie können einen dritten Parameter zum Senden mit dem Wert true angeben, um das Senden des Ereignisses an den Sender iFrame zu erzwingen.

Abmelden von Nachrichtenevents

Sie können den Handler für Events eines bestimmten Eventnamens auch wieder entfernen.

Beachten Sie, dass dadurch alle Handler für den angegebenen Eventnamen für diesen iFrame auf einmal entfernt werden.

Abfrage von Daten aus Portals

Die API liefert eine Reihe von Methoden, um bestimmte Daten von Portals abzufragen.

query.portalInfo

Informationen über das Portal abrufen.

query.user

Liefert das Benutzerobjekt des aktuell angemeldeten Benutzers. Liefert null, wenn kein angemeldeter Benutzer vorhanden ist.

query.language

Liefert das Sprachobjekt der aktuell verwendeten Sprache.

query.token

Returns the Portals Api token, which can be used in external software to additionally validate the user via EFS web service.

If the user is logged in, the token field will contain the users api token, which you can validate by calling the following EFS web service. Otherwise, token will be an empty string.

If the token is valid the userId and portalId is returned. Otherwise an exception is thrown. Please refer to the web services documentation for more details on this service call.

query.deviceInfo

Informationen über das Client-Gerät abrufen.

query.ajax (reserved for future use)

Führt einen Ajax-Aufruf an die interne Portalserver-API durch und gibt das Ergebnis zurück. Da Portals selbst aktuell keine öffentliche Portalserver-API zur Verfügung stellt, ist diese Funktion für die zukünftige Verwendung reserviert.

Aktionen in Portals auslösen

Die API liefert eine Reihe von Methoden, um bestimmte Aktionen in Portals auszulösen.

trigger.height

Setzt die iFrame-Höhe auf einen bestimmten Wert, der als Zeichenkette inklusive der Einheit angegeben wird.

trigger.autoHeight

Setzt die Höhe des iFrames auf die Höhe seines Inhalts. Dies geschieht einmal pro Anruf, nicht wiederholt. Sie müssen also die Funktion aktiv ausführen, um die Größe der Ereignisse später nochmal zu ändern.

trigger.logout

Melden Sie den aktuellen Benutzer von Portals ab und leiten Sie ihn auf die konfigurierte Zielseite weiter. Der iFrame wird durch diese Operation aus dem DOM entfernt.

trigger.route

Umleiten auf den angegebenen Page Slug. Der iFrame wird durch diese Operation aus dem DOM entfernt.

Auf MySight-Instanzen in Portals zugreifen

Open

Es gibt eine Reihe von Methoden zur Interaktion mit Tableau in einem MySight-Seitenmodul. Für die Funktionen benötigen Sie den pageModuleIdentifier eines MySight-Seitenmoduls. Diese Kennung wird im Portals CMS in den Einstellungen für das MySight-Seitenmodul hinterlegt und kann auf anderen Seiten für gleiche oder verschiedene Tableau-Instanzen wiederverwendet werden.

mySight.vizGetIsReady

Ruft ab, ob das Ereignis onFirstInteractive bereits ausgelöst wurde.

mySight.vizGetAreTabsHidden

Ruft ab, ob die Registerkarten ausgeblendet sind oder nicht.

mySight.vizGetIsToolbarHidden

Ruft ab, ob die Toolbar ausgeblendet ist oder nicht.

mySight.vizGetUrl

Liefert die URL des Viz.

mySight.vizGetCurrentUrl

Liefert die URL des aktuellen Viz.

mySight.vizGetIsHidden

Gibt zurück ob das Viz versteckt wird oder nicht

mySight.vizShow

Zeigt Viz

mySight.vizHide

Versteckt viz

mySight.vizDispose

Disposes the viz.

mySight.vizGetAreAutomaticUpdatesPaused

Ruft den Status der automatischen Updates ab.

mySight.vizPauseAutomaticUpdates

Pausiert die automatischen Updates.

mySight.vizResumeAutomaticUpdates

Setzt die automatischen Updates fort.

mySight.vizToggleAutomaticUpdates

Schaltet die automatischen Updates um.

mySight.vizRevertAll

Stellt den Ausgangszustand wieder her. Beachten Sie, dass bei diesem Vorgang die URL-Parameter ignoriert werden und somit der wiederhergestellte Zustand vom tatsächlichen Ausgangszustand abweichen kann.

mySight.vizRefreshData

Aktualisiert Daten vom Server.

mySight.vizShowDownloadWorkbookDialog

Zeigt den Dialog zum Herunterladen der Arbeitsmappe an.

mySight.vizShowExportImageDialog

Zeigt den Dialog zum Exportieren von Bildern an.

mySight.vizShowExportPDFDialog

Zeigt den Dialog zum Exportieren von PDF-Dateien an.

mySight.vizShowExportDataDialog

Zeigt den Dialog Exportdaten für das aktuelle oder ein bestimmtes Blatt an.

mySight.vizShowExportCrossTabDialog

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

mySight.vizShowShareDialog

Zeigt den Share-Dialog für das aktuelle oder ein bestimmtes Blatt an.

mySight.vizSetFrameSize

Legt die Rahmengröße der Vizs fest. Beachten Sie, dass die Mindestbreite von Portalen auf 100% gesetzt werden kann und Vorrang vor jeder hier eingestellten Breite hat.

mySight.workbookGetName

Ruft den Namen der Arbeitsmappe ab.

mySight.workbookGetSheetsInfo

Ruft Informationen über alle Blätter ab.

mySight.workbookGetActiveSheetName

Ruft den Namen des aktiven Blattes ab.

mySight.workbookGetActiveSheetIndex

Ruft den Index des aktiven Blattes ab.

mySight.workbookActivateSheet

Aktiviert ein Blatt über seinen Namen oder Index.

mySight.workbookRevertAll

Stellt den Ausgangszustand der Arbeitsmappe wieder her. Beachten Sie, dass bei diesem Vorgang die URL-Parameter ignoriert werden und somit der wiederhergestellte Zustand vom tatsächlichen Ausgangszustand abweichen kann.

mySight.workbookGetParameterNames

Ruft eine Liste der Parameternamen ab.

mySight.workbookGetParameterCurrentValue

Ruft den aktuellen Wert eines Parameters ab.

mySight.workbookGetParameterDataType

Ruft den Datentyp eines Parameters ab.

mySight.workbookGetParameterAllowableValuesType

Ruft die Art der zulässigen Werte eines Parameters ab.

mySight.workbookGetParameterAllowableValues

Ruft eine Liste der zulässigen Werte eines Parameters ab.

mySight.workbookGetParameterMinValue

Ruft den Min-Wert eines Parameters ab.

mySight.workbookGetParameterMaxValue

Ruft den Maximalwert eines Parameters ab.

mySight.workbookGetParameterStepSize

Ruft die Schrittweite eines Parameters ab.

mySight.workbookGetParameterDateStepPeriod

Ruft die Datumsschrittweite eines Parameters ab.

mySight.workbookChangeParameterValue

Setzt einen Parameter auf einen bestimmten Wert.

mySight.sheetGetName

Ruft den Namen eines Blattes über seinen Index ab.

mySight.sheetGetIndex

Ruft den Index eines Blattes über seinen Namen ab.

mySight.sheetGetIsActive

Ruft ab, ob ein Blatt aktiv ist oder nicht.

mySight.sheetGetIsHidden

Ruft ab, ob ein Blatt ausgeblendet ist oder nicht.

mySight.sheetGetType

Ruft den Typ des aktuell aktiven oder eines bestimmten Blattes ab.

mySight.sheetGetUrl

Ruft die URL des aktuell aktiven oder eines bestimmten Blattes ab.

mySight.sheetGetSize

Ruft die Größe des aktuell aktiven oder eines bestimmten Blattes ab.

mySight.sheetChangeSize

Legt die Größe des aktiven Blattes fest.

mySight.sheetGetFilters

Ruft die Filter eines Blattes ab

mySight.sheetApplyFilter

Wendet den Filter für ein Blatt an

mySight.sheetApplyRangeFilter

Wendet den Bereichsfilter für ein Blatt an

mySight.sheetApplyRelativeDateFilter

Applies the relative date filter for a sheet specified by its name.

mySight.sheetApplyHierarchicalFilter

Wendet den hierarchischen Filter für ein Blatt an

mySight.sheetClearFilter

Löscht den Filter für ein Blatt

Auf MySight Tableau-Events hören

Die API unterstützt die Registrierung auf eine Reihe von Tableau-Events. Die unterstützten Events sind:

• FIRST_INTERACTIVE

• VIZ_RESIZE

• TAB_SWITCH

• FILTER_CHANGE

• PARAMETER_VALUE_CHANGE

• MARKS_SELECTION

Um einen Listener für ein Event zu registrieren, verwenden Sie die Apis-Bus-Methoden zusammen mit den Tableau Eventkonstanten:

Beachten Sie, dass Sie Events von allen MySight Tableau-Instanzen auf der Seite erhalten, so dass Sie nach dem Empfangen eines Events sicherstellen müssen, dass Sie nur Events von einer bestimmten Instanz verarbeiten. Verwenden Sie dazu eine Überprüfung des pageModuleIdentifier im Event Objekt.

Use Portals styles

You can use Portals CSS styles by importing its stylesheets into your iframe. The following examples will guide you through the setup process.

Retrieve file paths

First you need to get the paths of the stylesheet files and font definitions:

The result parameter will contain the necessary information in its layout field:

These paths do not change for a given portal (besides the value of the cachebuster parameter called v), so it is possible to retrieve them once, store them and hardcode them into your code, to save postMessage requests and improve startup times a little.

Importing the extension stylesheet

After retrieving the stylesheet urls you need to import the files by adding link tags into your documents head:

You should note that it takes some time to retrieve the file from the server, so there is a short time in which your application is rendered without the styles in the file. You might want to prevent your application from beeing shown to the user before the above code has been executed.

The extension.css is a subset of the portals stylesheet and contains the necessary styles for the most common use cases. If you want to include the complete portals stylesheet you can import result.layout.portalsCss instead of result.layout.extensionCss. But be aware that this might introduce conflicts with existing styles in your application.

Importing the custom stylesheet

If you have added custom css in the Look & Feel section of the CMS, that contains styles which you want to apply to you application, then you should import the custom.css file, too.

Importing the portals default font

To use the same font as your portal use the following code:

Using the styles

The extension.css contains classes for the most common use cases.

Color variables

Type color classes

Classes exist for the most common type and property combinations:

Profile background classes

The profile background classes exist, too:

Other classes

Buttons

You can style your buttons by using the portals button classes:

The button size can be set by adding one of the following classes:

The type can be set by adding one the following classes:

To enable hover effects, add the following class:

To display a button as disabled, add the following class:

If the button has the "disabled" attribute, the styles of "btn--disabled" are applied automatically.

Input fields

You can use styles for input fields as well. Write your markup as follows:

Please pay attention to the order of the elements and their classes. The oninput event handler is required to add or remove the input-filled class according to the inputs value. If your input receives an initial value you have to add the input-filled class manually.

Selectboxes

You can use native html selectboxes and they will be styled as close as possible to the original portals selectboxes. As those are generated by JavaScript, an exact replication is not possible.

As native html selectboxes always have a value selected, the input-filled class is always set on the select element.

Opening a dialog in Portals

The portalsApi has four methods that give you the ability to open a dialog outside of the scope of your iframe.

Dialog buttons

The methods openDialog and openIframeDialog open a dialog with a single "Close" button. The corresponding methods openConfirmDialog and openIframeConfirmDialog open a dialog with a "Cancel" and an "Ok" button.

Text dialogs

The methods openDialog and openConfirmDialog take a string as first parameter, which is the text shown in the main area of the dialog. The title is optional.

Iframe dialogs

The methods openIframeDialog and openIframeConfirmDialog render an iframe in the main area of the dialog with the url given at the first parameter. The title, height and heightUnit are optional. The paramters height and heightUnit define the height of the iframe in the dialog.

Simple call

The simplest way to open a dialog is by calling one of the dialog methods, give a text/url and not worry about any events:

Handle dialog close

The dialog can either be closed or canceled/accepted and this event can be handled by implementing Promise methods, like this:

The confirm dialogs make use of the then and catch methods:

The catch method does not indicate that an error happened, it just tells you about the way the dialog was closed. Both methods do not get any parameters. This means that no data from the dialogs iframe is transported back to the calling iframe.

If you want to transport data between the iframes or trigger actions in the other iframe make use of the PortalsApi's message bus functionality, documented under Using the Portals message bus.