クライアント側ライブラリ
“クライアント側レイアウト・マネージャ” の章では、Zen に組み込まれている既定のクライアント側レイアウトについて説明しています。またZen では、Zen の既定をオーバーライドして、使用しているアプリケーションのすべてのクライアント側の動作をきめ細かく制御できる、クライアント側ライブラリ・モジュールを提供しています。
このドキュメントで明示的にクライアント側コンポーネントとして指定したコンポーネントを Zen ページで使用する場合、クライアント側ライブラリ・モジュールのすべてのエンティティは自動的に使用可能になります。これらのコンポーネントのリストは、前の 2 つの章 “クライアント側レイアウト・マネージャ” および “クライアント側メニュー・コンポーネント” を参照してください。この場合、クライアント側ライブラリから関数を呼び出すために Zen ページ・クラスに文を追加する必要はありません。これ以外の場合、ページ・クラスまたはアプリケーション・クラスの JSINCLUDES パラメータの値で JavaScript ファイルのリストに文を追加することで、ライブラリを参照できます。次に例を示します。
Parameter JSINCLUDES = "zenCSLM.js";
この章では、Zen クライアント側ライブラリ・モジュールの JavaScript のメソッドおよびプロパティの参照ガイドを提供します。この章では、ライブラリが提供する以下のサポートについて説明します。
規約では、クライアント側ライブラリで定義されたエンティティ名は、ZLM.setDragAvatar または ZLM.getDragInnerDestination のように接頭辞 ZLM の後にドットが続きます。接頭辞 ZLM は、ライブラリ・エンティティと Zen の使用時に定義できる別の関数とを区別するネームスペースと見なすことができます。
ライブラリは、生成されたクラス・ドキュメントを容易にしない JavaScript で記述されているので、InterSystems のオンライン・ドキュメント・システムにはライブラリのクラス・リファレンス・ドキュメントがありません。詳細は、この章を参照してください。
カスタム・ドラッグ・アンド・ドロップ・メソッドの記述
このセクションでは、“カスタム・コンポーネント” の章の “データのドラッグ・アンド・ドロップ・メソッド” セクションに沿って、カスタム・コンポーネントのドラッグ・アンド・ドロップ・メソッドをカスタマイズする際に重要なライブラリの部分について説明します。
以下のテーブルに、zenDragData という JavaScript オブジェクトのメソッドとプロパティを説明します。これらは、dataDrag と呼ばれる特殊変数として %ZEN.Component.componentOpens in a new tab のサブクラスで自動的に使用できるようになっています。
メンバ | 意味 |
---|---|
dataDrag.toString() | この関数は、dataDrag.text プロパティが定義されていれば、その値と同等の文字列を返します。定義されていない場合は、dataDrag.value プロパティを返します。 |
dataDrag.value | 値がドラッグされるコントロールの “ソース”・コントロールの論理値。 |
dataDrag.text | ソース・コントロールの表示値。これが使用できない場合は、論理値が使用されます。 |
dataDrag.sourceComponent | ソース・コントロールへのポインタ。 |
dataDrag.targetComponent | 値がドロップされるコントロールの “ターゲット”・コントロールの論理値。 |
dataDrag.sourceItem | ソース・コントロール内の特定のデータ・フィールドへのポインタ。例えば、コントロールがリスト・ボックスの場合、そこにはいくつかのリストのエントリが含まれている可能性があります。これらのエントリのうちの 1 つだけが、ドラッグされているデータ項目を提供します。 |
dataDrag.targetItem | ターゲット・コントロール内の特定のデータ・フィールドへのポインタ。これは、データ項目がドロップされているフィールドです。例えば、コントロールがリスト・ボックスの場合、リスト内の特定の項目を識別します。 |
Zen クライアント側ライブラリ・モジュールは、カスタム・ドラッグ・アンド・ドロップ・メソッドをサポートする以下の関数を提供します。
ZLM.getDragData
ZLM.getDragData()
dragData という JavaScript オブジェクトへのポインタを返します。このオブジェクトの構造は “データのドラッグ・アンド・ドロップ・メソッド” セクションで説明しています。このオブジェクトには、ドラッグ・アンド・ドロップ操作を実行するのに必要な情報がすべて含まれています。
ZLM.getDragDestination
ZLM.getDragDestination()
現在のドラッグ操作が終了した Zen 要素のエンクロージング <div> へのポインタを返します。
ZLM.getDragInnerSource
ZLM.getDragInnerSource()
現在のドラッグ操作を開始した最も内側のエンクロージング <div> 要素へのポインタを返します。この <div> は、ZLM.getDragSource によって返される Zen 要素のエンクロージング <div> の下位です。
ZLM.getDragInnerDestination
ZLM.getDragInnerDestination()
現在のドラッグ操作が終了した最も内側のエンクロージング <div> へのポインタを返します。この <div> は、ZLM.getDragDestination によって返される Zen 要素のエンクロージング <div> の下位です。
ZLM.getDragSource
ZLM.getDragSource()
現在のドラッグ操作を開始した Zen 要素のエンクロージング <div> へのポインタを返します。
ZLM.setDragAvatar
ZLM.setDragAvatar(newDiv)
ユーザ定義の dragStartHandler がドラッグされているドラッグ・アバターとして使用されるアイコンを設定できるようにします。newDiv 引数は、エンクロージング <div> オブジェクトへのポインタです。これは、以下の例および “データのドラッグ・アンド・ドロップ・メソッド” セクションのその他の例に示すように、ZLM.setDragAvatar を呼び出すために設定できます。
Method dragStartHandler(dragData) [ Language = javascript ]
{
// get drag data
if (!this.getDragData(dragData)) {
return false;
}
// avatar
var icon = this.getEnclosingDiv().cloneNode(true);
icon.style.position="absolute";
icon.style.border ="1px solid darkgray";
icon.style.background ="#D0D0F0";
ZLM.setDragAvatar(icon);
return true;
}
クライアント側コードのデバッグ
このトピックでは、Zen クライアント側の動作専用のコンソール・ウィンドウにメッセージのログを記録することでデバッグをサポートする一連の Zen クライアント側ライブラリ・モジュール関数について説明します。サンプルのメッセージ・コンソール・ウィンドウを以下に示します。この例の出力は、ZLM.cerr および ZLM.dumpObj の呼び出しを反映します。使用可能な関数は 2 つだけです。
メッセージ・コンソール・ウィンドウが前の ZLM.showMsgConsole の呼び出しの結果として開かれていない場合、このセクションで説明されているログ関数には、メッセージ・コンソール・ウィンドウを開く効果があります。開いているメッセージ・コンソール・ウィンドウがあれば、ログ関数はそのウィンドウに記録を続けます。
ログ関数は、クライアント側 JavaScript メソッドからも、次のように &js<> 構文を使用してサーバ側 Zen メソッドからも呼び出せるので非常に便利です。
&js<ZLM.cerr("We are now in a ZenMethod");>
このように、サーバ側とクライアント側の両方の動作で、同じメッセージ・コンソール・ウィンドウに書き込むことができ、両方の実際の動作シーケンスが示されます。ウィンドウは完全な制御がサーバに戻る (フォームが送信されてサーバ専用メソッド %OnSubmit が実行された場合など) まで開いたままになります。その時点でウィンドウは自動的に閉じます。
Zen クライアント側ライブラリ・モジュールは、以下のログ関数を提供します。
ZLM.showMsgConsole
ZLM.showMsgConsole()
エラー・コンソールとして機能する別のウィンドウが開きます。スペースを優先して、モノスペース・フォントを使用するには、このウィンドウを初期化します。デバッグ・ツールとして、このウィンドウは、JavaScript の一連の alert 呼び出しに代わる便利なものです。alert では、メッセージが表示されるたびに、ポップアップ・ウィンドウを閉じなければなりません。このウィンドウは、開いたままで ZLM.cerr の後続の呼び出しで出力されるすべてのテキストを表示します。
ZLM.cerr
ZLM.cerr(msg)
デバッグのために、メッセージ・コンソール・ウィンドウに文字列を出力します。msg 引数は、テキスト文字列です。以下の行をクライアント側 JavaScript メソッドに記述できます。
ZLM.cerr("We are now in a client side method");
ZLM.dumpObj
ZLM.dumpObj(obj)
指定されたオブジェクトのすべての既知のプロパティとそれらの現在の値をメッセージ・コンソール・ウィンドウに出力します。
入力引数 obj は、Zen コンポーネントまたは、配列、関数、またはカスタムデータ構造体などの JavaScript オブジェクトを含む、任意の有効な JavaScript オブジェクトとすることができます。ZLM.dumpObj を使用して配列の内容を表示することの利点は、配列に対して繰り返し処理を設定する必要がないということです。配列オブジェクトを ZLM.dumpObj に入力するだけです。
obj は、Zen ページのコンポーネントまたはそのページ自体を識別します。コンポーネントの有効な obj 値を取得するには、クライアント側関数 zen と、コンポーネント定義で指定された id を使用します。例えば、次のようなコンポーネントがあるとします。
<button id="myFavoriteObject" />
その場合、次のように現在のプロパティをダンプできます。
ZLM.cerr("What's in my favorite object?");
ZLM.dumpObj(zen("myFavoriteObject"));
また、obj は、対象のコンテンツを含む Zen 要素のエンクロージング <div> を指すポインタにすることもできます。この値を取得するには、まずクライアント側関数 zen を、コンポーネント定義で指定された id を使用して呼び出してから、クライアント側コンポーネント・メソッド getEnclosingDiv を呼び出します。その結果、ZLM.dumpObj 関数に入力できる値が得られます。次に例を示します。
var comp = zen("thatComponent");
var div = comp.getEnclosingDiv();
ZLM.dumpObj(div);
ZLM.dumpDOMTreeGeometry
ZLM.dumpDOMTreeGeometry(root)
DOM ノードのツリーの入れ子構造および基本的配置をメッセージ・コンソール・ウィンドウに出力します。root は、表示したいツリーのルートです。root には、JavaScript の観点から有効な任意の DOM ノードを指定できます。これは、<div>、<span>、<input>、<p> などの HTML タグに関連付けられた HTML ソースの任意の部分です。基本的には、コンポーネントの %DrawHTML メソッドを使用して HTML 出力を描画するための Web ビルディング・ブロックです。
DOM ツリー全体を表示するには、root として document.body を使用します。次に例を示します。
ZLM.cerr("What does the DOM for the entire page look like right now?");
ZLM.dumpDOMTreeGeometry(document.body);
また、root は、対象の DOM 構造を含む Zen コンポーネントのエンクロージング <div> を指すポインタにすることもできます。この値を取得するには、まずクライアント側関数 zen を、コンポーネント定義で指定された id を使用して呼び出してから、クライアント側コンポーネント・メソッド getEnclosingDiv を呼び出します。その結果、ZLM.dumpDOMTreeGeometry 関数に入力できる値が得られます。次に例を示します。
var comp = zen("secondGroupFromLeft");
var div = comp.getEnclosingDiv();
ZLM.dumpDOMTreeGeometry(div);
getEnclosingDiv の呼び出しにより、複数の DOM ノードが関連付けられている Zen コンポーネントのラッパとして使用する HTML <div> 要素が返されます。この規約は、DOM ツリーが規則正しく枝分かれするように設計されています。この返り値を ZLM.dumpDOMTreeGeometry の入力として使用する場合、このコンポーネントの %DrawHTML の呼び出しにより作成された HTML 構造のスナップショット、および適用されたスタイルシートや "onload" クライアント側後処理の結果として生じたその構造に対する変更を取得できます。
ZLM.dumpElementStyle
ZLM.dumpElementStyle(div)
指定されたコンポーネントのすべての既知のスタイル・プロパティをメッセージ・コンソール・ウィンドウに出力します。div は、対象のスタイル・プロパティを含む Zen コンポーネントのエンクロージング <div> を指すポインタです。
div の値を取得するには、まずクライアント側関数 zen を、コンポーネント定義で指定された id を使用して呼び出してから、クライアント側コンポーネント・メソッド getEnclosingDiv を呼び出します。その結果、ZLM.dumpElementStyle 関数に入力できる値が得られます。次に例を示します。
var comp = zen("advancedOptions");
var div = comp.getEnclosingDiv();
ZLM.dumpElementStyle(div);