イベントの理解

イベントとは、ボタンのクリックや、編集ボックスからのフォーカスの移動など、ユーザーが 実行できるアクションのことです。 イベントハンドラは、ユーザー (設計者) が、イベントに応答して 実行するアクションです。

イベントハンドラは、コントロールまたは XPage の一部です。

イベントハンドラは、スクリプト、シンプルアクション、シンプルアクショングループにすることが可能です。 1 つのイベントについて、ハンドラをクライアント、サーバー、またはその両方で実行するよう指定できます。 クライアントハンドラは、false を返すことにより、それ以降のクライアントハンドラの実行を停止し、サーバーハンドラの実行を取り消すことができます。

設計モードで作業している場合、該当するコントロールまたはページを フォーカスし、[イベント] タブをクリックして、希望のイベントを選択します。 その後、イベントハンドラを指定できます。

イベントはプロパティとして扱われ、[プロパティ] の 下の [すべてのプロパティ] に表示されます。 ただし、[すべてのプロパティ] からイベントの作成や変更を行うことはお勧めしません。 [イベント] タブを使用するか、ソース XML を 使用してください。

サーバーイベントハンドラ

サーバーイベントハンドラの一般的な形式は、 ソースモードで以下のようになります。 設計モードで作業している場合は、 [イベント] タブを選択して、次に [サーバー] タブを 選択してください。
<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}]]> <!-- スクリプト -->
		<xp:actionName arguments</xp:actionName> <!-- またはシンプルアクション -->
		<xp:actionGroup condition="#{javascript:textOfScript}"> <!-- またはシンプルアクショングループ -->
			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>
各部分の説明を以下に示します。

クライアントイベントハンドラ

クライアントスクリプトであるイベントハンドラの一般的な形式は以下のとおりです。 設計モードで作業している場合は、[イベント] タブを選択してから、[クライアント] タブを選択してください。
<xp:eventHandler event="name" submit="false"
	<xp:this.script>
		<![CDATA[[textOfScript]]> <!-- スクリプト -->
		<xp:actionName arguments</xp:actionName> <!-- またはシンプルアクション -->
		<xp:scriptGroup conditionScript="textOfScript"> <!-- またはシンプルアクショングループ -->
			actions and embedded groups
		</xp:scriptGroup>
	</xp:this.script>
</xp:eventHandler>
各部分の説明を以下に示します。

イベントハンドラの送信とキャンセル

タイプが Submit のボタンは、 以下の形式のイベントハンドラを生成します。
<xp:eventHandler event="onclick" submit="true"
	refreshMode="complete" immediate="false" save="true">
</xp:eventHandler>
タイプが Cancel のボタンは、 以下の形式のイベントハンドラを生成します。
<xp:eventHandler event="onclick" submit="true"
	refreshMode="complete" immediate="true" save="false">
</xp:eventHandler>
Submit ボタンの場合 save="true" で、 Cancel ボタンの場合 save="false" であることに注意してください。

サーバーとクライアントサイドのイベントハンドラの結合

クライアントサイドの JavaScript コードにより、サーバーサイドのイベントハンドラをトリガーできます。 最初のパラメータは、単なるサーバーサイドイベントハンドラの ID ではなく、そのイベントハンドラへの完全修飾パスにする必要があります。これにより、カスタムコントロールに埋め込まれているイベントハンドラも呼び出すことができるようになります。サーバーサイドイベントハンドラの ID を取得し、他のコントロールの場合と同様にクライアントスクリプトに渡すことができます (例えば、# {id:eventhanderId} または SSJS 関数 getClientId() を使用します)。

イベントハンドラは、指定するコンテキスト内で実行されます。例えば、view:_id1:repeatCtrl:0:_id33:eventhandler1 の ID を使用してイベントハンドラを指定すると、イベントハンドラは、ID が repeatCtrl の xp:repeat 内の最初の項目に対して実行されるのに対し、view:_id1:repeatCtrl:1:_id33:eventhandler1 の ID を使用して指定すると、イベントハンドラは、2 番目の項目に対して実行されます。

クライアントサイドのイベント処理は、ボタンまたは他のユーザーインターフェース要素によってトリガーされ、サーバーサイドのイベント処理によってハンドリングされる情報をサーバーに渡します。 設計モードで作業している場合は、[イベント] タブを選択してから、[クライアント] タブを選択してください。
<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>
設計モードで作業している場合は、 [イベント] タブを選択して、次に [サーバー] タブを 選択してください。
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);
}
親トピック: コントロールの追加