CIB doXiview - Integration

Site: CIB eLearning
Course: CIB doXiview
Book: CIB doXiview - Integration
Printed by: Guest user
Date: Saturday, 20 August 2022, 12:43 AM

Über dieses Dokument

Dieses Dokument ist an Entwickler gerichtet, welche CIB doXiview als Komponente in ihre eigene Webapplikation integrieren.

In einfachen Anwendungsfällen kann CIB doXiview durch Referenzierung per URL ohne Einsatz von JavaScript integriert werden.

In weiterführenden Anwendungsfällen kann die integrierende Anwendung mit CIB doXiview kommunizieren. Diese Kommunikation erfolgt mithilfe von JavaScript-Funktionen unter Verwendung des Frameworks CIB iwc (Abkürzung für inter-window communication).

Die Verwendung dieser Schnittstelle ist Inhalt dieses Dokuments.

Für das Verständnis werden Grundlagenkenntnisse über HTML und JavaScript vorausgesetzt.


Beispielanwendungen und Testoberfläche

Die in diesem Dokument beschriebenen Funktionen lassen sich auch praktisch an Beispielen nachvollziehen. In der CIB doXiview Demoversion sind Beispiele von sehr einfachen HTML-Seiten enthalten, welche als minimale integrierende Beispielanwendungen dienen.

Zusätzlich ist in der Demoversion die Webapplikation CIB doXiview Test UI enthalten, mit welcher verschiedene Parameter komfortabel in einer Benutzeroberfläche eingegeben werden können. Sie können hier die Wirkung verschiedener Parameter zunächst testen, ohne dafür selbst Code schreiben zu müssen. Die generelle Verwendung dieser Testoberfläche ist in der Dokumentation KurzanleitungCibDoXiviewDemo.pdf beschrieben, welche zusammen mit der Demoversion ausgeliefert wird.

Hinweis: Erläuterungen in diesem Dokument, welche an Code-Beispielen oder der Testoberfläche nachvollzogen werden können, sind mit diesem Symbol gekennzeichnet.

Möglichkeiten der Clientseitigen Integration von CIB doxiView

Es gibt prinzipiell 3 Möglichkeiten, wie CIB doXiview in einem Web-Browser geöffnet werden kann:

  1. Aufruf von CIB doXiview durch Eingabe einer URL in die Adresszeile des Web-Browsers
  2. Integration von CIB doXiview in eine andere Webapplikation über eine URL
  3. Integration von CIB doXiview in eine andere Webapplikation über eine URL und CIB iwc

Diese Möglichkeiten werden im Folgenden kurz skizziert.

Aufruf von CIB doXiview durch Eingabe einer URL in der Adress-Zeile des Web-Browsers
Aufruf von CIB doXiview über eine URL aus einer anderen Webapplikation
Integration von CIB doXiview über CIB iwc


Aufruf von CIB doXiview durch Eingabe einer URL in der Adress-Zeile des Web-Browsers

CIB doXiview ist eine Webapplikation, welche im einfachsten Fall direkt über die Eingabe einer geeigneten URL in der Browser-Adresszeile geladen und angezeigt werden kann. In diesem Fall gibt der Benutzer direkt als Teil der URL ein, welches Dokument von CIB doXiview unmittelbar angezeigt wird. Die Anzeige nimmt anschließend vollständig einen Browser-Tab ein.

Beispiele:

  1. Aufruf von CIB doXiview und Anzeige eines spezifizierten Dokuments
    Durch Eingabe der folgenden URL in der Adresszeile des Browsers wird CIB doXiview geöffnet und zeigt das Dokument example.pdf an:
    http://myserver/webview/?rsp=false&iwc_mode=standalone&urlField=http://myotherserver/example.pdf&ext=pdf
  2. Aufruf von CIB doXiview ohne Dokument mit einem Upload-Button
    Durch Eingabe der nächsten URL in der Adresszeile des Browsers wird CIB doXiview zunächst ohne ein Dokument geöffnet. Der Benutzer kann anschließend per Schaltfläche in der CIB doXiview Toolbar ein Dokument aus dem lokalen Dateisystem auswählen und in CIB doXiview hochladen und anzeigen.
    http://myserver/webview/?rsp=false&uistyle=cib&iwc_mode=standalone&ui=upload


Starten Sie die Demoversion von CIB doXiview und geben die folgende URL im Web-Browser ein:

http://localhost:8080/webview/?rsp=false&iwc_mode=standalone&ui=upload


Aufruf von CIB doXiview über eine URL aus einer anderen Webapplikation

In den meisten Fällen soll CIB doXiview jedoch aus folgenden Gründen in eine andere Webapplikation, d.h. eine andere HTML-Seite, eingebettet werden:

  1. Die einbettende Webapplikation bestimmt über Aufrufparameter, welches Dokument CIB doXiview anzeigen soll.
  2. Die CIB doXiview-Oberfläche soll optisch in der Seite der einbettenden Webapplikation integriert werden, d.h. in einem <iframe> HTML-Tag. Die weiter oben genannten Beispiel-URLs können in dem Fall unverändert als Wert für das src-Attribut eingesetzt werden.

Die folgende Datei simple-iframe.html aus der CIB doXiview Demoversion integriert CIB doXiview mittels <iframe>-Tag. Diese kann dort aufgerufen werden wie folgt:

http://localhost:8080/doxiview-examples/simple-iframe.html


Alternativ könnte mit einem Anchor Tag <a> und dem href-Attribut CIB doXiview in einem neuen Browser-Tab geöffnet werden.

Die Datei beispiele.html aus der CIB doXiview Demoversion enthält einen Link auf CIB doXiview als <a>-Tag.

Die einbettende Webapplikation kann CIB doXiview auf diese Weise parametrisiert aufrufen, hat allerdings ab diesem Zeitpunkt keine Möglichkeit mehr, mit CIB doXiview innerhalb des Webbrowsers zu kommunizieren.


Integration von CIB doXiview über CIB iwc

Für die folgenden Anwendungsfälle wird eine engere Kopplung zwischen der einbettenden Webapplikation und CIB doXiview benötigt:

  • Integration von eigenen Schaltflächen in die Toolbar von CIB doXiview und anschließende Reaktion, wenn der Benutzer diese anklickt
  • Anzeigen von eigenen Hinweistexten an den Benutzer
  • Sperren und Entsperren der Benutzeroberfläche von CIB doXiview
  • Drucken in Originalqualität über einen Dienst außerhalb des Webbrowsers
  • Anbindung von CIB doXiview an ein Archivsystem
  • Editieren von Freitextbereichen in RTF-Dokumenten
  • Ausfüllen von Unterschriftenfeldern

In diesen Fällen wird CIB doXiview nicht nur initial von der einbettenden Webanwendung aufgerufen, sondern kommuniziert auch anschließend mit ihr.

Zunächst wird wie im vorherigen Abschnitt Aufruf von CIB doXiview über eine URL aus einer anderen Webapplikation
beschrieben, CIB doXiview wieder mit einem <iframe> HTML-Tag in  die einbettende Anwendung integriert. Die Verwendung eines <iframe> wird bei dieser Integrationsart nun zwingend vorausgesetzt.

Im Unterschied zu Aufruf von CIB doXiview über eine URL aus einer anderen Webapplikation
wird hier als URL des iframe src-Attributes nur eine Basis-URL auf CIB doXiview angegeben:

<iframe src="http://myserver/webview/index.jsp?iwc_mode=internal"/>

Diese Basis-URL enthält nur den Parameter

iwc_mode=internal

Damit wird CIB doXiview signalisiert, dass weitere Parameter auf anderem Wege, nämlich mittels JavaScript-Funktionen übermittelt werden.

Das folgende Kapitel Kommunikation über CIB iwc erläutert die Integration über CIB iwc im Detail.


Kommunikation über CIB iwc



CIB iwc

CIB iwc (Abkürzung für inter-window communication) ist ein in JavaScript implementiertes Kommunikationsframework, welches es zwei Webanwendungen erlaubt, Clientseitig innerhalb des Web-Browsers miteinander zu kommunizieren.

Das Framework sorgt dafür, dass beide Anwendungen auch dann miteinander kommunizieren dürfen, wenn sie aus unterschiedlichen Domains stammen. Dies wird normalerweise aus Sicherheitsgründen von Web-Browsern unterbunden (Same Origin Policy). Im Umfeld großer Unternehmen ist es jedoch üblich, dass Anwendungen aus verschiedenen Domains stammen, etwa a.mycompany.com und b.mycompany.com.

CIB iwc basiert im Kern auf der HTML5-Funktion window.postMessage und wird in Form von JavaScript-Dateien von den beteiligten Anwendungen geladen.

Während zwei Anwendungen bei der direkten Verwendung von window.postMessage lediglich Strings austauschen können, ermöglicht CIB iwc eine Kommunikation auf höherer Ebene mittels JavaScript-Funktionsaufrufen.


Master und Slave

Damit zwei Webapplikationen über das CIB iwc Framework kommunizieren können, muss die eine Anwendung per HTML iframe-Tag in die andere Anwendung eingebettet werden.

Die einbettende Anwendung wird in diesem Zusammenhang Master oder Integrator genannt, die eingebettete Anwendung wird Slave genannt. Typischerweise erscheint aus Benutzersicht der Slave als Rechteck innerhalb des Masters. Der Master entscheidet darüber, wann und wie der Slave geladen wird.

Wenn CIB doXiview in Ihre Anwendung eingebettet wird, dann ist Ihre Anwendung in dieser Beziehung der Master und CIB doXiview ist der Slave.

Die folgende Abbildung veranschaulicht das:


Laden der CIB iwc JavaScript Ressourcen

Damit eine Kommunikation zwischen Master und Slave aufgebaut werden kann, müssen beide Webanwendungen als Voraussetzung zunächst das in Form von JavaScript Code vorliegende CIB iwc Frameworks laden.

Beispielsweise kann der CIB iwc Code von Ihrer Webseite aus der CIB doXiview Anwendung geladen werden wie folgt:


Prinzipiell ist dieser Ort beliebig. Sie können diese JavaScript-Ressource deshalb auch in Ihrer eigenen Anwendung als Kopie vorhalten und in Ihrem HTML Code mit einem relativen Pfad einbinden:


Wenn das CIB iwc Framework von vielen Anwendungen benutzt wird,  kann mehrfaches Laden der gleichen JavaScript-Datei in den Browser vermieden werden, wenn diese anwendungsübergreifend mit derselben URL referenziert wird:


Der Webbrowser hat so die Möglichkeit, diese Ressource zu cachen. CIB doXiview kann entsprechend konfiguriert werden, um CIB iwc ebenfalls von diesem zentralen Ort zu laden.

Im einfachsten Fall braucht nur das CIB iwc Framework selbst in Form der Datei cib.iwc.1.0.0.min.js geladen werden. Diese enthält für alle Anwendungen allgemein verwendbare Funktionen, beispielsweise zur Übergabe von Startparametern.

Zusätzlich werden anwendungsspezifische Funktionen in separaten JavaScript-Dateien bereitgestellt, welche auf dieselbe Weise eingebunden werden. Für die Kommunikation mit CIB doXiview ist dies die Datei iwc-interfaces-min.js.

Schließlich verwendet CIB iwc intern die JavaScript Bibliothek jQuery, welche deshalb ebenfalls von allen Kommunikationspartnern eingebunden werden muss.

Insgesamt werden also die folgenden drei JavaScript-Ressourcen für die Kommunikation Ihrer Anwendung mit CIB doXiview benötigt:


Soll eine Vielzahl von Anwendungen über CIB iwc kommunizieren, lässt sich das Laden der JavaScript-Ressourcen optimieren. Dies wird in Kapitel Optimierung zum laden der JavaScript-Ressourcen separat beschrieben.

Aufbau der Kommunikation Über CIB iwc

Nachdem der Master den CIB iwc JavaScript Code geladen hat, kann er den Slave laden und die Kommunikation zu diesem aufbauen. Anschließend sind Master und Slave in der Lage, mittels Funktionsaufrufen zu kommunizieren.

Der Aufbau der Kommunikation findet in folgenden Schritten statt:

  1. CIB iwc laden: Laden der benötigten JavaScript-Ressourcen durch den Master
  2. Initialisierung: Der Master initialisiert CIB iwc
  3. Registrierung der Master-Funktionen: Der Master registriert in CIB iwc seine Funktionen, welche später vom Slave aus aufrufbar sein sollen
  4. Laden des Slave: Der Master lädt über CIB iwc den Slave in dem gewünschten iframe mittels Aufruf der iwc-Funktion openUrlInFrame(iframe-id, url)
  5. Registrierung Slave: Der JavaScript Code des geladenen Slave wird vom Browser ausgeführt und registriert in CIB iwc seine vom Master aufrufbaren Funktionen
  6. Handshake zwischen Master und Slave: Der Slave ruft die Methode init(initCallback) an dem Master auf.
  7. Benachrichtigung Slave über Handshake-Ergebnis: Wenn der Master die Initialisierung erfolgreich beendet hat, wird die success-Methode aus dem initCallback des Slaves aufgerufen. Wenn die Initialisierung nicht erfolgreich war, wird die failure-Methode aufgerufen.

Nach einem erfolgreichen Handshake ist die Kommunikation etabliert:

  • Der Slave kann die vom Master bereitgestellten Funktionen aufrufen.
  • Der Master kann die vom Slave bereitgestellten Funktionen aufrufen.

Für die Integration von CIB doXiview müssen Sie in Ihrer Master-Anwendung die Schritte 1. bis 4. implementieren. Dies wird im folgenden Abschnitt am Beispiel erläutert.

Die Schritte 5. bis 7. werden komplett von CIB iwc und CIB doXiview durchgeführt.

Beispiel: Laden von CIB doXiview und Übergabe der Startparameter via CIB iwc

Der im vorherigen Punkt beschriebene Ablauf soll an einem Minimalbeispiel anschaulich dargestellt werden. Dazu erzeugen wir eine integrierende Anwendung, die CIB doXiview in einem iframe öffnet und die Startparameter via CIB iwc übermittelt.

Der Beispielcode besteht aus den folgenden Abschnitten:

  1. CIB iwc laden
  2. Initialisierung
  3. Registrieren der Master-Funktionen
  4. Laden des Slave

Hinweis: Der folgende Beispielcode ist auch in der Demoversion von CIB doXiview enthalten und lässt sich dort aufrufen mit:

http://localhost:8080/doxiview-examples/example-javascript-integration.html





Hinweis: Das Öffnen von CIB doXiview und die Übergabe der Startparameter kann bequem mit der Testoberfläche nachvollzogen werden. Gehen Sie dazu wie folgt vor:

  1. Öffnen Sie die Testoberfläche im Browser durch Eingabe der URL http://localhost:8080/showcase und wechseln Sie zum Tab „Konfiguration“
    Die Testoberfläche dient als CIB iwc Master für CIB doXiview
  2. Auswahl der gewünschten Startparameter, welche an CIB doXiview übergeben werden sollen
  3. Klick auf die Schaltfläche Open
    (Öffnet CIB doXiview in einem iframe)

In der Browserkonsole können die übergebenen Startparameter identifiziert werden.

Startparameter iwc_mode

In unserem Beispiel wurde CIB doXiview wie folgt aufgerufen:


Als Ausnahme von der Regel, dass alle Startparameter mittels CIB iwc übertragen werden, ist hier ein einzelner Startparameter nach wie vor innerhalb der CIB doXiview URL definiert: iwc_mode=internal. Dieser Startparameter ist als Teil der URL vorgesehen, um CIB doXiview mitzuteilen, ob überhaupt eine Kommunikation mit einem Master etabliert werden soll.
Die folgenden Werte für diesen Startparameter sind möglich:

Wert für iwc_mode

Beschreibung

standalone

CIB doXiview wird keine Kommunikation über CIB iwc mit einem Master etablieren.
Alle Startparameter werden als Teil der Aufruf-URL erwartet.

Als Beispiel siehe Kapitel Aufruf von CIB doXiview durch Eingabe einer URL in der Adress-Zeile des Web-Browsers

internal

CIB doXiview etabliert eine Kommunikation mit CIB iwc zu einem Master. Alle weiteren Startparameter werden über CIB iwc vom Master abgeholt.

Als Beispiel siehe Kapitel Aufbau der Kommunikation Über CIB iwc

external

Falls neben CIB iwc bereits ein weiteres JavaScript-Kommunikationsframework in Ihrer Anwendungslandschaft im Einsatz ist, kann CIB iwc damit zusammenarbeiten.

Dieser Fall geht über den Rahmen dieser Dokumentation hinaus. Bitte setzen Sie sich gegebenenfalls mit ihrem technischen Ansprechpartner bei CIB in Verbindung.

Keine Angabe

Falls der Parameter gar nicht angegeben wird, verwendet CIB doXiview einen der drei anderen Werte, entsprechend dem konfigurierten Standardverhalten. Dieses wird mittels der Property iwc.mode.default in der Datei default-config.properties bzw. environment-config.properties festgelegt.
Die Voreinstellung lautet:

iwc.mode.default=INTERNAL

Alternativ sind die Werte EXTERNAL oder STANDALONE möglich.


Master und Slave Interfaces

Die zur Kommunikation mit CIB doXiview zur Verfügung stehenden JavaScript-Funktionen sind nach Anwendungsfällen in mehrere Schnittstellen gruppiert.

Beispielsweise wurde im Abschnitt Aufbau der Kommunikation Über CIB iwc die Schnittstelle common verwendet, um die Startparameter zu übergeben:


Die folgende Tabelle gibt einen Überblick über die verwendbaren Schnittstellen:

Kommunikationsschnittstelle

Anwendungsfall

common

Enthält allgemeine Funktionen, die von mehreren Web-Applikationen verwendet bzw. bereitgestellt werden

webview

Enthält allgemeine Funktionen von CIB doXiview.

archive

Enthält Funktionen von CIB doXiview im Archivmodus, d.h. wenn Dokumente aus einem Archivsystem geladen werden.

print

Enthält Funktionen im Zusammenhang mit dem Ausdruck eines in CIB doXiview angezeigten Dokuments in Originalqualität über einen Gerätedienst auf dem Arbeitsplatzrechner.

toolbar

Enthält Funktionen für den Umgang mit der in CIB doXiview angezeigten Werkzeugleiste.

sign

Enthält Funktionen für das Hinzufügen von elektronischen Unterschriften in CIB doXiview.

 

Jede dieser Schnittstellen enthält zwei Arten von Funktionen:

Funktionen zum Registrieren Ihrer Master-Funktionen, welche von CIB doXiview aufgerufen werden können

Funktionen von CIB doXiview, welche von Ihrer Master-Anwendung aufgerufen werden können

In Kapitel die Kommunikationsschnittstellen werden alle Kommunikationsinterfaces mit den darin definierten Methoden im Detail beschrieben.

Die Result Callback-Struktur

Funktionen aus den Kommunikationsschnittstellen können entweder einen definierten Rückgabewert oder keinen Rückgabewert haben.

Wird eine Funktion aufgerufen, die keinen Rückgabewert definiert, bekommt die aufrufende Anwendung nach dem Aufruf keinerlei Rückmeldung mehr in irgendeiner Form.

Wenn dagegen eine Funktion mit einem Rückgabewert definiert ist, muss der Aufrufer seinerseits zwei Funktionen namens success und failure definieren, welche im Erfolgsfall und im Fehlerfall mit einem jeweils passenden Rückgabewert aufgerufen werden. Diese beiden Funktionen werden zu einem Objekt zusammengefasst übergeben, welches im folgenden Result Callback genannt wird. Das Result Callback lässt sich am einfachsten als JavaScript Objekt-Literal definieren wie folgt:


Der im Fehlerfall an failure übergebene Parameter error ist stets wie folgt aufgebaut:


Die Struktur des im Erfolgsfall an success übergebenen Parameters params hängt jeweils von der aufgerufenen Funktion ab und ist der Dokumentation der Funktion zu entnehmen.

Beispielsweise liefert die Funktion getViewStateInfo der Kommunikationsschnittstelle doXiview im Erfolgsfall laut Dokumentation die folgende Struktur als Parameter params:

{
    currentBundleDocumentID: the current bundle document id,
    currentDocumentID: the current document id,
    currentDocumentPageCount: the page count for the current document,
    currentPageNumber: the current page number
}

Das folgende Code-Beispiel fasst zusammen, wie Sie mit dieser Funktion in Ihrer Master-Anwendung die Nummer der aktuell in CIB doXiview angezeigten Dokumentseite und die Anzahl der Seiten abfragen können:


Die obige Funktion displayPageNumber() könnte z.B. vom Benutzer Ihrer Anwendung durch einen wie folgt definierten Button ausgelöst werden:


Die Kommunikationsschnittstellen



Erklärung zur SchnittstellenBeschreibung

Die Verwendung einer Funktion zur Kommunikation setzt voraus, dass

  • der eine Kommunikationsteilnehmer die Funktion für den anderen bereitstellt, und
  • der andere Kommunikationsteilnehmer die Funktion aufruft.

Um die jeweilige Seite der Kommunikation deutlich zu machen, besteht eine Namenskonvention.

Der Bereitsteller einer Funktion namens someFunction ruft zu diesem Zweck eine Funktion auf, die per Konvention registerSomeFunctionCallback genannt wird.

Der Aufrufer kann diese Funktion anschließend aufrufen, per Konvention unter dem Namen someFunction.

Die Benennung dieser Funktionen hängt also nicht von der generellen Rolle einer Anwendung als Master oder Slave ab, sondern von der Richtung der Kommunikation bezogen auf eine einzelne Funktion.

Beispiel: Es gibt eine Funktion, welche CIB doXiview in Richtung seines Masters aufruft, um Startparameter zu erhalten.

Da in diesem Fall der Master die Funktion bereitzustellen hat, ruft er zu diesem Zweck die in seiner Schnittstelle CibMasterCommonFunctions  definierte Funktion mit Namen registerStartParametersCallback auf. Als Parameter übergibt er die vom Slave aufrufbare Funktion:

var getStartParameters = function(…
registerStartParameterCallback(getStartParameters)

Als Aufrufer dieser Funktion ist der Slave vorgesehen. Er ruft dazu die in seiner Schnittstelle CibSlaveCommonFunctions vorhandene Funktion getStartParameters auf:

var resultCallback = { success: function…
getStartParameters(resultCallback)


In den Funktionsbeschreibungen in diesem Kapitel ist im untersten Abschnitt Registration definiert, ob entweder der Master oder der Slave die definierte Funktion registrieren muss. Die jeweils andere Seite kann die Funktion mit dem Namen aufrufen, welcher links oben unter Function genannt ist.

Jede Funktionsbeschreibung ist aus Sicht der aufrufenden Seite formuliert.

Ihre Anwendung, in welche CIB doXiview integriert wird, ist immer der Master.

Function

Parameters

Return

getStartParameters

callback: ResultCallback

JSON

Returns CIB doXiview start parameters required for viewing a document in CIB doXiview. The result will be returned through the success-method of the specified result callback.

Return:

A JSON representation of start parameters which has the following structure:

var startParameters = {
          context : {login context},
          webview : {
               // doxiview specific start parameters
},         webedit : {
// webEdit specific start parameters
} }

Registration by master:

master.common.registerStartParameterCallback(callback: FunctionCallback);

 

Beispiel-Implementierung aus Sicht Master (integrierende Anwendung):

master.common.registerStartParameterCallback(function() {
var startParameters = {
                "webview": {
                         "uistyle":"cib",                          "ui":"upload",                 }
        };
        return startParameters;
});

Das common Interface

Allgemein
getStartParameters
terminate
fireDataDirty
lock, unlock
logout
resize
showMessage


Allgemein

Das Kommunikations-Interface common definiert generelle Funktionen, welche nicht CIB doXiview-spezifisch sind, sondern auch in anderen per CIB iwc integrierbaren Anwendungen zum Einsatz kommen können.

Es ist aus Sicht des Masters in Form des Objekts CibCommonMasterFunctions verfügbar.

Dieses wird wie folgt erzeugt:



getStartParameters

Diese Funktion wurde bereits als Beispiel erläutert. Mittels dieser Funktion erfragt CIB doXiview von seinem Integrator die zu verwenden Startparameter.

Function

Parameters

Return

getStartParameters

callback: ResultCallback

JSON

Returns CIB doXiview start parameters required for viewing a document in CIB doXiview. The result will be returned through the success-method of the specified result callback.

Return:

A JSON representation of start parameters which has the following structure:

var startParameters = {
          context : {login context},
          webview : {
               // doXiview specific start parameters
},         webedit : {
// webEdit specific start parameters
} }

Registration by Master:

master.common.registerStartParameterCallback(callback: FunctionCallback);

 

Beispiel-Implementierung aus Sicht Master (integrierende Anwendung):

master.common.registerStartParameterCallback(function() {
        var startParameters = {
               "webview": {
                       "uistyle":"cib",                        "ui":"upload",                }
        };
        return startParameters;
});


Hinweis: In der CIB doXiview Testoberfläche können verschiedene voreingestellte Startparameter-Belegungen aus einer Liste ausgewählt werden.

Zudem können mit den Schaltflächen „Add Entry“ und „Add Text Entry“ weitere Startparameter einzeln gesetzt werden:



terminate

Wenn CIB doXiview beendet werden soll, kann es notwendig sein, dass abschließend Daten über die beendete Sitzung an den Master übermittelt werden oder dieser auf das Beenden der Dokumentbetrachtung reagieren soll. Dazu ruft CIB doXiview die Funktion terminate auf.

Function

Parameters

Return

terminate
code: int
data: JSON
errorDescription: String
void

This method must be called when the application finishes/closes. Once this method has been called, the application status will be set to CLOSED and subsequent calls to functions will fail.

Parameter description:

  • int: code:
    The terminate code.
  • JSON: data:
    Any data to pass back, e.g. viewer settings.
  • String: errorDescription:
    A description of the error if an error occurred.

Registration by Master:

master.common.registerTerminateCallback(callback: FunctionCallback);


fireDataDirty

In CIB doXiview können Änderungen vorliegen, die der Benutzer noch nicht gespeichert hat. Beispiele hierfür sind noch nicht gespeicherte Annotationen oder ein geändertes RTF-Freitextfeld. Damit der Master darauf reagieren kann, ruft CIB doXiview die Funktion fireDataDirty auf.

Function

Parameters

Return

fireDataDirty

isDataDirty: boolean
message: String
messageId: int

void

Informs the integrator that there are unsaved changes in CIB doXiview which can for instance be unsaved changes within the editor component after the user edited a RTF-Snippet.

Parameter description:

  • boolean: isDataDirty:
    Whether or not there are unsaved changes in CIB doXiview.
  • String: message:
    The message which will be presented to the user if the integrator application is tried to be closed without saving.
  • int: messageId:
    The id of the message so that it can be overridden if necessary by the integrator

Registration by master:

master.common.registerFireDataDirtyCallback(callback: FunctionCallback);

lock, unlock

Es kann erforderlich sein, die gesamte CIB doXiview Benutzeroberfläche zu sperren um sie gegen unbefugte Eingaben zu schützen. Beispielsweise durch eine explizite Sperranforderung des Benutzers oder wenn der Benutzer längere Zeit inaktiv war. Ein späteres Entsperren der Oberfläche ist ebenfalls möglich. Beides wird durch den Master veranlasst.

Function

Parameters

Return

lock

N/A

void

Tells the client application to lock itself.

Registration by slave:

slave.common.registerLockCallback(callback: FunctionCallback);

 

Function

Parameters

Return

unlock

N/A

void

Tells the client application to unlock itself.

Registration by slave:

slave.common.registerUnlockCallback(callback: FunctionCallback);


logout

Wird in der Master-Anwendung ein Logout des Benutzers durchgeführt, sollte CIB doXiview darüber informiert werden, z. B. um einen eventuell geöffneten Freitext-Editor schließen.

Slave Interface:

Function

Parameters

Return

logout

N/A

void

Tells the client application to logout.

Registration by slave:

slave.common.registerLogoutCallback(callback:FunctionCallback);


resize

In CIB doXiview ist es möglich, die Größe der Anwendung anzupassen. Dies wird durch einen Aufruf der Funktion resize realisiert.

Slave Interface:

Function

Parameters

Return

resize

width: int
height: int

void

Lets CIB doXiview resize to the specified size in pixel.


Parameter description:

  • int: width:
    The new width of the application.
  • int: height:
    The new height of the application.

Registration by slave:

slave.common.registerResizeCallback(callback: FunctionCallback);


showMessage

Der Master kann die Funktion showMessage aufrufen, um in CIB doXiview Nachrichten für den Benutzer anzuzeigen. Diese werden über dem Dokument eingeblendet und nach einer gewissen Zeit automatisch ausgeblendet.

Function

Parameters

Return

showMessage

messageText: String

void

Lets CIB doXiview display the specified message text.

Parameter description:

  • String: messageText:
    The message to show.

Registration by slave:

slave.common.registerShowMessageCallback(callback: FunctionCallback);


Das webview Interface

Allgemein
finishLoading
getViewStateInfo
finishEditing
setSnippetEditingAllowed
cancelEditing
showNotification
onDocumentVersionUpdated
applicationStarted
openDocument


Allgemein

Das Interface webview definiert allgemeine Funktionen zur Kommunikation mit CIB doXiview. Zudem sind hier Funktionen enthalten, welche beim Editieren von RTF verwendet werden.

Es ist aus Sicht des Masters in Form des Objekts CibWebviewMasterFunctions verfügbar.


finishLoading

CIB doXiview informiert den Master durch Aufruf der Funktion finishLoading, wenn der Ladevorgang eines Dokuments abgeschlossen wurde. Daraufhin kann der Master weitere Aktionen auslösen, z. B. zum Freischalten von eigenen Toolbar-Schaltflächen.

Function

Parameters

Return

finishLoading

successful: boolean

void

Notifies the integrator of CIB doXiview that the document has finished loading.

Parameter description:

boolean: successful:

Whether or not the document was successfully loaded.

Registration by Master:

master.webview.registerFinishLoadingCallback(callback:
  FunctionCallback);

 

Beispiel-Implementierung aus Sicht des Masters:

master.webview.registerFinishLoadingCallback (function(params) {
      // work with “params.successful” which can be true or false
      // returning something is not needed since return type is “void”
});


Hinweis: In der Testoberfläche kann die Benachrichtigung durch CIB doXiview über  finishLoading beobachtet werden: Sobald CIB doXiview ein  Dokument geladen hat, reagiert die Testoberfläche darauf, indem sie den Aufruf in der Konsole ausgibt.



getViewStateInfo

Der Master kann durch Aufruf von getViewStateInfo CIB doXiview nach dem aktuellen Zustand der Anzeige befragen, beispielsweise welche Seite momentan ausgewählt ist.

Function

Parameters

Return

getViewStateInfo

callback: JSON

JSON

Asks CIB doXiview for the current view state, which can be for instance used during communication with CIB webprint.

Parameter description:

JSON: callback:

The callback object which will receive the result.

Return:

A JSON representation of the current view state, which has the following structure:

{
          currentBundleDocumentID: the current bundle document id,
          currentDocumentID: the current document id,
          currentDocumentPageCount: the page count for the current document,
          currentPageNumber: the current page number
  }

Registration by Slave:

slave.webview.registerGetViewStateInfoCallback(callback:FunctionCallback)

 

Beispiel-Implementierung aus Sicht des Masters:

master.webview.getViewStateInfo ({   
    success: function(params) {       
        // work with params.currentBundleDocumentID       
        // work with params.currentDocumentID           
        // work with params.currentDocumentPageCount             
        // work with params.currentPageNumber         
    },   
    failure: function(error) {       
        // log error or something            
    }
});


Hinweis: In der Testoberfläche kann dieser Aufruf mit der Schaltfläche „RuntimeManipulation/Third Party Functions/Get View State“ ausgelöst werden. Das Ergebnis des Aufrufs wird in der Konsole der Testoberfläche ausgegeben.


finishEditing

Diese Funktion spielt lediglich für den Anwendungsfall „Editieren von Freitextpassagen in einem RTF-Dokument“ mittels CIB webEdit eine Rolle.

CIB doXiview kann seinen Master darüber informieren, ob ein Editiervorgang erfolgreich abgeschlossen wurde. Zu diesem Zweck wird die sogenannte editSessionId an den Master kommuniziert, sowie eine Liste elementList der modifizierten Freitextbereiche. Falls kein Text verändert wurde, ist diese Liste leer.

Der Master kann daraufhin beispielsweise die editierten Freitextbereiche weiterverarbeiten. Für weitergehende Informationen hierzu kontaktieren Sie bitte Ihren Ansprechpartner bei CIB.

Function

Parameters

Return

finishEditing

editSessionId: String
elementList: Array

void

Informs the integrator of CIB doXiview that the user has finished editing the specified editable elements.

Parameter description:

  • String: editSessionId:
    The id of the current edit session.
  • Array: elementList:
    The list of modified elements which has the following structure:
    • {
           containerId: a containerId with modified elements,
           elementNames[]: a list of modified element names
        }[]

Registration by Master:

master.webview.registerFinishEditingCallback(callback:FunctionCallback)


Hinweis: In der Testoberfläche kann in der Konsolenausgabe die Benachrichtigung durch CIB doXiview über finishEditing einfach nachvollzogen werden:

  1. Öffnen Sie CIB doXiview in dem Modus webEdit
  2. Editieren Sie eine Freitextpassage
  3. Beenden Sie das Editieren durch Speichern oder Abbrechen