目次


IBM Case Manager カスタム・ウィジェットにおけるプロパティー、カスタム・アクション、およびイベント

カスタム・ウィジェットで扱うことができるプロパティー、カスタム・アクション、およびイベントについて紹介します。

Comments

はじめに

以前の developerWorks 記事 「IBM Case Manager のカスタム・ウィジェット開発手順」 では、ICM カスタム・ウィジェットを開発するための手順を解説しました。本記事では、カスタム・ウィジェットで扱うことができるプロパティー、カスタム・アクション、およびイベントを紹介します。

プロパティーは、ケース管理ソリューションを開発するための Web ベースのツールである Case Manager Builder 上で配置したカスタム・ウィジェットに対して渡す値を定義することができる機能です。この機能を使用することによって、配置したカスタム・ウィジェットごとに別の値を渡すことができるようになります。カスタム・ウィジェットでは、プロパティーから受け取った値によって表示や動作を変えることが可能になります。細かい違いによって複数のカスタム・ウィジェットを作る必要が少なくなり、カスタム・ウィジェットの汎用性を高めることができます。

カスタム・アクションは、ボタン、メニューなどから呼び出す処理を定義する機能です。カスタム・アクションを定義することで、ユーザーがボタンをクリックしたときに、アクションとして実装した処理を実行させることができます。

イベントは、ウィジェットでの処理のタイミングを別のウィジェットに通知できる仕組みです。通知のパブリッシュおよびサブスクライブを定義することができます。この仕組みを利用することによって、例えば、一方のカスタム・ウィジェットでボタンがクリックされたときにイベントをパブリッシュし、そのイベントをサブスクライブしたカスタム・ウィジェットで事前に定義しておいた関数を実行させることによって、ボタンがクリックされたタイミングで他のウィジェットでの処理を開始することができます。イベントにはペイロードとして任意の JSON データを持たせることができるので、イベントのパブリッシュおよびサブスクライブでデータを受け渡すことができます。

それぞれ具体的なサンプル・コードも参照しながら解説をします。巻末にソースコードを添付しています。

前提

ICM のカスタム・プラグイン開発手順については、以前の developerWorks 記事「IBM Case Manager のカスタム・ウィジェット開発手順」を参照してください。サンプル・プロジェクトの構成は、プロパティーおよびイベントについては 「Web プロジェクトあり」 プロジェクト、そしてカスタム・アクションについては 「単体の IBM Content Navigator (ICN) プラグイン」 プロジェクトになっています。

実行環境として ICM 5.2 がすでにインストールされていることを前提とします。 ICM 5.2 のインストールおよび構成の手順については、参考文献の Knowledge Center ページ「IBM Case Manager のインストールおよび構成」を参照してください。

また、開発環境として ICN プラグインの開発環境が必要です。ICN プラグインの開発環境の詳細については、参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」を参照してください。この参考文献に合わせて、この記事でも Rational Application Developer (RAD) 8.0.4 を前提環境として説明します。なお、今回のサンプルのように非常にシンプルな実装で RAD 特有の機能が不要なケースでは、Eclipse 環境でも開発可能です。

プロパティー

汎用的に設計されたカスタム・ウィジェットに対して、Case Manager Builder で配置したそれぞれのカスタム・ウィジェットに特有の値を渡して表示や動作を設定したいことがあります。簡単な例を上げると、カスタム・ウィジェット内のメッセージを変更したり、背景色を変更したり、といった設定です。メッセージや背景色のみが異なるカスタム・ウィジェットを必要なバリエーションの数だけ作成するのは大きな手間になります。このような場合には、カスタム・ウィジェットのプロパティーを定義すれば、ひとつのカスタム・ウィジェットで実現できます。カスタム・ウィジェット内では、配置したカスタム・ウィジェットごとに値を与えることによってプロパティーから受けとった値を使って表示や動作を決めるように実装します。

ここでは、定義できるプロパティーの種類 (タイプ) を順に紹介し、カスタム・ウィジェットの詳細情報をまとめた JSON ファイルでの定義と、Case Manager Builder でのプロパティー値の入力画面、および取得したプロパティー値を表示したケースの詳細画面の例を紹介します。

プロパティー値の入力画面は、Case Manager Builder の Page Designer で配置したウィジェットの「設定の編集」ボタンでダイアログが開きます (図 1 および図 2)。

図 1. プロパティー値の入力画面を開く「設定の編集」アイコンの位置
図 2. 「設定の編集」アイコンをクリックして開いたプロパティー値の入力画面例

プロパティーの定義

プロパティーの定義は、カスタム・ウィジェットの詳細情報をまとめた JSON ファイルにて行います。この JSON ファイルは、カスタム・ウィジェットのプロジェクトに作成している ICMRegistry フォルダー以下にあるファイルです。添付した各サンプル・ウィジェットの情報は表 1 に示します。

表 1. プロパティーに関するサンプル・ウィジェットの情報
プロジェクト名サンプル・ウィジェットの名前ICMRegistry 以下の詳細情報をまとめた JSON ファイル名サンプル・ウィジェット内で定義しているプロパティー
ICMPropertyICMGenericPropertyWidgetICMGenericPropertyWidget.json基本的なプロパティー
ICMSpecificPropertyWidgetICMSpecificPropertyWidget.jsonICM にビルトインされている型のプロパティー
ICMContextualMenuPropertyWidgetICMContextualMenuPropertyWidget.jsonページ・ウィジェットのポップアップ・メニューを設定するプロパティー
ICMOrderPropertyWidgetICMOrderPropertyWidget.jsonケース詳細ウィジェットのタブに関するプロパティー
ICMGroupPropertyTypeWidgetICMGroupPropertyTypeWidget.jsonグループのプロパティー

これらの JSON ファイル内ではプロパティーごとに表 2 に示したキーを定義します。propertyTypetype の設定値によって、プロパティーの種類を指定することができます。リスト 1 には、プロパティー定義の具体例として、文字列のプロパティーの定義を示します。

JSON ファイルに記述する内容は、Technote「Defining registry files for custom actions, properties, page widgets, and events in IBM Case Manager V5.2」および ECM Community Blog「IBM Case Manager V5.2.0 Custom Page Widgets and Actions Development」も参照してください。

表 2. プロパティーで定義するキー
キー必須/オプション説明
propertyType必須文字列定義するプロパティーが単一 (property) なのかグループ (group) なのかを指定します。次節で詳しく説明します。
type必須文字列定義するプロパティーの種類を指定します。次節で詳しく説明します。
id必須文字列ユニークな識別子を指定します。
title必須文字列Case Manager Builder でプロパティーを表示したときのラベルです。
required必須ブール値値が真の場合、定義するプロパティーが必須項目になります。
defaultValueオプションtype の値によって決まる初期値を指定します。
visibilityオプションブール値値が真の場合、定義するプロパティーが表示されます。デフォルトは真です。
propertiesMemberオプション配列propertyType がグループ (group) の場合に、定義するプロパティーの集まりです。
remapNeededオプションブール値値が真の場合、ソリューションがインポートされてデプロイされたときに更新が必要なプロパティーになります。String プロパティーにのみ適用されます。デフォルトは真です。
リスト 1. JSON ファイルでのプロパティー定義の例
"properties": [
	{
		"propertyType": "property",
		"type": "string",
		"id": "Title_TitlePane",
		"title": "Title for Title Pane",
		"required": false,
		"defaultValue": "MultiChoice",
		"visibility": true
	}
]

定義するプロパティーが単一のプロパティー (property) であるかグループ (group) であるかを propertyType で指定します。また、定義するプロパティーの型は type で指定します。propertyType によって指定できる type が異なります。それらについては、次節以降で説明します。

カスタム・ウィジェットの JavaScript コードからは、リスト 2 の書式でプロパティーを参照できます。ここで {property_id} は JSON ファイルで定義した typeid 値です。例えば、リスト 1 の定義例では "Title_TitlePane" がプロパティーの id 値なので、this.widgetProperties.Title_TitlePane でプロパティー値を参照できます。propertyType がグループである場合も同様に、propertiesMember キーに定義した個々の単一プロパティーの id 値を指定することでプロパティー値を参照することができます。

巻末に添付したサンプル・コードでは、カスタム・ウィジェットからプロパティー値を取得して表示しています。具体的なコード例は、巻末のソースコードを参照してください。

リスト 2. ウィジェットからプロパティー値を参照する方法
this.widgetProperties.{property_id}

propertyType: 単一 (property)

propertyType"property" を指定すると、単一のプロパティーを定義することができます。プロパティーの型は type の値で指定します。指定できる type を、基本的なプロパティー、ICM にビルトインされている型のプロパティー、および特定のページで有効なプロパティーの三つに分けて順に説明します。

最初に、基本的なプロパティーを表 3 に示します。

表 3. propertyType が単一 (property) のプロパティーとして指定できるタイプ
タイプ説明
string文字列を値として持つプロパティーを定義します。
booleanブール値を値として持つプロパティーを定義します。
integer整数を値として持つプロパティーを定義します。
float小数を値として持つプロパティーを定義します。
datetime日付と時刻を値として持つプロパティーを定義します。日付と時刻のどちらか一方のみを定義することはできません。
textareaテキストエリアを表示して、文字列を値として持つプロパティーを定義します。
choicelist複数の選択肢からひとつの値を選択できるチョイス・リストを表示します。
labelプロパティー画面に表示する文字列を定義します。入力を持つプロパティーを説明する文字列を表示するためなどに使用できます。改行を入れる目的でも使用できます。また、ヘルプへのリンクを表示することもできます。

それぞれの入力画面例と定義例を図 3図 4、およびリスト 3 に示します。サンプル・ウィジェットは ICMGenericPropertyWidget を参照してください。

"textarea" には、"defaultValue" に改行コード (\n) を含めることができます。

"choicelist" は、"options" に選択肢を列挙します。選択肢は idname を持つオブジェクトの配列として "options" に指定します。"default" には列挙した選択肢のうち、ひとつの id を指定することができます。

"label" は、一つ目の例で示すように Learn More というヘルプ・ページへのリンクを追加表示して、クリックしたときに ICM がインストールされている環境の ICM のヘルプ・ページを表示することもできます。その場合は "help" の値に ICM のヘルプ・ページで該当するページのファイル名 (例:「Case Information ウィジェットの入力イベント」のページであれば acmwc106.htm) を指定します。ヘルプ・ページの具体的なファイル名については ICM のヘルプ・ページを参照して、指定したいページのファイル名を確認してください。

また、二つ目の例で示すように、改行を入れる目的でも使用することができます。この目的で使用する場合は、title を空にして定義することで前後の行に空間を空けることができます。

図 5 は、リスト 3 で定義したプロパティー値を取得し、ICM のページ上に表示した画面例です。

図 3. 基本的なプロパティーの入力画面例 1
図 4. 基本的なプロパティーの入力画面例 2
リスト 3. 基本的なプロパティーの定義例 (ICMGenericPropertyWidget.json)
"properties": [
	{
		"propertyType": "property",
		"type": "string",
		"id": "string_1",
		"title": "String Property 1",
		"defaultValue": "こんにちは。",
		"required": true
	},
	{
		"propertyType": "property",
		"type": "boolean",
		"id": "boolean_1",
		"title": "Boolean Property 1",
		"defaultValue": true,
		"required": true
	},
	{
		"propertyType": "property",
		"type": "integer",
		"id": "integer_1",
		"title": "Integer Property 1",
		"defaultValue": 10,
		"required": true
	},
	{
		"propertyType": "property",
		"type": "float",
		"id": "float_1",
		"title": "Float Property 1",
		"defaultValue": 20.3,
		"required": true
	},
	{
		"propertyType": "property",
		"type": "datetime",
		"id": "datetime_1",
		"title": "Datetime 1",
		"defaultValue": "2014-11-27T03:00:00Z",
		"required": true
	},
	{
		"propertyType": "property",
		"type": "textarea",
		"id": "textarea_1",
		"title": "Text Area Property 1",
		"defaultValue": "一行目\n 二行目",
		"required": true
	},

	{
		"propertyType": "property",
		"type": "choicelist",
		"id":"choicelist_1",
		"defaultValue":"Item_1",
		"required":true,
		"visibility":true,
		"title":"Choicelist 1",
		"options": [
			{ "id": "Item_1", "title": "Item 1" },
			{ "id": "Item_2", "title": "Item 2" }
		]
	},

	{
		"propertyType": "property",
		"type": "label",
		"id": "label_1",
		"title": "ラベル・プロパティー",
		"help": "help_page.html"
	},
	{
		"propertyType": "property",
		"type": "label",
		"id": "label_2",
		"title": ""
	},
	{
		"propertyType": "property",
		"type": "label",
		"id": "label_3",
		"title": "label_2 は改行として使っています。"
	}
]
図 5. 基本的なプロパティーの表示例

次に、ICM にビルトインされている型を扱えるプロパティーを説明します。表 4 に指定できる type を示します。これらのプロパティーで選択できる値は、カスタム・ウィジェットを配置するページとそのページを定義しているソリューションから取得されます。例えば "role" では、そのソリューションで定義されているロールがプロパティーの選択肢としてドロップダウン・リストで表示され、その中からひとつを選択することができます。

"toolbar" では、ツールバーを持つカスタム・ウィジェットのツールバー上のボタンとアクションを定義することができます。

それぞれの入力画面例と定義例を図 6リスト 4 に示します。サンプル・ウィジェットは、ICMSpecificPropertyWidget を参照してください。

図 8 は、図 6 および図 7 で定義したプロパティー値を取得し、ICM のページ上に表示した画面例です。

表 4. ICM にビルトインされている型のプロパティー
type説明
roleそのソリューションで有効なロールのリストを表示し、ユーザーが選択できるようにします。
taskそのソリューションで有効なタスクのリストを表示し、ユーザーが選択できるようにします。
caseTypeCase Manager Builder で、ユーザーがケース・タイプを選択できるエディタを表示する。
viewそのソリューションで有効なすべてのビューを含んだ選択リストを表示します。Case type の Views の Properties Layouts で定義したビューが表示されます。
viewListひとつのビューを選択できる case type と view のペアを表示します。複数のビューをリストに追加することができます。ビューの id がリストになって出力されます。
toolbarページに表示されるツールバーを編集できるようにします。
図 6. ICM にビルトインされている型のプロパティーの入力画面例 1
図 7. ICM にビルトインされている型のプロパティーの入力画面例 2
リスト 4. ICM にビルトインされている型のプロパティーの定義例 (ICMSpecificPropertyWidget.json)
"properties": [
	{
		"propertyType": "property",
		"type": "role",
		"id": "role_1",
		"required": false,
		"visibility": true,
		"title": "Role 1"
	},
	{
		"propertyType": "property",
		"type": "task",
		"id": "task_1",
		"required": false,
		"visibility": true,
		"title": "Task 1"
	},
	{
		"propertyType": "property",
		"type": "caseType",
		"id": "casetype_1",
		"required": false,
		"title": "Case Type 1"
	},
	{
		"propertyType": "property",
		"type": "view",
		"id": "view_1",
		"required": false,
		"visibility": true,
		"title": "View 1"
	},
	{
		"propertyType": "property",
		"type": "viewList",
		"id": "viewlist_1",
		"required": false,
		"visibility": true,
		"title": "View List 1"
	},
	{
		"propertyType": "property",
		"type": "toolbar",
		"id": "toolbar_1",
		"context": ["CustomContext"],
		"defaultValue": {
			"actionList": [{
					"actionDefinitionId": icm.action.utility.OpenWebPage",
				"propertiesValue": {
					"label": "IBMWebPage",
					"targetURL": "http://www.ibm.com"
				}
			}]
		},
		"required": false,
		"visibility": true,
		"title": "toolbar 1"
	}
]
図 8. ICM にビルトインされている型のプロパティーの表示例

toolbar プロパティーで設定したツールバーを表示するには、カスタム・ウィジェットでの処理を実装した JavaScript コードでの処理が必要です。リスト 5 に示すように、定義した toolbarid を引数のオブジェクトに持つ icm.widget.menu.Toolbar インスタンスを作成します。次に、そのインスタンスの DOM ノードを、テンプレート (リスト 6) で定義した ContentPane の "content" として設定します。

リスト 5. toolbar プロパティーで設定したツールバーを反映するコード (ICMSpecificPropertyWidget.js)
//アクションが実行されるコンテキストを設定します
this.setActionContext("CustomContext", {customProperty: true});

if (!this.customToolbar) {
	//dojoAttachPoint キーの値として、定義した tooler の id を指定したオブジェクトを引数にして
	//Toolbar インスタンスを作成します
	this.customToolbar = new Toolbar({
		dojoAttachPoint: "toolbar_1"
	});

	//作成した Toolbar インスタンスの DOM ノードを、テンプレートに定義した div の content として登録します
	this.customToolbarHolder.set("content", this.customToolbar.domNode);

	//ポップアップ・メニューを起動します
	this.topToolbar.startup();
}
リスト 6. ツールバーを表示する場所の定義 (ICMSpecificPropertyWidget.html)
<div data-dojo-type="dijit/layout/ContentPane"
	data-dojo-attach-point="customToolbarHolder" data-dojo-props="style: 'border:none;'">
</div>
図 9. toolbar プロパティーで設定したツールバーを反映した表示例

最後に、特定ページのカスタム・ウィジェットで有効なタイプを表 5 に示します。これらのタイプは、特定のウィジェットを継承したカスタム・ウィジェットにおいて定義することができます。

"contextualMenu"icm.base.BasePageWidget を継承したカスタム・ウィジェットで有効なタイプです。コンテキストに応じて、表示されるポップアップ・メニューを設定することができます。Case Manager Builder での入力画面例を図 10 に示します。サンプル・ウィジェットは、ICMContextualMenuPropertyWidget を参照してください。

"order" は、icm.pgwidget.caseinfo.CaseInfo を継承したカスタム・ウィジェットで有効なタイプです。Case Information ウィジェットには要約、ドキュメント、タスク、および履歴のタブがありますが、それらのタブを表示するかどうか、および表示の順序を設定することができます。Case Manager Builder での設定画面例を図 11 に示します。サンプル・ウィジェットは、ICMOrderPropertyWidget です。

表 5. 特定ページのウィジェットで有効なタイプ
type特定ページのウィジェット説明
contextualMenuicm.base.BasePageWidgetPage ウィジェットのポップアップ・メニューに表示される項目を編集できるようにします。
ordericm.pgwidget.caseinfo.CaseInfoCase Information ウィジェットに配置されているタブの順番を編集できるようにします。
図 10. contextualMenu プロパティーの入力画面例
図 11. order プロパティーの入力画面例

contextualMenu および order プロパティーの定義例をリスト 7 およびリスト 10 に示します。カスタム・ウィジェットでの処理を実装した JavaScript コードをリスト 8 に示します。そのテンプレートである HTML ファイルをリスト 9 に示します。また、それぞれを設定したカスタム・ウィジェットの実行例を図 12 および図 13 に示します。サンプル・ウィジェットは、ICMContextualMenuPropertyWidget を参照してください。

定義したポップアップ・メニューを表示させるためには、カスタム・ウィジェットでの処理を実装した JavaScript コードでポップアップ・メニューへ追加する必要があります。まず、dojoAttachPoint キーの値として、定義した contextualMenuid を引数のオブジェクトに持つ ContextualMenu インスタンスを作成します。次に、作成した ContextualMenu インスタンスの DOM ノードを、テンプレートで定義した div の子として追加します。また、MenuManager の setTargetReference 関数を使って、ポップアップ・メニューを出す場所を指定します。リスト 8 では、テンプレートの ICMContextualMenuPropertyWidget.htmldata-dojo-attach-point として定義してある "contextualMenuTargetRefPoint" という div を指定しています。

"context" キーでは、アクションが実行されるために必要なコンテキストを定義します。コンテキストの定義は ANDOR を組み合わせることができます。例えば、"Context 1" かつ "Context 2" のときに実行できるアクションを定義するには [["Context 1", "Context 2"]] のように定義します。また、"Context 1" または "Context 2" のときに実行できるアクションを定義するには ["Context 1", "Context 2"] のように定義します。これらを組み合わせて、「"Context 1" かつ "Context 2"」もしくは「"Context 3" かつ "Context 4"」のときに実行できるアクションを定義するには [["Context 1", "Context 2"], ["Context 3", "Context 4"]] のように定義します。

ICM が提供している既存のコンテキストは参考文献の Knowledge Center ページ「アクション・コンテキスト」を参照してください。また、カスタム・ウィジェットの中でカスタム・コンテキストを使用することができます。リスト 10 では CustomContext というカスタム・コンテキストを指定しています。カスタム・ウィジェットの実行時にコンテキストを変更するには、カスタム・ウィジェットでの処理を実装した JavaScript コードの中で、MenuManager の setSelectedItems 関数を使います。リスト 8 では、contextualMenuTargetRefPoint のポップアップ・メニューに対して、{customProperty: true} というコンテキスト・オブジェクトの配列を指定して CustomContext というコンテキストを設定しています。

リスト 7. contextualMenu プロパティーの定義例 (ICMContextualMenuPropertyWidget.json)
"properties":[
	{
		"propertyType": "property",
		"type": "contextualMenu",
		"id": "customContextualMenu_1",
		"context": ["CustomContext"],
		"defaultValue": {
			"actionList": [
				{
					"actionDefinitionId": "icm.action.utility.OpenWebPage",
					"propertiesValue": {
						"label": "IBM Web Page",
						"targetURL": "http://www.ibm.com"
					}
				}
			]
		},
		"required": false,
		"visibility": true,
		"title": "contextualMenu 1"
	}
]
リスト 8. contextualMenu プロパティーの設定をポップアップ・メニューに反映するコード (ICMContextualMenuPropertyWidget.js)
define([
	"dojo/string",
	"dojo/_base/array",
	"dojo/_base/declare",
	"dojo/_base/lang",
	"icm/base/_BaseWidget",
	"icm/base/BaseActionContext",
	"icm/base/BasePageWidget",
	"icm/widget/menu/ContextualMenu",
	"icm/widget/menu/MenuManager",
	"dojo/text!./templates/ICMContextualMenuPropertyWidget.html"
], function(string, array, declare, lang, _BaseWidget, BaseActionContext, 
			BasePageWidget, ContextualMenu, MenuManager, template){
	return declare("icmproperty.pgwidget.ICMContextualMenuPropertyWidget", 
			[_BaseWidget, BasePageWidget, BaseActionContext], {
		templateString: template,

		postCreate: function(){
			this.inherited(arguments);

			 if (!this.menu) {
				//定義した contextualMenu の id を dojoAttachPoint キーの値として
				//指定したオブジェクトを引数にして ContextualMenu インスタンスを作成します
				this.menu = new ContextualMenu({
					dojoAttachPoint: "customContextualMenu_1"
				});

				//作成した ContextualMenu インスタンスの DOM ノードを、
				//テンプレートに定義した div の子として登録します
				this.contextualMenuStore.appendChild(this.menu.domNode);

				//ポップアップ・メニューを表示する場所を指定します
				MenuManager.setTargetReference(this.menu,
						"contextualMenuTargetRefPoint");

				//アクションが実行されるコテンキストを設定します
				MenuManager.setSelectedItems(this.id, "contextualMenuTargetRefPoint",
					[{customProperty: true}], "CustomContext");

				//ポップアップ・メニューを起動します
				this.menu.startup();
			}
		}

	});
});
リスト 9. テンプレート HTML ファイル (ICMContextualMenuPropertyWidget.html)
<div>
	<div data-dojo-attach-point="contextualMenuStore"></div>
	<span data-dojo-attach-point="contextualMenuTargetRefPoint">
		ここを右クリックするとポップアップ・メニューが表示されます。
	</span>
</div>
図 12. contextualMenu の表示例

order プロパティーの定義例をリスト 10 に示します。また、プロパティー値を設定したカスタム・ウィジェットの実行例を図 13 に示します。サンプル・ウィジェットは、ICMOrderPropertyWidget を参照してください。

order プロパティーの定義では、"options" キーで選択肢を定義し、"defaultValue" キーでプロパティー入力画面での各タブの順番および表示/非表示について初期値を定義できます。Case Information ウィジェットでは、要約、ドキュメント、タスク、および履歴の最大 4 種類のタブを表示することができます。Summary, Documents, Activities, History をそれぞれ要約、ドキュメント、タスク、および履歴の id として記述します。title にはタブの名前として表示される任意の文字列を記述します。"defaultValue" として記述した配列の順番が、タブの順番の初期値になります。また、"visibility" のブール値でタブの表示/非表示の初期値を指定します。

リスト 10. order プロパティーの定義例 (ICMOrderPropertyWidget.json)
"properties": [
	{
		"propertyType": "property",
		"type": "order",
		"id": "tabDefinition",
		"required": false,
		"visibility": true,
		"title": "タブの表示/非表示と順番を設定してください。",
		"defaultValue": [
			{"id": "Summary", "visibility": true},
			{"id": "Documents", "visibility": true},
			{"id": "Activities", "visibility": true},
			{"id": "History", "visibility": true}
		],
		"options": [
			{ "id": "Summary", "title": "要約" },
			{ "id": "Documents", "title": "ドキュメント" },
			{ "id": "Activities", "title": "タスク" },
			{ "id": "History", "title": "履歴" }
		]
	}
]
図 13. order の表示例

propertyType: グループ (group)

propertyType"group" を指定すると、前節で紹介した単一のプロパティーを複数まとめたグループを定義することができます。例えば、文章のタイトルを入力する文字列のプロパティーと作成日を入力する日付のプロパティーをひとつのまとまりとして枠で囲ってプロパティー画面に表示することができます。複数のプロパティーをグループで表示することによって見やすく意味が伝わりやすくなり、ユーザビリティを向上させることができます。

propertyType がグループ (group) のタイプを表 6 に示します。これらを使って複数のプロパティーをグループとしてまとめて表示することができます。まとめて表示したいプロパティーは、propertyMembers に配列として列挙します。

"section" は、図 14 のように複数のプロパティーをまとめて折り畳みできるように表示します。

"dropdown" は、図 14 のように複数のプロパティーからひとつを選択できるように表示します。

"propertyPanel" は、図 14 のように複数のプロパティーをひとつのまとまりとして枠で囲って表示します。

"tab" は、図 15 のように複数のプロパティーをまとめて新しいタブに表示します。

グループは入れ子構造を作ることができます。例えば、タブを定義して、そのタブの中に複数のドロップダウン・リストを表示することも可能です。

それぞれの定義例をリスト 11 に示します。サンプル・ウィジェットは、ICMGroupPropertyTypeWidget を参照してください。

図 16 は、リスト 11 で定義したプロパティー値を取得し、ICM のページ上に表示した画面例です。

表 6. propertyType がグループ (group) のタイプ
タイプ説明
section折り畳みが可能なセクションを定義します。
tab設定変更をするダイアログで新しいタブを定義します。
dropdownあらかじめ定義されたプロパティーのリストからひとつを選択するドロップダウン・リストを定義します。
propertyPanelプロパティーのリストが表示されるパネルを定義します。プロパティーの集まりをひとくくりにして表示することで、ユーザーにとってまとまりがわかりやすく表示できます。
図 14. propertyType がグループ (group) のタイプを使った入力画面例 ("Section 1" を開いた状態)
図 15. propertyType がグループ (group) のタイプを使った入力画面例 ("Tab 1" を選択した状態)
リスト 11. propertyType がグループ (group) のタイプの定義例 (ICMGroupPropertyTypeWidget.json)
"properties": [
	{
		"propertyType": "group",
		"type": "section",
		"id": "section_1",
		"title": "Section 1",
		"propertyMembers": [
			{
				"propertyType": "property",
				"type": "boolean",
				"id": "section_1_boolean_1",
				"defaultValue": true,
				"required": true,
				"title": "Boolean 1 in section 1"
			},
			{
				"propertyType": "property",
				"type": "boolean",
				"id": "section_1_boolean_2",
				"defaultValue": false,
				"required": true,
				"title": "Boolean 2 in section 1"
			}
		]
	},
	{
		"propertyType": "group",
		"type": "propertyPanel",
		"id": "panel_1",
		"title": "Panel 1",
		"propertyMembers": [
			{
				"propertyType": "property",
				"type": "string",
				"id": "panel_1_string_1",
				"title": "String 1 in panel 1",
				"defaultValue": "こんにちは。",
				"required": true
			},
			{
				"propertyType": "property",
				"type": "boolean",
				"id": "panel_1_boolean_1",
				"title": "Panel 1 Boolean 1",
				"defaultValue": true,
				"required": true
			}
		]
	},
	{
		"propertyType": "group",
		"type": "dropdown",
		"id": "dropdown_1",
		"title": "Dropdown 1",
		"propertyMembers": [
			{
				"propertyType": "property",
				"type": "string",
				"id": "dropdown_1_string_1",
				"title": "こんにちは 1",
				"defaultValue": "hello 1",
				"required": true
			},
			{
				"propertyType": "property",
				"type": "string",
				"id": "dropdown_1_string2",
				"title": "こんにちは 2",
				"defaultValue": "hello 2",
				"required": true
			}
		]
	},
	{
		"propertyType": "group",
		"type": "tab",
		"id": "tab_1",
		"title": "Tab 1",
		"propertyMembers": [
			{
				"propertyType": "property",
				"type": "integer",
				"id": "tab_1_integer_1",
				"title": "Integer 1",
				"defaultValue": 1,
				"required": true
			}
		]
	}
]
図 16. propertyType がグループ (group) のタイプで定義したプロパティーの表示例

アクション

カスタム・アクションは、ICM で使用できる新しいアクションを定義するためのものです。ここでは、サンプルとして ICMCustomActionPlugin を紹介しながらカスタム・アクションの実現方法を説明します。カスタム・アクションは、com.ibm.ecm.extension.PluginAction クラスを継承した Java クラス内で定義します。

巻末に添付したサンプル・ウィジェットの情報は表 7 に示します。

表 7. アクションに関するサンプル・ウィジェットの情報
プロジェクト名サンプル・ウィジェット名ICMRegistry 以下の詳細情報をまとめた JSON ファイル名説明
ICMCustomActionPluginなしなしサンプル・ウィジェットはなく、アクションのみを定義した ICN カスタム・プラグインです。アクションの定義は ICMCustomAction.java に記述しています。

まず、カスタム・アクション用のプロジェクトを作成します。カスタム・アクションは単体の ICN プラグイン・プロジェクトで作成可能ですので、ここでは単体の ICN プラグイン・プロジェクト構成にします。ただし、Web プロジェクトあり/なしの構成でも同様の方法で作成可能です。プロジェクトのファイルおよびフォルダーの構成は図 17 に示します。ICN プラグイン・プロジェクトについての詳細は Redbook「Customizing and Extending IBM Content Navigator」を参照してください。

図 17. ICMCustomActionPlugin

次に、アクションの定義を実装する Java コードを説明します。ICMCustomAction.javaリスト 12 に示します。

getAdditionalConfiguration 関数にカスタム・アクションの定義を記述します。Case Manager Builder でカスタム・ウィジェットを設定するときに入力できるプロパティーを properties で定義します。また、カスタム・ウィジェットで使用するイベントを events で定義します。プロパティーで定義できるキーを表 8 に示します。

"context" キーでアクションが実行されるために必要なコンテキストを定義します。コンテキストの定義は ANDOR を組み合わせることができます。ICM が提供している既存のコンテキストは Knowledge Center ページ「アクション・コンテキスト」を参照してください。また、カスタム・ウィジェットの中でカスタム・コンテキストを使用することができます。カスタム・コンテキストはカスタム・ウィジェットでの処理を実装した JavaScript コードの中で icm.base.BaseActionContext を継承し、setActionContext 関数を呼び出すことよって設定することができます。getActionContext 関数で現在のコンテキストを取得することができ、また cleanActionContext 関数によって特定のコンテキストを削除することができます。これらの関数の詳しい仕様については Knowledge Center ページ「IBM Case Manager JavaScript API リファレンス」を参照してください。

リスト 12. アクションの定義を実装する Java コード (ICMCustomAction.java)
package com.ibm.icm.sample.plugin.actions;

import java.io.IOException;
import java.util.Locale;

import com.ibm.ecm.extension.PluginAction;
import com.ibm.json.java.JSONObject;

public class ICMCustomAction extends PluginAction {

	@Override
	public String getId() {
		return "icmcustomaction.CustomAction";
	}

	@Override
	public String getName(Locale locale) {
		return "ICM Custom Action";
	}

	@Override
	public String getIcon() {
		return "";
	}

	@Override
	public String getPrivilege() {
		return "";
	}

	@Override
	public String getServerTypes() {
		return "p8,cm";
	}

	@Override
	public String getActionFunction() {
		return "";
	}

	@Override
	public boolean isMultiDoc() {
		return false;
	}

	@Override
	public boolean isGlobal() {
		return false;
	}

	@Override
	public String getActionModelClass() {
		return "icmcustomaction/action/ICMCustomAction";
	}

	@Override
	public JSONObject getAdditionalConfiguration(Locale locale) {
		String jsonString = "{" +
				"\"ICM_ACTION_COMPATIBLE\": true," +
				"\"context\": null," +
				"\"name\": \"ICM Custom Action\"," +
				"\"description\": \"メッセージを表示します。\"," +
				"\"properties\": [" +
					"{" +
						"\"id\": \"label\"," +
						"\"title\": \"ラベル\"," +
						"\"defaultValue\": \"メッセージの表示\"," +
						"\"type\": \"string\"," +
						"\"isLocalized\": false" +
					"}," +
					"{" +
						"\"id\": \"message\"," +
						"\"title\": \"メッセージ\"," +
						"\"defaultValue\": \"こんにちは。\"," +
						"\"type\": \"string\"," +
						"\"isLocalized\": false" +
					"}" +
				"]," +
				"\"events\": [" +
					"{" +
						"\"id\": \"icmcustomaction.PublishEvent\"," +
						"\"title\": \"publish event\"," +
						"\"description\": \"カスタム・アクションのイベントです\"," +
						"\"direction\": \"published\"," +
						"\"type\": \"broadcast\"" +
					"}" +
				"]" +
			"}";

		try {
			return JSONObject.parse(jsonString);
		} catch (IOException e) {
			e.printStackTrace();
		}
		return null;
	}
}
表 8. アクションで定義するキー
キー必須説明
ICM_ACTION_COMPATIBLEはいブール値真にすることで、ICM のケースで定義したアクションが使用できるようになります。
typeオプション文字列

アクションを実行するにあたって、特別な処理をさせることができます。指定可能な値は下記の 2 種類です。

iterator: この場合は、アクションを実装するコードで getIterator() 関数を定義する必要があります。ボタンまたはメニューに、その関数が返すアイテムのリストが表示されます。ひとつのアイテムが選択されると実際にアクションが実行され、選択されたアイテムを実行中に参照することができます。

checkbox:ツールバーもしくはポップアップ・メニューにチェックボックスとしてアクションが表示されるようになります。この場合は、"fieldname" を定義して、その値をチェックボックスに指定する必要があります。

fieldnametypecheckbox の場合は必須文字列typecheckbox の場合は、この値は必須です。properties 配列で設定されたプロパティーの Id を設定します。
descriptionはい文字列Case Manager Builder のプロパティー値の入力画面で、アクションの説明としツールチップ上に表示されます。
contextはい配列

アクションが実行されるために必要なコンテキストを配列で定義します。コンテキストは、contextualMenu プロパティーの "context" キーと同様に記述できます。

[["Context 1", "Context 2"]]: "Context 1" および "Context 2" が必要

["Context 1", "Context 2"]: "Context 1" もしくは "Context 2" が必要

["Context 1"]"Context 1" が必要

[]:空の配列はどんなコンテキストにおいても実行できることを意味します。

nameはい文字列Case Manager Builder のプロパティー値の入力画面で、アクションの名前として表示されます。
propertiesはい配列ページ・ウィジェットでのツールバーおよびメニューで表示するプロパティー、もしくは実行時に内部的に使用されるアクションを選択できるプロパティーの配列です。
eventsはい配列アクションによって発信されるイベントの配列です。発信されるイベントがない場合は空の配列にします。(イベントについての詳細は次章で説明します)

カスタム・アクションの実装は、icm.action.Action を拡張したウィジェットに記述します。その中で execute() を定義して具体的なアクションの動きを実装します。

カスタム・ウィジェットの JavaScript ファイルはリスト 13 に示します。アクションが実行されるときには execute 関数が実行されます。この例ではプロパティーで設定された文字列をアラートで表示します。

リスト 13. カスタム・アクションを実装するコード (ICMCustomAction.js)
define([
	"dojo/_base/declare",
	"icm/action/Action"
], function(declare, Action) {
	return declare("icmcustomaction.action.ICMCustomAction", [Action], {
		execute: function() {
			alert(this.propertiesValue.message || "メッセージなし");
		}
	});
});

カスタム・アクションの実行

カスタム・アクションを実行するためには、まず、ページのボタンにカスタム・アクションを追加する必要があります。

  1. 作成した ICN プラグイン ICMCustomActionPlugin をビルドして、JAR ファイルをロードします。具体的な手順は、参考文献の developerWorks 記事「IBM Content Navigator におけるプラグイン開発手順」を参照してください。
  2. Case Manager Builder を開いて、ソリューションの「編集」をクリックします。
  3. 「ページ」タブに移動して、「「ケースの詳細」ページ」からページを選択して Page Designer を起動します。
  4. Case Toolbar の「設定の編集」アイコンをクリックして、ダイアログを開きます (図 18)。
  5. 「ツールバー」タブを開きます。
  6. 「ボタンの追加」ボタンをクリックします (図 19)。
  7. アクションとして ICM Custom Action を選択します (図 20)。
  8. 「OK」ボタンをクリックします。
  9. 新しくボタンの定義がリストの最後に追加されていることを確認します (図 21)。
  10. 「OK」ボタンをクリックしてダイアログを閉じます。
  11. ページおよびソリューションを保存して、ソリューションをデプロイします。
図 18. Case Toolbar の「設定の編集」アイコンの位置
図 19. 「ボタンの追加」アイコンの位置
図 20. 追加するボタンのアクションの選択
図 21. 追加したボタンの確認

ICM のケースから先ほど追加したボタンをクリックして、カスタム・アクションを実行します。

  1. ICM にログインして、ケースを開きます。
  2. ツールバーの「メッセージの表示」ボタンをクリックすると、カスタム・アクションが実行されてメッセージがポップアップで表示されます (図 22)。
図 22. カスタム・アクションの実行例

イベント

イベントは、処理のタイミングを別のウィジェットに通知できる仕組みです。ICM のカスタム・ウィジェットでは、イベントのパブリッシュ/サブスクライブを定義して通知を送受信することで、ウィジェット間で連動して動作させることができます。この仕組みを利用することによって、例えば、一方のウィジェットでボタンがクリックされたときにイベントをパブリッシュし、そのイベントをサブスクライブするカスタム・ウィジェットで事前に定義しておいた関数を実行させることができます。イベントにはペイロードとして任意の JSON データを持たせることができるので、パブリッシュ/サブスクライブ間で任意の値を送受信することができます。ICM が提供している既存のウィジェットでもイベントが定義されており、それらのイベントをサブスクライブすることで既存のウィジェットで実行される処理のタイミングに合わせてカスタム・ウィジェットでの処理を行うこともできます。

巻末に添付したサンプル・ウィジェットの情報は表 9 に示します。

表 9. イベントに関するサンプル・ウィジェットの詳細情報
プロジェクト名サンプル・ウィジェット名ICMRegistry 以下の詳細情報をまとめた JSON ファイル名説明
ICMEventICMEventPublisherWidgetICMEventPublisherWidget.jsonパブリッシュするイベントを定義したサンプル・ウィジェット
ICMEventSubscriberWidgetICMEventSubscriverWidget.jsonサブスクライブするイベントを定義したサンプル・ウィジェット

サンプルの概要

ここでは、イベントのサンプルとして ICM カスタム・プラグインを説明します。このプラグインはイベントをパブリッシュする ICMEventPublisherWidget、およびイベントをサブスクライブする ICMEventSubscriberWidget を持ちます。

まずは、RAD または eclipse 上にて Web プロジェクトなしの ICM カスタム・プラグインのプロジェクトを作成します。また、ICMEventPublisherWidget および ICMEventSubscriberWidget を作成します。プロジェクトのファイル構成は図 23 に示します。プロジェクト作成の詳しい説明は、以前の developerWorks 記事「IBM Case Manager のカスタム・ウィジェット開発手順」を参照してください。

図 23. イベントのパブリッシュ/サブスクライブをするカスタム・ウィジェットを持つプロジェクトの作成

イベントの定義は ICMRegistry のフォルダー以下に配置する各カスタム・ウィジェットの JSON ファイル内で定義します。イベントを定義する際に指定するキーを表 10 に示します。具体的な記述例は次節で説明します。

表 10. イベントで定義するキー
キー必須/オプション説明
id必須文字列ユニークな識別子
title必須文字列イベントの表示名
direction必須文字列イベントがパブリッシュの場合は published、サブスクライブの場合は subscribed
typeパブリッシュのときのみ必須文字列

パブリッシュ (directionpublished) の場合のみ、broadcastwiring を指定します。

broadcast: イベントはブロードキャストされます。

wiring: イベントは指定したウィジェットへ送られます。ウィジェットの指定は Case Manager Builder で設定します。

functionNameサブスクライブのときのみ必須文字列サブスクライブ (directionsubscribed) の場合のみ、イベントをサブスクライブしたときに呼び出すイベント・ハンドラーの関数名を指定します。
descriptionオプション文字列イベントの説明です。Case Manager Builder 上でイベントのワイヤリングをするときに、イベントの説明として表示されます。

パブリッシュ・イベントの定義

ICMEventPublisherWidget 用のイベント定義は ICMRegistry 以下にある ICMEventPublisherWidget.json に記述します。ICMEventPublisherWidget.json でのイベント定義部分を抜粋してリスト 14 に示します。ここでは、icm.SendEventPayload という id でイベントの定義を記述します。パブリッシュするイベントとして directionpublished にします。このイベントは Case Manager Builder 上で通知するウィジェットを指定できるように、typewiring として定義します。

リスト 14. イベントの定義 (ICMEventPublisherWidget.json)
"events": [
	{
		"id": "icm.SendEventPayload",
		"title": "Send Event Payload",
		"description": "ペイロードに文字列を持つイベントです",
		"direction": "published",
		"type": "wiring"
	}
]

次に、先ほど定義した icm.SendEventPayload というイベントを実際にパブリッシュする ICMEventPublisherWidget ウィジェットの定義をします。このウィジェットは、ボタンをひとつ配置し、クリックされたときにイベントをパブリッシュします。これを実装した JavaScript ファイルをリスト 15 に示します。onPublishEvent 関数に対して、イベントの id とペイロードを引数に与えて呼び出すことで、イベントをパブリッシュすることができます。ここでは、icm.SendEventPayload イベントに与えるペイロードとして payload オブジェクトを作成して、onPublishEvent 関数の引数に指定しています。

リスト 15. イベントをパブリッシュするコード (ICMEventPublisherWidget.js)
define([
	"dojo/_base/declare",
	"icm/base/_BaseWidget",
	"icm/base/BasePageWidget",
	"dojo/text!./templates/ICMEventPublisherWidget.html",
	"dijit/form/Button" // in template
], function(declare, _BaseWidget, BasePageWidget, template){
	return declare("icmevent.pgwidget.ICMEventPublisherWidget", [_BaseWidget, BasePageWidget], {
		templateString: template,

		publishEvent: function() {
			var payload = {myEventTitle:"イベント・タイトル"};
			this.onPublishEvent("icm.SendEventPayload", payload);
		}
	});
});

サブスクライブ・イベントの定義

ICMEventSubscriberWidget 用のイベント定義は ICMRegistry 以下にある ICMEventSubscriberWidget.json に記述します。ICMEventSubscriberWidget.json でのイベント定義部分を抜粋してリスト 16 に示します。ここでは、icm.ReceiveEvent という id でイベントの定義を記述します。サブスクライブするイベントとして directionsubscribed にします。このイベントをサブスクライブしたときに実行されるウィジェットの関数として handleReceiveEvent を指定しています。

リスト 16. イベントの定義 (ICMEventSubscriberWidget.json)
"events": [
	{
		"id": "icm.ReceiveEvent",
		"title": "Receive Event Payload",
		"description": "イベントのペイロードを受けとります",
		"direction": "subscribed",
		"functionName": "handleReceiveEvent"
	}
]

次に、先ほど定義した icm.ReceiveEvent イベントをサブスクライブする ICMEventSubscriberWidget ウィジェットの定義をします。このウィジェットでは、イベントをサブスクライブするとペイロードの値を取得して表示します。これを実装した JavaScript ファイルをリスト 17 に示します。リスト 16 で定義したように、イベントをサブスクライブすると handleReceiveEvent 関数が実行されます。イベント・ハンドラーとして指定した handleReceiveEvent 関数には、ペイロードの値が第一引数としてわたってきます。

リスト 17. イベント・ハンドラーのコード (ICMEventSubscriberWidget.js)
define([
	"dojo/json",
	"dojo/_base/declare",
	"icm/base/_BaseWidget",
	"icm/base/BasePageWidget",
	"dojo/text!./templates/ICMEventSubscriberWidget.html"
], function(json, declare, _BaseWidget, BasePageWidget, template){
	return declare("icmevent.pgwidget.ICMEventSubscriberWidget", [_BaseWidget, BasePageWidget], {
		templateString: template,

		handleReceiveEvent: function(payload) {
			this._holder.innerHTML = "イベントがサブスクライブされました: " + json.stringify(payload);
		}
	});
});

ワイヤリング

ワイヤリングとは、パブリッシュされたイベントをどのウィジェットのどのイベントでサブスクライブするかを定義することです。この定義は Case Manager Builder 上でウィジェットをページに配置したときに行います。下記手順でワイヤリングを行います。ここでは、ICMEventPublisherWidget の icm.SendEventPayload を、ICMEventSubscriberWidget の icm.SubscribedEvnet につなぎます。

  1. ICMEvent プロジェクトをビルドして、ICM にデプロイします。具体的な手順は参考文献の developerWorks 記事「IBM Case Manager のカスタム・ウィジェット開発手順」を参照してください。
  2. Case Manager Builder を開いて、ソリューションの「編集」をクリックします。
  3. 「ページ」タブに移動して、「「ケースの詳細」ページ」からページを選択して Page Designer を起動します。
  4. ICMEventPublisherWidget および ICMEventSubscriberWidget を任意の位置に配置します。
  5. ICMEventPublisherWidget の「関連付けの編集」アイコンをクリックして、ダイアログを開きます (図 24)。
  6. 出力イベントに Send Event Payload、ターゲット・ウィジェットに ICM Event Subscriber、および入力イベントに Receive Event Payload を選択して (図 25)、「ワイヤーの追加」ボタンをクリックします。
  7. 指定した関連付けが追加されていることを確認して (図 26)、「OK」をクリックしてダイアログを閉じます。
  8. 入出力イベント数を確認します (図 27)。
  9. ページおよびソリューションを保存して、ソリューションをデプロイします。
図 24. ICMEventPublisherWidget でのワイヤリング設定ダイアログを開く「関連付けの編集」アイコンの位置
図 25. ICMEventPublisherWidget での出力イベントの設定
図 26. ワイヤリング設定の確認
図 27. 各ウィジェットの入出力イベント数の確認

実行例

ICM にログインしてケースを開きます。「パブリッシュ」ボタンをクリックする (図 28) と ICMEventPublisherWidget から icm.SendEventPayload がパブリッシュされます。icm.SendEventPayload は ICMEventSubscriberWidget の icm.ReceiveEvent にワイヤリングされているので、icm.ReceiveEvent をサブスクライブしたときに実行される handleReceiveEvent 関数が実行されます。handleReceiveEvent 関数は、サブスクライブしたイベントのペイロードを表示します (図 29)。

図 28. ICMEventPublisherWidget および ICMEventSubscriberWidget の実行前
図 29. ICMEventPublisherWidget および ICMEventSubscriberWidget の実行後

Eclipse plugin

以前の developerWorks 記事「IBM Case Manager プロパティー・ビューにおけるカスタム・エディターの開発」で、Eclipse プラグインを紹介しています。この Eclipse プラグインでは、プロパティー、カスタム・アクション、およびイベントの記述も生成することができます。自動で生成されたコードを元に開発を進めることによって、初期の煩雑な依存関係やケアレスミスを軽減でき、開発の効率化の助けになることでしょう。インストールおよび使用方法については前記事を参照してください。

まとめ

ここでは、プロパティー、カスタム・アクション、イベントについて説明しました。これらを使用することによって、カスタム・ウィジェットをより汎用的で再利用可能なものにでき生産性向上が期待できます。また、カスタム・アクションやイベントを定義することで、より複雑な画面を簡単に作成することができるようになります。

前記事へのリンク


ダウンロード可能なリソース


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Information Management, Web development
ArticleID=998297
ArticleTitle=IBM Case Manager カスタム・ウィジェットにおけるプロパティー、カスタム・アクション、およびイベント
publish-date=02192015