Client-side scripting

The triggering of a Client event sends its JavaScript™ code plus the XPage context to an interpreter on the user's client.

A client-side interpreter has the following characteristics:
  • Has access to the client Document Object Model for XML and HTML.
  • Does not have access to server JavaScript™ libraries for accessing the document store and performing other activities.
  • Cannot be used for formulas.
  • Has access to client script libraries only.
  • Uses the standard JavaScript™ found in the user's client.

Getting server information

You can pass information from the server to the client by embedding a formula in XSP format in the client-side script. The syntax for JavaScript™ is as follows:
#{javascript:statements}
The following example shows a client-side script attached to the onclick event of a button. Before loading this script to the client, the time executes the embedded server-side script so that the common user name appears as a string constant in the client-side alert method.
window.alert("#{javascript:session.getCommonUserName()}")

Getting the identifier of a DOM element

The run time assigns identifiers to DOM elements based on the names of the design controls. For example, the run time identifier for inputText1 might be view:_id1:inputText1. The identifer is not predictable so should not be specified as a literal.
You can pass the identifier to the client by embedding the following syntax in the client-side script:
#{id:control_name}
For example, the following code is the client-side onchange event for an edit box named inputText1:
var e = window.document.getElementById("#{id:inputText1}");
e.value = e.value.toUpperCase()

Getting event information

You can use the identifier thisEvent to acquire the Event object for the event in which the client code is running. This gives you access to the standard Event properties.
The following client-side onclick event for an edit box gets the element identifier for the current control through the target property of thisEvent. When the user clicks in the edit box, the string "enter valid name" is placed there if the edit box is empty.
var e = window.document.getElementById(thisEvent.target.id);
if (e.value == "") {
	e.value = "enter valid name"
}

Attaching two scripts to an event

You can attach a client-side and server-side script to the same event:
  • The client-side script executes first before the service request for the event goes to the server.
  • The server-side script executes next upon receipt of the service request, unless the client-side script returns false. A return value of false cancels the service request.

Alternatively you can attach simple actions or simple action groups. You can attach a script to one side (client or server) of the event and a simple action or simple action group to the other side. You can attach multiple scripts to an event by using the Execute Script or Execute Client Script simple action in a simple action group. See Simple actions.

Suppose a button onclick event has two events. The client-side script shown below queries the user with a dialog containing OK and Cancel buttons. If the user clicks OK, the server-side script executes; if the user clicks Cancel, the server-side script does not execute.
if(window.confirm("Do you want to continue?") != true)
	return false

Triggering a client script from a server script

The UI view root, accessible through the view global object, has a method postScript that executes a script after the server responds to the client. Suppose a button onclick event has a server event with two simple actions. The first simple action is Save Document while the second simple action is Execute Script with the script specified as follows:
view.postScript("alert('document saved')")

When the user clicks the button, the server-side event saves the XPage data to a document then responds to the client at which time the alert dialog appears.

Detecting errors

Client-side errors are not reported at design time. The editor might highlight code that is incorrect, but the Problems view does not report the error and the deployment process does not report the error. At run time erroneous code may be reported but may fail silently.
For example, the following client-side script for a button onclick event contains a simple syntax error. Yet the script deploys with no error reported. At run time nothing happens when you click the button, and other script on the page may not work properly.
window.alert("hello client world)

To detect client-side errors, turn on the browser's error, JavaScript™, or Java™ console. This typically brings up another window that reports errors. For example, in Mozilla Firefox, click Tools > Error ConsoleFor the example case, the window that opens displays unterminated string literal.