eventHandler - Event Handler (property)

Specifies scripts and simple actions to be executed when a control event occurs.

Category

events

Syntax

For a server event:
<xp:eventHandler event="eventname" submit="true|false"
	refreshMode="complete|partial|norefresh" refreshId="controlid"
	immediate="true|false"	execMode="partial|full">
	<xp:this.action>
	<!--For a script:-->
		<![CDATA[#{javascript:script}]]> <!--where script is the text of the script-->
	<!--For a simple action:-->
		<xp:simpleactionname attributes>content</xp:simpleactionname>
	<!--For a simple action group:-->
	</xp:this.action>
		<xp:actionGroup condition="#{javascript:script}">
			<xp:simpleactionname attributes>content</xp:simpleactionname>
			...
			<!--Can embed simple action groups-->
		</xp:actionGroup>
	<xp:this.parameters>
		<xp:parameter name="name" value="value"></xp:parameter>
		...
	</xp:this.parameters>
</xp:eventHandler>
For a client event:
<xp:eventHandler event="eventname" submit="false">
	<xp:this.script>
	<!--For a script:-->
		<![CDATA[script]]> <!--where script is the text of the script-->
	<!--For a simple action:-->
		<xp:simpleactionname attributes>content</xp:simpleactionname>
	<!--For a simple action group:-->
		<xp:scriptGroup conditionScript="script">
			<xp:simpleactionname attributes>content</xp:simpleactionname>
			...
			<!--Can embed simple action groups-->
		</xp:scriptGroup>
	</xp:this.script>
</xp:eventHandler>
Where:
  • eventname specifies the name of the event, for example, onblur or onclick. In Design mode, 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. In Design mode, 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. In Design mode, click Full Update.
    • partial reloads a selected part of the page using Asynchronous JavaScript™ and XML (AJAX) technology. In Design mode, click Partial Update.
    • norefresh does not reload the page. In Design mode, click No Update.
  • refreshId applies only for refreshMode="partial" and specifies the control to be updated. In Design mode, click Select Element.
  • immediate="true" suppresses data processing on the server. For data processing, omit this attribute or specify anything but true. In Design mode, 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. In Design mode, click Set partial execution mode.
  • action specifies either:
    • the script where script is your code. In Design mode, click Script Editor. Enter the script in the script window or open the script dialog.
    • the name of a simple action and its arguments. In Design mode, 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.
  • parameters specifies the names and values of any event parameters. In Design mode, click Edit Event Parameters.

Usage

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 can be a server script, a client script, a simple action, or a simple action group.

In Design mode with focus on the control or the page, click the Events tab. 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.

Examples

This button onclick event creates a new document with a server script:
<xp:button value="Create document" id="button4">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action>
			<![CDATA[#{javascript:var doc = database.createDocument();
			doc.replaceItemValue("subject", requestScope.subject);
			doc.save();
			requestScope.subject = null}]]>
		</xp:this.action>
	</xp:eventHandler>
</xp:button>
This button onclick event opens the page named main with a server simple action:
<xp:button id="button5" value="Main page">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action>
			<xp:openPage name="/main.xsp" target="newDocument"></xp:openPage>
		</xp:this.action>
	</xp:eventHandler>
</xp:button>
This button onclick event creates a new document then opens the page named main with a simple action group:
<xp:button value="Create document" id="button6">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action>
			<xp:actionGroup condition="#{javascript:true}">
				<xp:executeScript>
					<xp:this.script><![CDATA[#{javascript:var doc = database.createDocument();
					doc.replaceItemValue("subject", requestScope.subject);
					doc.save();
					requestScope.subject = null}]]>
					</xp:this.script>
				</xp:executeScript>
				<xp:openPage name="/main.xsp" target="newDocument"></xp:openPage>
			</xp:actionGroup>
		</xp:this.action>
	</xp:eventHandler>
</xp:button>
This edit box onblur event displays a message if the user text contains spaces:
<xp:inputText id="inputText2" value="#{requestScope.subject}">
	<xp:eventHandler event="onblur" submit="true" refreshMode="complete">
		<xp:this.script>
		<![CDATA[var e = window.document.getElementById("#{id:inputText2}");
		if(e.value.indexOf(" ") > -1) {
		window.alert("You should not have spaces in this value.")}]]>
		</xp:this.script>
	</xp:eventHandler>
</xp:inputText>