キーの使用法
Zen Mojo には、ユーザとの対話を駆動するために使用できるキーのシステムが用意されています (第 1 章の概要を参照)。この章では、このシステムの使用方法について説明します。以下のトピックについて説明します。
開発の早い段階で、必ずキーの名前付け規約を定義してください (このドキュメントの “名前付け規約” を参照)。
考えられるアプローチ
キーは、さまざまな方法で使用できます。このセクションでは、2 つの主なアプローチについて説明します。複合的なアプローチやそれ以外のアプローチも可能です。
1 つの documentView を別の documentView から駆動する
このアプローチでは、pageContents 領域に 2 つの documentView コンポーネントがあり、そのうちの 1 つ (通常は左または上のコンポーネント) がもう 1 つ (通常は右または下のコンポーネント) を駆動します。
一般的なシナリオでは、1 つの documentView (A) に一連のボタンまたはメニューが含まれており、それぞれに一意のキーが設定されています。ユーザがこの documentView 内の項目を選択すると、onselect() イベント・ハンドラが以下を実行します。
-
documentView A から現在のデータ・キー、レイアウト・キー、またはその両方を取得します。
-
取得したキーに基づいて、もう 1 つの documentView (B) のデータ・キー、レイアウト・キー、またはその両方を設定します。
onselect() の内部では、選択された項目の現在の値も入手できるため、ロジックでその情報を使用することもできます。
-
documentView B のレイアウトを更新します。
すべてのページ・マネージャで複数の documentView がサポートされるわけではありません。
ドキュメント・スタックを使用する
Zen Mojo では、ドキュメント・スタックもサポートされます (“ドキュメント・スタックの操作” を参照)。
ドキュメント・スタックのアプローチでは、pageContents 領域に documentView コンポーネントが 1 つだけ含まれています。一般的なシナリオでは、ユーザが項目を選択すると、onselect() イベント・ハンドラが以下を実行します。
-
現在のデータ・キー、レイアウト・キー、またはその両方を取得します。
-
取得したキーに基づいて、pushDocument() を呼び出してドキュメント・スタックに新しいバージョンを追加し、それを documentView 内に表示します。[戻る] ボタンを含むヘッダが Zen Mojo によって自動的に追加されます。ユーザはこのボタンを使用してアプリケーションの前のスタック・レベルに戻ることができます。
onselect() の内部では、選択された項目の現在の値も入手できるため、ロジックでその情報を使用することもできます。
ドキュメント・スタックはブラウザの履歴スタックとは異なることに注意してください。Zen Mojo には、ブラウザの履歴スタックを管理するために使用できる別の一連のツールが用意されています。
pushDocument() および関連するメソッドの詳細は、“ドキュメント・スタックの操作” を参照してください。
documentView の初期キーの指定
documentView の初期キーを指定するには、ページ・クラスに含まれる <mojo:documentView> 要素の次のプロパティのいずれかまたは両方を指定します。
-
initialLayoutKey — この documentView の初期レイアウト・キー
-
initialDocumentKey — この documentView の初期データ・キー
どちらのプロパティも、home が既定値です。
以下に例を示します。
<:mojo:documentView id="mainView"
developerMode="true"
initialDocumentKey="initialKey"
initialLayoutKey="initialKey"
ongetlayout = "return zenPage.getContent('layout',key,criteria);"
ongetdata = "return zenPage.getContent('data',key,criteria);">
...
<:/mojo:documentView>
キーの設定とレイアウトの更新
documentView インスタンスのキーを設定し、その documentView のレイアウトを更新するには、適切なクライアント・メソッド内で以下を実行します。
-
構文 zen('docViewId') を使用して、特定の ID を持つ documentView を参照します。
-
その documentView の setDocumentKey() メソッド、setLayoutKey() メソッド、またはその両方を呼び出します。
-
その documentView の updateLayout() メソッドを呼び出します。
以下に例を示します。
var docView = zen('mainView');
docView.setDocumentKey(key);
docView.updateLayout();
以下のリストでは、これらのメソッドの詳細について説明します。
ClientMethod setDocumentKey(key, criteria, level) [ Language = javascript ]
(ドキュメント・スタックの特定のレベルで) データ・オブジェクトのキーとオプションの条件を設定します。引数は以下のとおりです。
-
key は、コンテンツの特定のバージョンを示す短い一意の名前です。
-
criteria は、使用するテンプレートに関する追加情報を含む文字列またはオブジェクトです。例えば、ユーザが入力した検索文字列を指定できます。または、コードの内部で使用される複数のプロパティを含むオブジェクトを指定することもできます。
Zen Mojo が criteria 引数を直接使用することはありません。この引数は、クライアント・メソッド (通常は ongetdata および ongetlayout コールバックと呼ばれるメソッド) 内で使用できます。使用例は、この章の “criteria 引数の使用” を参照してください。
-
level は、キーと条件を設定する (ドキュメント・スタックの) レベルです。(各 documentView で、ドキュメント・スタックのレベルごとにデータ・オブジェクトに対して固有のキーと条件を設定できます。)
pushDocument() や popDocument() などのメソッドを使用しない場合は、この引数を無視できます。ドキュメント・スタックの詳細は、“ドキュメント・スタックの操作” を参照してください。
このメソッドは、(ドキュメント・スタックの特定のレベルで) キャッシュも無効化します。レイアウトを更新するには、後述する updateLayout() を使用します。
ClientMethod setLayoutKey(key, criteria, level) [ Language = javascript ]
(ドキュメント・スタックの特定のレベルで) レイアウト・グラフのキーとオプションの条件を設定します。使用する引数は setDocumentKey() とほぼ同じですが、setLayoutKey() がデータ・オブジェクトではなくレイアウト・グラフで使用されるキーと条件に影響する点が異なります。
このメソッドは、(ドキュメント・スタックの特定のレベルで) キャッシュも無効化します。レイアウトを更新するには、次に説明する updateLayout() を使用します。
ClientMethod updateLayout(effect) [ Language = javascript ]
現在のデータ・キー、レイアウト・キー、および条件を使用して documentView の ongetdata および ongetlayout コールバックを呼び出します (つまり、現在のレイアウトを更新します)。
effect 引数は、使用する遷移効果を指定します (既定のページ・マネージャを使用する場合)。他のページ・マネージャでは、この引数は無視されます。この引数には、'fade'、'fade-flakes'、または 'fade-tiles' を指定できます。
criteria 引数の使用
このセクションでは、criteria 引数の使用例を示します。最初の例では、クライアント・メソッドで criteria 引数として使用するオブジェクトを作成します。
var reqId = {HistoryStart:this.historyStart,HistoryEnd:this.historyEnd};
reqId.SessionID = data.SessionID;
reqId.SessionMRN = data.SessionMRN;
docView.setDocumentKey(key,reqId);
docView.updateLayout();
次の例では、ユーザが入力した検索語とレイアウト・グラフで内部的に使用されるプロパティを含む criteria オブジェクトを作成します。
docView.setDocumentKey(key,{term:this.searchTerm, initLoad:true});
docView.setLayoutKey(key);
docView.updateLayout('fade');
criteria 引数は、%OnGetJSONContent() メソッド内で pCriteria として使用できます。以下の例で、%OnGetJSONContent() メソッドは最初に pCriteria がオブジェクトであることを確認し、次にサーバからデータを取得するために使用するプロパティをそこから抽出します。
if $IsObject(pCriteria) {
set tDocId=pCriteria.docId }
else {
set tDocId=""
}
///use tDocId to retrieve specific data, if applicable
documentView のキーの取得
Zen Mojo には、特定の documentView の現在のデータ・キーとレイアウト・キーを取得するために使用できるメソッドも用意されています。これらのメソッドは、documentView インスタンスのメソッドです。これらのメソッドを以下に示します。
ClientMethod getDocumentKey() [ Language = javascript ]
(ドキュメント・スタックの現在のレベルで) この documentView のデータ・キーを返します。
ClientMethod getLayoutKey() [ Language = javascript ]
(ドキュメント・スタックの現在のレベルで) この documentView のレイアウト・キーを返します。
ドキュメント・スタックの操作
ドキュメント・スタックを操作するには、documentView インスタンスのメソッドを呼び出します。クライアント・メソッドからこれらのメソッドのいずれかを呼び出すには、次の 2 つの手順を使用します。
var mainView = zen('mainView');
mainView.methodname();
1 行目の zen('mainView') は、ID が mainView である documentView への参照です。2 行目では、その documentView に関連付けられたメソッドを呼び出します。
ClientMethod getLevel() [ Language = javascript ]
現在のドキュメント・スタック・レベルを返します。初期のスタック・レベルは 0 です。pushDocument() を使用すると、レベルが 1 つインクリメントされます。popDocument() を使用すると、レベルが 1 つデクリメントされます。
ClientMethod popAll(render,clearDataCache) [ Language = javascript ]
元のドキュメントを除くすべてのドキュメント・バージョンを削除し、表示を更新し、ドキュメント・スタック・レベルを 0 に設定します。render が True の場合、このメソッドは新たに表示される以前のドキュメント・バージョンを再レンダリングします。clearDataCache が 1 の場合、このメソッドは現在表示されているパネルのキャッシュをクリアします。
ClientMethod popDocument(render,clearDataCache) [ Language = javascript ]
ドキュメント・スタックから最新のドキュメント・バージョンを削除し、表示を更新し、ドキュメント・スタック・レベルを 1 つデクリメントします。render および clearDataCache の詳細は、popAll() を参照してください。
ClientMethod popDocuments(number, render, clearDataCache) [ Language = javascript ]
ドキュメント・スタックから指定された数 (number) の最新のドキュメント・バージョンを削除し、表示を更新し、ドキュメント・スタック・レベルを必要な数だけデクリメントします。render および clearDataCache の詳細は、popAll() を参照してください。
ClientMethod pushDocument(layoutKey, layoutCriteria, dataKey, dataCriteria) [ Language = javascript ]
ドキュメント・スタックに新しいドキュメント・バージョンを追加し、それを (既定では) 以前のバージョンより前に表示します。新しいドキュメント・バージョンは、指定されたレイアウト・キーと条件およびデータ・キーと条件を使用して、そのレイアウトとデータをフェッチします。dataKey が指定されない場合は、現在のレベルのデータが使用されます。
このメソッドはまた、ドキュメント・スタック・レベルを 1 つインクリメントします。