Understanding events

Events are actions that a user might perform such as clicking a button or removing focus from an edit box. Event handlers are actions that you (the designer) perform in response to events.

An event handler is part of a control or part of the XPage.

An event handler can be a script, a simple action, or a simple action group. For one event, handlers can be specified to run on the client, the server, or both. A client handler can stop further client handler execution and cancel execution of a server handler by returning false.

If you are working in Design mode, put focus on the appropriate control or the page, click the Events tab, and select the desired event. You can then specify the event handler.

Events are treated as properties and appear on All Properties under Properties. However best practice is to not create or modify an event from All Properties. Use the Events tab or the source XML.

Server event handlers

The general format for a server event handler is as follows in Source mode. If you are working in Design mode, select the Events tab and then the Server tab.
<xp:eventHandler event="name" submit="true|false"
	refreshMode="complete|partial|norefresh" refreshId="id"
	immediate="true|false"	execMode="partial|full">
	<xp:this.action>
		<![CDATA[#{javascript:textOfScript}]]> <!-- script -->
		<xp:actionName arguments</xp:actionName> <!-- or simple action -->
		<xp:actionGroup condition="#{javascript:textOfScript}"> <!-- or simple action group -->
			actions and embedded groups
		</xp:actionGroup>
	</xp:this.action>
	<xp:this.parameters>
		<xp:this.parameter name="name" value"value"</xp:this.parameter> ...
	</xp:this.parameters>
</xp:eventHandler>
Where:
  • event specifies the name of the event, for example, onblur or onclick. If you are working on the Events tab, select the appropriate event.
  • submit="true" causes a request to be sent to the server when the user activates the event. Any other value for submit deactivates the event. If you are working on the Events tab, click No Submission to remove the event.
  • refreshMode is one of the following:
    • complete reloads the entire page to the client after the server processes the request. If you are working on the Events tab, click Full Update.
    • partial reloads a selected part of the page using Asynchronous JavaScript™ and XML (AJAX) technology. If you are working on the Events tab, click Partial Update.
    • norefresh does not reload the page. If you are working on the Events tab, click No Update.
  • refreshId applies only for refreshMode="partial" and specifies the control to be updated. If you are working on the Events tab, click Select Element.
  • immediate="true" suppresses data validation on the server. For data processing, omit this attribute or specify anything but true. If you are working on the Events tab, click Do not validate or update data.
  • execMode="partial" specifies a partial refresh when a code fragment is executed. For full refresh, omit this attribute or specify anything but partial. If you are working on the Events tab, click Set partial execution mode.
  • action specifies either:
    • the script where textOfScript is your code. If you are working on the Events tab, click Script Editor. Enter the script in the script window or open the script dialog.
    • the name of a simple action and its arguments. If you are working on the Events tab, click Simple Actions. Use the various buttons and lists to create and edit simple actions.
    • actionGroup which can contain simple actions and other action groups. The condition is optional. You can specify multiple groups.
  • parameters specifies the names and values of any event parameters. If you are working on the Events tab, click Edit Event Parameters.

Client event handlers

The general format for an event handler that is a client script is as follows. If you are working in Design mode, select the Events tab and then the Client tab.
<xp:eventHandler event="name" submit="false"
	<xp:this.script>
		<![CDATA[[textOfScript]]> <!-- script -->
		<xp:actionName arguments</xp:actionName> <!-- or simple action -->
		<xp:scriptGroup conditionScript="textOfScript"> <!-- or simple action group -->
			actions and embedded groups
		</xp:scriptGroup>
	</xp:this.script>
</xp:eventHandler>
Where:
  • event specifies the name of the event, for example, onblur or onclick. If you are working on the Events tab, select the appropriate event.
  • submit="false" means no request is sent to the server when the user activates the event. This is required for a client script.
  • script specifies either:
    • the script where textOfScript is your code. If you are working on the Events tab, click Script Editor. Enter the script in the script window or open the script dialog.
    • the name of a simple action and its arguments. If you are working on the Events tab, click Simple Actions. Use the various buttons and lists to create and edit simple actions.
    • scriptGroup which can contain simple actions and other action groups. The condition is optional. You can specify multiple groups.

Submit and cancel event handlers

A button of type Submit generates an event handler of the following form:
<xp:eventHandler event="onclick" submit="true"
	refreshMode="complete" immediate="false" save="true">
</xp:eventHandler>
A button of type Cancel generates an event handler of the following form:
<xp:eventHandler event="onclick" submit="true"
	refreshMode="complete" immediate="true" save="false">
</xp:eventHandler>
Notice that save="true" for Submit buttons and save="false" for Cancel buttons.

Combining server and client side event handlers

Client side JavaScript™ code can trigger a server side event handler. The first parameter must be a fully qualified path to the event handler, rather than just the server side event handler's id. This allows you to call event handlers that are embedded in custom controls as well. You can acquire the id of the event handler server side and pass it through to the client script as you would any other control (for example using # {id:eventhanderId} or the SSJS function getClientId()).

The event handler is executed within the context you specify. For example, specifying an event handler with an id of view:_id1:repeatCtrl:0:_id33:eventhandler1 would execute against the first item in the xp:repeat with an id of repeatCtrl, whereas view:_id1:repeatCtrl:1:_id33:eventhandler1 would execute against the second item.

The client side event handling is triggered with a button or other user interface element, and passes information to the server to be handled by the server side event handling. If you are working in Design mode, select the Events tab and then the Client tab.
<button dojoType="dijit.form.Button" type="button"
	onClick="XSP.executeOnServer('# {id:eventhandler1a}', '# {id:panel1}')">
	Click To Trigger Server Event Handler
</button>

<xp:eventHandler event="name" id="eventhandler1a">
	<xp:this.action>
		<xp:saveDocument />
	</xp:this.action>
</xp:eventHandler>
If you are working in Design mode, select the Events tab and then the Server tab.
XSP.executeOnServer = function () {
	// the event handler id to be executed is the first argument, and is required
	if (!arguments[0])
		return false;
	var functionName = arguments[0];

	// OPTIONAL - The Client Side ID that is partially refreshed after executing the event handler
	var refreshId = (arguments[1]) ? arguments[1] : "@none";
	var form = (arguments[1]) ? this.findForm(arguments[1]) : dojo.query('form')[0];
       
	// catch all in case dojo element has moved object outside of form...
	if (!form)
		form = dojo.query('form')[0];

	// OPTIONAL - Options object containing onStart, onComplete and onError functions for the call to the
	// handler and subsequent partial refresh
	var options = (arguments[2]) ? arguments[2] : {};

	// OPTIONAL - Value to submit in $$xspsubmitvalue. can be retrieved using context.getSubmittedValue()
	var submitValue = (arguments[3]) ? arguments[3] : '';

	// Set the ID in $$xspsubmitid of the event handler to execute
	dojo.query('[name="$$xspsubmitid"]')[0].value = functionName;
	dojo.query('[name="$$xspsubmitvalue"]')[0].value = submitValue;
	this._partialRefresh("post", form, refreshId, options);
}