Server-side scripting

The triggering of a Server event sends its JavaScript code plus the XPage context to an interpreter on the Web server.

The server-side interpreter has these characteristics:
  • Has access to the JavaScript™ libraries for accessing the document store and performing other activities on the server. See "Introduction to the JavaScript and XPages Reference" in the HCL Domino® Designer XPages Reference.
  • Does not have access to the client Document Object Model for XML and HTML.
  • Is the only option for formulas and actions.
  • Has access to server script libraries only.
  • Rejects embedded Java™ statements in JavaScript™ only when executing restricted methods and operations if the XPages Signer is not granted permission to perform restricted operations (see Signing XPages).
  • Differs in some respects from the ECMAScript Language Specification Standard ECMA-262 (see http://www.ecma-international.org/publications/standards/Ecma-262.htm). For details about the differences, see "Introduction to the JavaScript and XPages Reference" in the HCL Domino® Designer XPages Reference.

Global objects and functions

Global objects and functions provide starting points for server-side scripting. This topic outlines a few useful global objects and functions. For complete documentation, see "Global Objects and Functions" in the HCL Domino® Designer XPages Reference.
  • requestScope, sessionScope, applicationScope, viewScope
    These objects allow you to define global variables, where the scope is the duration of one service request, one session (until the user logs out), the life of the application, or the life of the view page. Define the variable as a property of the object, for example, requestScope.x. Global variables can be bound to controls outside JavaScript™ by specifying a scope and a variable name for the data source. The provided example page has three edit boxes bound to requestScope variables named x, y, and z. The last edit box has an onclick event that uses the global variables to place the total of the first two boxes in the last box.
    <?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
    This object of type XSPContext (see the HCL Domino® Designer XPages Reference) represents the runtime context. A useful method is redirectToPage which sends a specified page to the client. This example shows two edit boxes and a button on page1 and an edit box on page2. The edit boxes are bound to sessionScope variables named x, y, and z. The user completes the edit boxes on page1 with numbers and clicks the button. The button onclick event presents the total on xpage2.
    <?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
    These are objects of type NotesSession (see the HCL Domino® Designer XPages Reference) and represent a connection to the document server. The session is restricted as follows:
    • session assigns credentials based on the user. The session is restricted by the application's ACL and the security tab of the server's Domino® Directory entry.
    • sessionAsSigner assigns credentials based on the signer of the of XPages design element. The session is restricted by the application's ACL and the security tab of the server's Domino® Directory entry.
    • sessionAsSignerWithFullAccess assigns credentials based on the signer of the of XPages design element and allows full administrative access to the application's data. The signer must have the right to such access or the session is not created.
    This page contains a computed field that displays the common name of the current user.
    <?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
    This is an object of type NotesDatabase (see the HCL Domino® Designer XPages Reference) that represents the data store for the current application. This page uses the database global variable in two controls. First a computed field displays the number of documents in the database. Second a button when clicked creates a document in the database. In testing you see the document count increment as you click the button.
    <?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
    The global variable currentDocument. is an object of type NotesDocument (see the HCL Domino® Designer XPages Reference) that represents the data source affected by the current control. You can also access a data source with its assigned name. The default names for document data sources are document1, document2, and so on. This page contains a button that uses the currentDocument global variable to save the content of the page to a document. In this case, document1 could be substituted for currentDocument.
    <?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
    This function takes the name of a UI control as a parameter and returns its object. The object has the methods getValue and setValue for accessing the values received from and sent to the client. This page has three edit boxes. The third edit box has an onclick event that concatenates the content of the first two edit boxes.
    <?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>

User interaction

Typically you interact with the user through the controls. Data is placed in input controls before the client sends a service request. The server can place data in controls for display on the client before sending the response. This page contains an edit box, a button, and a computed field. The button saves the content of the edit box to a document then writes a status message to the computed field.
<?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>

The window.alert function is not available to server scripts.

Use these functions to write to the console log:
  • print(string) writes a string.
  • _dump(object) writes a string representation of the object.
Access the console log as follows:
  • For browser-based activities, log entries are accessed at console.log on the server (for example, C:\Notes\Data\IBM_TECHNICAL_SUPPORT\console.log):.
  • For Notes® client-based activities, log entries are accessed by clicking Help > Support > View Trace.

This example demonstrates a function that highlights application output to the system log:

// Function for highlighting output to log
function printToLog(stuff) {
    _dump("\r\nPRINT START\r\n");
    _dump(stuff);
    _dump("\r\nPRINT END\r\n");
}
// Test call
printToLog("Here's some stuff for the log.");

Exception handling

A script can use try, catch, and finally clauses as in Java™. The catch clause executes if an exception occurs and the finally clause always executes. The button on this page uses the try ... catch mechanism to write errors to a computed field.

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

In this test case, an exception occurs because doc is not defined before being used.

If you do not catch an exception, results depend on the runtime environment. For example, the browser or Notes® client may display a page with a generic error message.

For validation checks, see message - Display Error and messages - Display Errors.

JavaScript™ server libraries

These JavaScript™ libraries (packages) are automatically available to server scripts:
Library Description
Domino (see the HCL Domino® Designer XPages Reference) Includes NotesSession, NotesDatabase, NotesDocument, and other classes to query and manipulate user data and the user server environment.
DOM (see the ®HCL Domino® Designer XPages Reference) Not currently used because the data store is not XML based.
Runtime (see the HCL Domino® Designer XPages Reference) Makes available various utility classes.
Standard (see the HCL Domino® Designer XPages Reference) Makes available various utility classes.
XSP (see the HCL Domino® Designer XPages Reference) Allows access to the execution context.
@Functions (see the HCL Domino® Designer XPages Reference) Functions that emulate Notes® @functions.