本文へジャンプ

Lotus > Lotus Developer Domain > 
　 　
　

IBM Workplace Designerを使用して文書の変更履歴をトラッキングする
　
   
　
コンテンツ
変更履歴の保存
[Project Manager]サンプル・コンポーネントのインポート
projectスキーマとissueスキーマの変更
changeHistoryスクリプト・ライブラリーの作成
updateChangeHistory()関数の呼び出し
変更履歴の表示
更新されたコンポーネントのデプロイとテスト
機能の追加
まとめ
ダウンロード
リソース
筆者について（原文のまま）

John Mackey, Director of Workplace Technologies, E2 Consulting Group
john.mackey@e2cg.com

レベル：初級
原文の掲載：2006年03月28日（2006年04月04日更新）
更新日：2006年10月13日更新
原文はこちら (US)


任意のWorkplace Designerコンポーネントについて、文書の変更履歴を取得し、表示する手法を理解しましょう。XMLを使用してこのデータ取得し、IBM Workplace Designerのより強力なコントロールの1つであるパネル・コントロールを使用してデータを表示できます。

多くのユーザーは、データに加えられた変更をトラッキングしたいと思っています。監査証跡は、電子文書には不可欠の機能です。変更した人、変更された日時、および変更内容は、トラッキングすべき重要なアイテムです。しかし、多くの開発者は、これらの変更を取得することは必ずしも簡単ではなく、面倒な作業になる可能性があること知っています。

Lotus Notes/Domino開発の知識を背景として、私たちは文書の変更履歴を取得するさまざまな手法を試みました。Lotus Notes/Dominoでの一般的な手法は、以前のデータを非表示フィールドに保存し、このフィールドを実際のフィールドと比較して、何が変更されたのかを決める方法です。Lotus DominoをDomino Enterprise Connection Services(DECS)およびIBM DB2と共に用いる場合は、DB2のBefore Updateトリガーを使用して履歴を取得する方法が望ましいでしょう。この手法では、以前に保存されたレコードと、これから保存されるレコードにアクセスし、2つの文書の違いを比較できます。IBM Workplace Designerでは、保存済みの文書の2次コピーを入手し、document.save()を実行する前に2つを比較することで、この手法をシミュレートできることがわかりました。この記事ではこの手法を取り上げ、Workplace Designerを使用して、変更履歴を取得および表示する汎用的な方法について説明します。

この記事は、Workplace Designerアプリケーションの開発者を対象として書かれています。

変更履歴の保存

文書の変更履歴はどこに保存すべきでしょうか。多くの選択肢があります。Lotus Dominoでは、テキスト・フィールドにデータを保存し、「~」などの特殊文字を使用してデータを区別する方法が一般的です。しかし、この方法では、変更をレポートしたり、要素を追加するときに、多くの問題が生じます。別のアプローチとして、各エントリーごとに返答文書を作成する方法も考えられます。Workplace Designer文書の新しいXMLデータ・モデルでは、現在の文書にデータをXML子要素として追加する、というより優れた手法を使用できます。これらの要素は、各文書ごとに1つまたは複数含めることができます。この手法を用いると、データを文書内部に保存しながら、XMLの特性を活かして、データを容易に操作したり、出力することができます。

まず、取得しなければならないデータを定義しましょう。少なくとも必要なのは、次のデータです。

  • タイム・スタンプ：変更が加えられた時点の日付と時刻です。
  • ユーザー名：変更を加えたユーザーです。
  • 説明：変更内容の説明です。

この記事では、IBM Workplace Designerに含まれている[Project Manager]サンプル・コンポーネントに変更を加えます。既存のアプリケーションを用いたことで、アプリケーションを最初から作成しなくても、記事に記載されているコードの適用方法を理解できます。

上に戻る

[Project Manager]サンプル・コンポーネントのインポート

最初に、[Project Manager]コンポーネントをWorkplace Designerにインポートします。Workplace Designer2.6を使用している場合は、次の手順に従って、コンポーネント用に新しいプロジェクトを作成します。

  1. Workplace Designerを開き、[ファイル]-[新規]-[コンポーネント]を選択します。
  2. [サンプル・コンポーネントを使用して開始]オプションを選択します。
  3. リスト・ボックスで[Project Manager]コンポーネントを選択します。
  4. コンポーネントの名前とラベルを入力し、[OK]をクリックします。図1を参照してください。

図1.[新規Workplaceコンポーネント]ダイアログ・ボックス

Workplace Designer2.5を使用している場合は、次の手順に従って、サンプル・コンポーネント用に新しいプロジェクトを作成します。

  1. Workplace Designerを開き、[ファイル]-[インポート]-[コンポーネント]を選択します。
  2. 次の場所にあるサンプル・コンポーネント・ディレクトリーに移動します。
    \WMCがインストールされているディレクトリー\applications\eclipse\plugins\com.ibm.workplace.designer.sampleApps_1.0.0\sampleApps
  3. [Project Manager]コンポーネントを選択します。必要であれば、コンポーネント名を変更します。次に、[OK]をクリックします。図2を参照してください。

図2.[Workplaceコンポーネントをインポート]ダイアログ・ボックス
上に戻る

projectスキーマとissueスキーマの変更

サンプル・コンポーネントをインポートした後は、最初の作業として、projectスキーマとissueスキーマを変更し、changeHistory子要素を追加します。Workplace Designer2.5および2.6のどちらでも、次の手順に従います。

  1. Workplace Designerで、[コンポーネントナビゲータ]から、コンポーネントの[スキーマ]を選択し、展開します。
  2. projectスキーマをダブルクリックして開きます。
  3. [ルート要素]タグで、project要素を直接選択します。
  4. [要素]-[要素を追加]-[子として]を選択します。プロジェクトを右クリックして、これらのメニュー項目を選択することもできます。
  5. 要素にchangeHistoryという名前を付け、デフォルトのstringを型として受け入れます。
  6. changeHistoryを選択し、[要素]-[要素を追加]-[子として]を選択します。
  7. 名前にtimestampを入力し、要素の型としてdateTimeを選択します。
  8. username要素とdescription要素にも、この手順を繰り返します(どちらもstring型です)。スキーマは、図3のように表示されます。

    図3.新しいスキーマ


  9. 変更を保存します。
  10. issueスキーマについても、上記の2〜7の手順を繰り返します。
上に戻る

changeHistoryスクリプト・ライブラリーの作成


コードをスクリプト・ライブラリーに保存すると、コードの維持が容易になり、フォーム間でコードを共有できます。コーディングを開始する前に、文書の変更履歴を取得する手順について考えてみましょう。

  1. 文書の検証後、かつdocument.save()イベントが発生する前に、updateChangeHistory()関数を呼び出します。
  2. この関数は、最初にこれが新規文書であるかどうかをチェックします。新規文書の場合は、作成日時と作成者名を記録します。
  3. 既存の文書の場合は、現在の文書のIDを使用してオリジナル文書のコピーを取得します。
  4. 次に、キー・フィールドを比較して、変更されたかどうかを判断します。
  5. 変更がある場合、または新規文書の場合は、DOMDocumentのaddContent()メソッドを使用して新しいchangeHistory要素を挿入します。

すべてのフォーム・フィールドで変更を比較する必要はありません。通常、ユーザーが変更履歴をトラッキングしたいのは、いくつかのキー・フィールドです。定期的に変更されるフィールドがあるかもしれませんが、収集する履歴のサイズを不必要に増加させたくありません。projectフォームでは、ユーザーが変更履歴を知りたいフィールドとして、Project Name、Status、Manager、Budget、Status Updateを選択しました。issueフォームでは、Type、Owner、Priorityについて変更をトラッキングします。

では、コーディングを開始しましょう。

  1. Workplace Designerで、[コンポーネントナビゲータ]から、コンポーネントの[スクリプト]を選択し、展開します。
  2. [スクリプトライブラリ]をダブルクリックして開きます。
  3. [新規スクリプトライブラリ]ボタンをクリックします。
  4. ライブラリーにChangeHistoryという名前を付けます。
  5. 資料ファイル「changeHistoryスクリプト」に記載されているコードを入力します。
  6. 変更を保存します。

このコードでは、比較が必要な2つのデータ型のために、2つのヘルパー関数を作成しました。1つはstring値を比較する関数で、もう1つはdouble値を比較する関数です。date値などの他の型を比較したいときは、追加の関数を作成する必要があります。

もう1つ注目したいのは、compareDoubleValues()関数でdouble値をstring値に変換するために、I18nクラスを使用している点です。このクラスは、国際化対応のためのさまざまなメソッドを提供します。これには、書式設定や値を変換する多くのメソッドが含まれています。この記事で扱うサンプルでは日付の書式を設定する関数は使用しませんが、これらの関数は役に立ちます。スキーマ内の日付/時刻の値は、インターナショナル形式で保存されています。XMLスキーマからフォーム・フィールドに日付を表示するときは、Workplace Designerがユーザーに代わって日付の形式を自動的に処理します。XMLの日付をJavaScriptで使用するときは、I18nクラスを使用してこれらの日付の書式を設定できます。


function compareStringValues(theField,theFieldDesc,currentDoc,theOrigDoc,theUser,theTimeStamp,buildDescFlag){
	//initialize theDescription string variable to hold our change description
	var theDescription="";						

	if (currentDoc.getStringValue(theField)!=theOrigDoc.getStringValue(theField)){
		//build the description
		if (buildDescFlag){		
			theDescription=theFieldDesc + " changed from "+ theOrigDoc.getStringValue(theField)
			_+ " to " + currentDoc.getStringValue(theField);
		//use the passed in description. pass false in when data is too long to track. 
		}else{					
			theDescription=theFieldDesc;
		}
		insertHistory(theUser,theTimeStamp,theDescription,currentDoc);
	}
}

function compareDoubleValues(theField,theFieldDesc,currentDoc,theOrigDoc,theUser,theTimeStamp){
	//initialize theDescription string variable to hold our change description
	var theDescription="";	

	if (currentDoc.getDoubleValue(theField)!=theOrigDoc.getDoubleValue(theField)){
		theDescription=theFieldDesc + " changed from "+ I18n.toString(theOrigDoc.getDoubleValue(theField))
		_+ " to " + I18n.toString(currentDoc.getDoubleValue(theField));
		insertHistory(theUser,theTimeStamp,theDescription,currentDoc);
	}
}

insertHistory()関数について、注目していただきたい点があります。Workplace Designer製品のマニュアルでは、addContent()メソッドの構文は次のように記載されています。

addContent(content:DOMContent) : DOMDocument
addContent(n:int, content:DOMContent) : DOMDocument

このメソッド仕様の2番目のバージョンでは、最初のパラメーターは整数値です。この値は、DOMツリーにおけるこの要素の位置に関連します。たとえば、次のように整数値1を指定したとします。

currentDoc.getRootElement().addContent(1,history);

このhistory要素は最初の位置に置かれ、以前の各要素はそれぞれ1つ位置が下がることになります。これにより、historyの変更は降順、つまり最新の変更が一番上になるように保存されます。この方法を用いると、データのソートが必要ないので、後でデータを表示するときも簡単です。


function insertHistory(theUser,theTimeStamp,theDescription,currentDoc){
	//create a new DOMElement object for our history
	var history = new DOMElement("changeHistory");			

	//set the user element
	history.setStringValue("userName",theUser);
	//set the timeStamp				
	history.setDateValue("timeStamp",theTimeStamp);
	//set the description of the change			
	history.setStringValue("description",theDescription);		
	
//Here is where we add the history object to our current document.  

	currentDoc.getRootElement().addContent(1,history);	
	print("<<<<adding content history");
}

メモ：changeHistoryのすべてのコードについては、資料ファイル「changeHistoryスクリプト」を参照してください。

上に戻る

updateChangeHistory()関数の呼び出し


次に、新しい関数を呼び出すためにProjectEditフォームとIssueEditフォームを変更します。updateChangeHistory()関数は、短いコードで呼び出すことができます。Workplace Designer 2.5の[Project Manager]サンプル・コンポーネントは、2.6のサンプル・コンポーネントと少しだけ異なります。2.6には、検証を行うコードが追加されています。

Workplace Designerで、コンポーネントの[フォーム]を展開してProjectEditフォームを開き、ProjectEditフォームをダブルクリックします。Workplace Designer2.5の場合は、次の手順で操作します。

  1. 画面を下方向にスクロールし、[OK]をクリックします。
  2. [プロパティ]ペインで、[基本]タブを選択します。
  3. ボタンの種類をSubmitからSimpleに変更します。ボタンがクリックされたときに追加の関数を実行するため、この操作が必要となります。
  4. 次に、[イベント]タブを選択します。
  5. onClickイベントを選択します。
  6. 次のコードを入力します。
    
import ChangeHistory;
import NavigationScripts;
updateChangeHistory(document);
saveCurrentDocument(document, context, "DepartmentProjectStatus.xsp");
  7. 変更を保存します。図4を参照してください。

図4.ProjectEditフォームの[イベント]タブ

Workplace Designer2.6の場合は、次の手順で操作します。

  1. 画面を下方向にスクロールし、[OK]をクリックします。
  2. [イベント]タブを選択します。
  3. onClickイベントを選択します。
  4. 既存のスクリプトの一番上に、次のコードを入力します。
    import ChangeHistory;
  5. 「saveCurrentDocument(document,context,"DepartmentProjectStatus.xsp");」の行の上に、次のコードを入力します。
    updateChangeHistory(document);
  6. 変更を保存します。

ProjectEditフォームを変更した後、IssueEditフォームを開きます。Workplace Designer2.5の場合は、次の手順で操作します。

  1. 画面を下方向にスクロールし、[OK]をクリックします。
  2. [イベント]タブを選択します。
  3. onClickイベントを選択します。
  4. 「import NavigationScripts;」の下に、次のコードを入力します。
    import ChangeHistory;
    updateChangeHistory(document);
  5. 変更を保存します。図5を参照してください。

図5.IssueEditフォームの[イベント]タブ

Workplace Designer2.6の場合は、次の手順で操作します。

  1. 画面を下方向にスクロールし、[OK]をクリックします。
  2. [イベント]タブを選択します。
  3. onClickイベントを選択します。
  4. 既存のスクリプトの一番上に、次のコードを入力します。
    import ChangeHistory;
  5. 「saveCurrentDocument(document,context,"ProjectEdit.xsp");」の行の上に、次のコードを入力します。
    updateChangeHistory(document);
  6. 変更を保存します。

この時点で、アプリケーションは、指定されたフィールドへの変更を記録し始める準備が整っています。

上に戻る

変更履歴の表示

文書の変更履歴を記録できるようになったので、次の課題は、履歴データをフォームに表示することです。Workplace Designerで最も強力なUIコントロールの1つに、パネル・コントロールがあります。パネル・コントロールには他のUIコントロールを含められ、特定の条件に基づいて内部のコンテンツを繰り返すことができます。ここでは、パネル・コントロールを使用して、現在の文書に関するすべての変更履歴の要素が格納されたフィールドを含む表を繰り返します。

表とパネルの使用

フォーム内にある他の表と同じ表を作成する最も簡単な方法は、既存の表をコピーすることです。project表(最初の表)をコピーし、フォームの一番下に貼り付けます。2番目の行に埋め込まれた、ラベルとフィールドを含む表を削除します。新しい表は、図6のように表示されます。

図6.新しい表

新規文書の場合は、履歴の表を非表示にします。表の[基本]タブを選択します。[表示]プロパティーで、計算結果を選択し、次の式を入力します。

!@IsNewDoc();

次に、表のタイトルを設定します。表内の最初の行の計算結果フィールドをクリックし、[値]タブをクリックします。現在のスクリプトをDocument Historyで置き換えます。ここに、履歴データを繰り返すためのパネル・コントロールを挿入します。カーソルを2番目の行に置き、[UIコントロール/コンテナコントロール]パレットからパネルをドラッグ・アンド・ドロップします。パネルの幅を100%に設定します。[データ]タブをクリックし、[このパネルのデータソースを指定する]オプションを選択します。[データソース]を文書に設定します。ドロップダウン・リストからProjectスキーマを選択します。[データコンテキスト]フィールドに「changeHistory」と入力します(図7参照)。

図7.パネルのプロパティー

[繰り返し]タブをクリックします。[XPathを使用する]オプションを選択し、テキスト・ボックスに「/project/changeHistory」と入力します。次に、パネルに3列の表を挿入します。この表には、表示したい各履歴要素(timestamp、description、username)のために3つのフィールドを配置します。

表コントロールをパネルにドラッグ・アンド・ドロップします。表が1行×3列となるように、1つの行を削除します。表によってパネルのサイズが変更されることがあるので、必要な場合は、後でパネルのサイズを変更します。表の各セルの幅を115、145、320に設定します。

それでは、3つのデータ・フィールドを追加しましょう。編集ボックス・コントロールを最初のセルの上にドラッグ・アンド・ドロップします。編集ボックス・コントロールを選択し、[基本]タブをクリックします。ラベルのテキストを削除します。読み取り専用属性をtrueに設定します。幅を100%に設定します。[データ]タブを選択します。[データのバインド]ドロップダウン・リストでtimeStampを選択します。ドロップダウン・リストにtimeStamp要素が表示されない場合は、パネルのデータまたは繰り返しの入力に問題があると考えられます(実際に筆者が経験しました)。[日付/時刻形式]ドロップダウン・リストで<日付と時刻>を選択します(図8参照)。

図8.編集ボックスのプロパティー

手順を省くために、最初のフィールドをコピーして、2番目のセルに貼り付けます。[データ]タブをクリックします。[データのバインド]ドロップダウン・リストでdescriptionを選択します。[表示タイプ]を[ストリング]に設定します。フィールドの別のコピーを3番目の列に貼り付けます。[データ]タブをクリックし、[データのバインド]ドロップダウン・リストでuserNameを選択します。[表示タイプ]を[ストリング]に設定します。

これでほぼ完成しました。修正が必要なのはあと1点です。繰り返しパネル内で表を使用するとき、余分な線が表示されていました。解決方法は、表の前後の段落を非表示にすることです。表内に余分な線がある場合は、この手順をとばして先に進み、後でもう一度実行することもできます。詳細については、囲みの「余分な線を非表示にする」を参照してください。

余分な線を非表示にする

余分な線を非表示にするには、パネル内で表の上の行をクリックします。ドロップダウン・リストで[段落]を選択し、[表示]プロパティーをfalseに設定します。同じ操作をパネル内の表の下の行にも行います。

これでprojectフォームが完成し、データの変更履歴を表示する準備が整いました。同じ手順をIssueEditフォームに繰り返すか、文書履歴の表をIssueEditにコピーすることができます。この場合、スキーマの選択とパネルのXPath式で、projectスキーマの代わりにissueスキーマを使用する必要があります。

繰り返しパネルを使用する別のサンプルについては、IBM Redpaper『IBM Workplace 2.5 Development with Workplace Designer (US)』を参照してください。

上に戻る

更新されたコンポーネントのデプロイとテスト

更新されたコンポーネントをデプロイし、テストする準備ができました。コンポーネントをサーバーにデプロイするには、新しいプロジェクトを作成し、保存します。次に、プロジェクトを編集し、一部のフィールドを改訂します。結果は図9のようになります。

図9.新しいコンポーネントのデプロイ

上に戻る

機能の追加

文書の変更履歴を取得し、表示できるようになると、履歴が比較的早く増加することに気付くかもしれません。そこで、文書履歴表の表示/非表示をユーザーが選択できる機能が欲しくなります。この機能は、クリックしたときにsessionDataへの変数を設定するラベルをユーザーに表示することで追加できます。この変数を使用して、履歴表全体の表示と非表示を切り替えます。

ラベル・コントロールを文書履歴表の上にドラッグ・アンド・ドロップします。ラベルを選択し、[基本]タブを選択します。ラベル・プロパティーを「+ Show Document History」に変更します。表示プロパティーでは、計算結果を選択し、次の式を入力します。

sessionData.showHistory!=true & !@IsNewDoc();

[イベント]タブで、onClick()イベントを選択します。ドロップダウン・リストでJavaScriptを選択し、[サーバー上で実行]オプションを選択します。次のスクリプトを入力します。

sessionData.showHistory = true;

[フォーマット]タブで、色をRGB{80,121,183}に設定します。この色は、ProjectEditフォームの他のタイトルと一致します。これについて、カスタムの色を定義する必要があります。[スタイル]を太字に設定します。

次に、表を非表示にする2番目のラベルを作成します。先ほど作成したラベルの下に、別のラベル・コントロールをドラッグ・アンド・ドロップします。ラベルを選択し、[基本]タブを選択します。ラベル・プロパティーを「- Hide Document History」に変更します。表示プロパティーでは、計算結果を選択し、次の式を入力します。

sessionData.showHistory==true & !@IsNewDoc();

[イベント]タブで、onClick()イベントを選択します。ドロップダウン・リストでJavaScriptを選択し、[サーバー上で実行]オプションを選択します。次のスクリプトを入力します。

sessionData.showHistory = false;

[フォーマット]タブで、色をRGB{80,121,183}に設定します。[スタイル]を太字に設定します。

次に、文書履歴表の表示プロパティーの式を変更します。表を選択し、[基本]タブを選択します。表示プロパティーで計算結果を選択します。これを次のように変更します。

!@IsNewDoc() & sessionData.showHistory;

文書が開いたときに、履歴表をデフォルトで非表示にするために、PostOpenDocument() イベントでshowHistoryセッション変数をfalseに再設定します。これを行うには、まず、[フォーム]プロパティーを選択します。[イベント]タブを選択し、onPostOpenDocument()イベントを選択します。ドロップダウン・リストでJavaScriptを選択し、[サーバー上で実行]オプションを選択します。次のスクリプトを入力します。

sessionData.showHistory=false;

「+ Show Document History」ラベル、「- Hide Document History」ラベル、および新しい式を持つ[イベント]タブが表示されたフォームを図10に示します。

図10.表の表示プロパティーのデフォルトの設定

もう1つ考慮が必要な点は、繰り返しパネルによって表示されるデータの量を制限することです。パネルの[繰り返し]タブには、[最大繰り返し回数]の設定があります。必要であれば、この設定に整数値を入力します。

上記の変更内容をIssueEditフォームにもコピーすると、新しい機能をサーバーにデプロイする準備が完了します。試してみてください。

上に戻る

まとめ

この記事では、フォーム・データへの変更を取得し、変更内容をXML子要素に保存する簡単な手法について説明しました。Workplace Designerには、このデータを容易に繰り返し、フォームへ配置することを可能にするパネル・コントロールが用意されています。この記事で紹介した手法を読み、実際に作業を行うことにより、パネル・コントロールとXMLn子要素の豊富な活用方法を理解できます。

上に戻る

ダウンロード

説明 ファイル名 サイズ ダウンロード方法
サンプルWDCファイル ProjectManager26.wdc ProjectManager26.wdc HTTP
ダウンロード方法について(US)
Adobe® Reader®が必要

上に戻る

リソース

学ぶ
製品とテクノロジーを手に入れる
議論する
上に戻る

筆者について（原文のまま）

John Mackey is the Director of Workplace Technologies at E2 Consulting Group (http://www.e2cg.com). He works extensively with the IBM Workplace and IBM WebSphere Portal product lines and has over ten years experience with Lotus Notes. When he’s not working on Workplace applications, he enjoys spending time with his wife, his three children, and their Jack Russell terrier. He can be reached at john.mackey@e2cg.com.

上に戻る