Serverseitige Scripterstellung

Das Auslösen eines Ereignisses vom Typ Server sendet den entsprechenden JavaScript-Code und den XPage-Kontext an einen Interpreter auf dem Web-Server.

Der serverseitige Interpreter zeichnet sich durch Folgendes aus:
  • Er hat Zugriff auf die JavaScript-Bibliotheken für den Zugriff auf den Dokumentspeicher und für die Ausführung von anderen Aktivitäten auf dem Server. Weitere Informationen finden Sie unter der Einführung in die JavaScript- und XPages-Referenz.
  • Er hat keinen Zugriff auf das clientseitige Dokumentobjektmodell (Document Object Model) für XML und HTML.
  • Er bietet die einzige Möglichkeit, Formeln und Aktionen zu verwenden.
  • Er hat nur Zugriff auf Server-Scriptbibliotheken.
  • Er weist eingebettete Java-Anweisungen in JavaScript bei der Ausführung eingeschränkter Methoden und Operationen nur zurück, wenn der XPages-Unterzeichner nicht berechtigt ist, eingeschränkte Operationen auszuführen (siehe XPages signieren).
  • Er unterscheidet sich in bestimmten Aspekten von dem ECMAScript-Sprachspezifikationsstandard ECMA-262. (Weitere Informationen hierzu finden Sie unter http://www.ecma-international.org/publications/standards/Ecma-262.htm.) Weitere Informationen zu den Unterschieden finden Sie in der Einführung in die JavaScript- und XPages-Referenz.

Globale Objekte und Funktionen

Globale Objekte und Funktionen stellen Ausgangspunkte für die serverseitige Scripterstellung dar. Im Folgenden sind einige hilfreiche globale Objekte und Funktionen kurz dargestellt. Eine vollständige Dokumentation finden Sie unter Globale Objekte und Funktionen.
  • requestScope, sessionScope, applicationScope, viewScope
    Mit diesen Objekten können Sie globale Variablen definieren. Dabei ist der Bereich die Dauer einer Serviceanforderung, die Dauer einer Sitzung (bis der Benutzer sich abmeldet), die Lebensdauer der Anwendung oder die Lebensdauer der Ansichtsseite. Definieren Sie diese Variable als eine Eigenschaft des Objekts, zum Beispiel requestScope.x. Globale Variablen können an Steuerelemente außerhalb von JavaScript gebunden werden. Dazu geben Sie einen Bereich und einen Variablennamen für die Datenquelle an. Die bereitgestellte Seite enthält drei Felder, die mit den requestScope-Variablen x, y und z verbunden sind. Das letzte Editierfeld weist ein onclick-Ereignis auf, das die globalen Variablen verwendet, um die Summe der beiden ersten Felder im letzten Feld anzuzeigen.
    <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:inputText id="inputText1" value="#{requestScope.x}">
	<xp:this.converter><xp:convertNumber type="number"></xp:convertNumber></xp:this.converter>
</xp:inputText><xp:span> x</xp:span><xp:br></xp:br>
<xp:inputText id="inputText2" value="#{requestScope.y}">
	<xp:this.converter><xp:convertNumber type="number"></xp:convertNumber></xp:this.converter>
</xp:inputText><xp:span></xp:span> y<xp:br></xp:br><xp:span></xp:span>
<xp:inputText id="inputText3" value="#{requestScope.z}">
	<xp:this.converter><xp:convertNumber type="number"></xp:convertNumber></xp:this.converter>
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action>
			<![CDATA[#{javascript:requestScope.z = requestScope.x + requestScope.y}]]>
		</xp:this.action>
	</xp:eventHandler></xp:inputText> x + y<xp:span></xp:span><xp:span></xp:span>
</xp:view>
  • context
    Dieses Objekt des Typs XSPContext stellt den Laufzeitkontext dar. redirectToPage ist eine nützliche Methode, mit der eine angegebene Seite an den Client gesendet wird. Das folgende Beispiel zeigt zwei Editierfelder und eine Schaltfläche auf page1 sowie ein Editierfeld auf page2 an. Die Editierfelder sind an die sessionScope-Variablen x, y und z gebunden. Der Benutzer füllt die Editierfelder auf page1 mit Zahlen aus und klickt auf die Schaltfläche. Mit dem onclick-Ereignis der Schaltfläche wird die Summe auf xpage2 angezeigt.
    <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:inputText id="inputText1" value="#{sessionScope.x}">
	<xp:this.converter><xp:convertNumber type="number"></xp:convertNumber></xp:this.converter>
</xp:inputText><xp:span> x</xp:span><xp:br></xp:br>
<xp:inputText id="inputText2" value="#{sessionScope.y}">
	<xp:this.converter><xp:convertNumber type="number"></xp:convertNumber></xp:this.converter>
</xp:inputText><xp:span></xp:span>	y	<xp:br></xp:br>
<xp:button id="button1" value="x + y">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action><![CDATA[#{javascript:sessionScope.z = sessionScope.x + sessionScope.y;
		context.redirectToPage("xpage2.xsp")}]]></xp:this.action>
	</xp:eventHandler>
</xp:button>
</xp:view>

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"><xp:span></xp:span>
<xp:inputText id="inputText3" value="#{sessionScope.z}">
	<xp:this.converter><xp:convertNumber type="number"></xp:convertNumber></xp:this.converter>
		</xp:inputText> x + y<xp:span></xp:span>
	<xp:span></xp:span>
</xp:view>
  • session, sessionAsSigner, sessionAsSignerWithFullAccess
    Dies sind Objekte des Typs NotesSession. Sie stellen eine Verbindung mit dem Dokumentserver dar. Die Sitzung ist wie folgt eingeschränkt:
    • Mit session werden Berechtigungsnachweise abhängig vom Benutzer zugeordnet. Die Sitzung wird durch die Zugriffssteuerungsliste der Anwendung und die Registerkarte "Sicherheit" des Servereintrags im Domino-Verzeichnis eingeschränkt.
    • Mit sessionAsSigner werden Berechtigungsnachweise abhängig vom Unterzeichner eines XPages-Gestaltungselements zugeordnet. Die Sitzung wird durch die Zugriffssteuerungsliste der Anwendung und die Registerkarte "Sicherheit" des Servereintrags im Domino-Verzeichnis eingeschränkt.
    • Mit sessionAsSignerWithFullAccess werden Berechtigungsnachweise abhängig vom Unterzeichner eines XPages-Gestaltungselements zugeordnet und es wird vollständiger Verwaltungszugriff auf die Anwendungsdaten gewährt. Der Unterzeichner muss zu diesem Zugriff berechtigt sein, andernfalls wird die Sitzung nicht erstellt.
    Diese Seite enthält ein berechnetes Feld, in dem der allgemeine Name des aktuellen Benutzers angezeigt wird. 
    <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
	<xp:text escape="true" id="computedField1" value="#{javascript:session.getCommonUserName()}">
	</xp:text>
</xp:view>
  • database
    Dies ist ein Objekt des Typs NotesDatabase. Es stellt den Datenspeicher für die aktuelle Anwendung dar. Auf dieser Seite wird die globale Variable database in zwei Steuerelementen verwendet. Das erste ist ein berechnetes Feld, in dem die Anzahl der Dokumente in der Datenbank angezeigt wird. Das zweite ist eine Schaltfläche, mit der beim Anklicken ein Dokument in der Datenbank erstellt wird. Bei einem Test können Sie sehen, dass die Anzahl der Dokumente bei jedem Anklicken der Schaltfläche zunimmt.
    <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:text escape="true" id="computedField1"
	value="#{javascript:database.getAllDocuments().getCount().toFixed()}">
</xp:text>	<xp:br></xp:br>
<xp:button id="button1" value="Create document">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action><![CDATA[#{javascript:var doc = database.createDocument();
		doc.appendItemValue("Subject", "my subject");
		doc.save()}]]></xp:this.action>
	</xp:eventHandler>
</xp:button>
</xp:view>
  • currentDocument, document1, document2
    Die globale Variable currentDocument. ist ein Objekt des Typs NotesDocument, das die Datenquelle darstellt, auf die sich das aktuelle Steuerelement auswirkt. Sie können auf eine Datenquelle auch mit dem ihr zugeordneten Namen zugreifen. Die Standardnamen für Dokumentdatenquellen sind document1, document2 usw. Diese Seite enthält eine Schaltfläche, die den Inhalt der Seite mithilfe der globalen Variablen currentDocument in einem Dokument speichert. In diesem Fall kann currentDocument beispielsweise durch document1 ersetzt werden.
    <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:this.data>
	<xp:dominoDocument var="document1" formName="form1"></xp:dominoDocument>
</xp:this.data>
<xp:table>
	<xp:tr>
		<xp:td><xp:label value="Subject:" id="subject_Label1" for="subject1"></xp:label></xp:td>
		<xp:td><xp:inputText value="#{document1.subject}" id="subject1"></xp:inputText></xp:td>
	</xp:tr>
</xp:table>
<xp:button id="button1" value="Create document">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action><![CDATA[#{javascript:currentDocument.save();
		context.redirectToPage("xpage2")}]]></xp:this.action>
	</xp:eventHandler>
</xp:button></xp:view>
  • getComponent
    Diese Funktion übernimmt den Namen eines UI-Steuerelements als Parameter und gibt dessen Objekt zurück. Das Objekt verfügt über die Methoden getValue und setValue für den Zugriff auf die Werte, die vom Client empfangen und an den Client gesendet werden. Diese Seite enthält drei Editierfelder. Das dritte Editierfeld weist ein onclick-Ereignis auf, das den Inhalt der beiden ersten Editierfelder verknüpft.
    <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:inputText id="inputText1"></xp:inputText><xp:br></xp:br>
<xp:inputText id="inputText2"></xp:inputText><xp:br></xp:br>
<xp:inputText id="inputText3">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action>
			<![CDATA[#{javascript:getComponent("inputText3").setValue(getComponent("inputText1").getValue() + getComponent("inputText2").getValue())}]]>
		</xp:this.action>
	</xp:eventHandler>
</xp:inputText>
</xp:view>

Benutzerinteraktion

Die Interaktion mit dem Benutzer erfolgt normalerweise über die Steuerelemente. In den Eingabesteuerelementen werden Daten eingefügt, bevor der Client eine Serviceanforderung sendet. Der Server kann Daten zur Anzeige auf dem Client in Steuerelemente einfügen, bevor die Antwort gesendet wird. Diese Seite enthält ein Editierfeld, eine Schaltfläche und ein berechnetes Feld. Mit der Schaltfläche wird der Inhalt des Editierfelds in einem Dokument gespeichert und anschließend wird eine Statusnachricht in das berechnete Feld geschrieben.
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:this.data>
	<xp:dominoDocument var="document1" formName="form1"></xp:dominoDocument>
</xp:this.data>
<xp:table>
	<xp:tr>
		<xp:td><xp:label value="Subject:" id="subject_Label1" for="subject1"></xp:label></xp:td>
		<xp:td><xp:inputText value="#{document1.subject}" id="subject1"></xp:inputText></xp:td>
	</xp:tr>
</xp:table>
<xp:button id="button1" value="Create document">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action><![CDATA[#{javascript:document1.save();
		requestScope.status = "Document created"}]]></xp:this.action>
	</xp:eventHandler>
</xp:button><xp:br></xp:br>
<xp:text escape="true" id="computedField1" value="#{requestScope.status}"></xp:text>
</xp:view>

Die Funktion window.alert ist für Server-Scripts nicht verfügbar.

Mithilfe der folgenden Funktionen können Sie Einträge in das Konsolenprotokoll schreiben:
  • print(string) schreibt eine Zeichenfolge.
  • _dump(object) schreibt eine Zeichenfolgedarstellung des Objekts.
Sie können wie folgt auf das Konsolprotokoll zugreifen:
  • Bei browserbasierten Aktivitäten können Sie über console.log auf dem Server auf Protokolleinträge zugreifen (z. B. C:\Notes\Data\IBM_TECHNICAL_SUPPORT\console.log).
  • Bei Notes-Client-basierten Aktivitäten können Sie auf Protokolleinträge zugreifen, indem Sie auf Hilfe > Unterstützung > Trace anzeigen klicken.

Dieses Beispiel veranschaulicht eine Funktion, die die Anwendungsausgabe im Systemprotokoll hervorhebt:

// Funktion für das Hervorheben der Ausgabe im Protokoll
function printToLog(stuff) {
    _dump("\r\nPRINT START\r\n");
    _dump(stuff);
    _dump("\r\nPRINT END\r\n");
}
// Testaufruf
printToLog("Hier sind einige Informationen für das Protokoll.");

Ausnahmebehandlung

Ein Script kann try-, catch- und finally-Klauseln wie in Java verwenden. Die catch-Klausel wird ausgeführt, wenn eine Ausnahme eintritt. Die finally-Klausel wird immer ausgeführt. Die Schaltfläche auf dieser Seite schreibt mithilfe des Mechanismus try ... catch Fehler in ein berechnetes Feld.

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:button id="button2" value="Create document">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action><![CDATA[#{javascript:try {
			doc.appendItemValue("Subject", "my subject");
		} catch(e) {
			requestScope.status = "Error: " + e;
		}}]]></xp:this.action>
	</xp:eventHandler>
</xp:button><xp:br></xp:br>
<xp:text escape="true" id="computedField1" value="#{requestScope.status}"></xp:text>
</xp:view>

Bei diesem Anwendungsbeispiel tritt eine Ausnahme ein, da doc vor der Verwendung nicht definiert wird.

Wenn keine Ausnahme eintritt, sind die Ergebnisse von der Laufzeitumgebung abhängig. Beispielsweise wird im Browser oder auf dem Notes-Client eine Seite mit einer generischen Fehlernachricht angezeigt.

Informationen zu Gültigkeitsprüfungen finden Sie unter message - Fehler anzeigen und messages - Fehler anzeigen.

JavaScript-Serverbibliotheken

Diese JavaScript-Bibliotheken (Pakete) sind für Server-Scripts automatisch verfügbar:
Bibliothek Beschreibung
Domino Enthält NotesSession, NotesDatabase, NotesDocument und andere Klassen zum Abfragen und Bearbeiten von Benutzerdaten und der Serverumgebung des Benutzers.
DOM Derzeit nicht verwendet, da der Datenspeicher nicht XML-basiert ist
Runtime Stellt verschiedene Utility-Klassen zur Verfügung.
Standard Stellt verschiedene Utility-Klassen zur Verfügung.
XSP Bietet Zugriff auf den Ausführungskontext.
@Functions Funktionen, die Notes-@Functions emulieren.
Übergeordnetes Thema: Scripts in XPages erstellen

Zusätzliche Dokumentation | Marken |