Zen コントロール
Zen コントロールは、Zen フォームに配置するユーザ入力要素です。コントロールはすべて Zen コンポーネントですが、Zen コントロールには、その親クラスである %ZEN.Component.controlOpens in a new tab から派生した独自の特性があります。
最も重要なこととして、各コントロールには value が関連付けられています。value は、そのコントロールの現在の論理値を収めたプロパティです。各コントロールは、この値を表示するか、または内部に保持できます。Zen では、フォームのすべてのコントロール値を、“Zen のフォーム” の章で説明した規則に従って、1 つの単位としてまとめて検証し、送信します。
この章では、以下の内容について説明します。
-
すべての Zen コントロールが共有する特性についての説明
-
“コントロールの属性”
-
“データのドラッグ・アンド・ドロップ”
-
“コントロール・メソッド”
-
-
以下のさまざまなカテゴリのコントロールのレイアウト、スタイル、および動作の各面での違いの識別
-
“ボタン” — <button>、<image>、<submit>
-
“テキスト” — <label>、<text>、<textarea>、<password>
-
“選択肢” — <checkbox>、<multiSelectSet>、<fileUpload>、<colorPicker>、<radioButton>、<radioSet>
-
“リスト” — <select>、<listBox>、<dataListBox>、<combobox>、<dataCombo>
-
“日付” — <calendar>、<dateSelect>、<dateText>
-
“グリッド” — <dynaGrid>、<dataGrid>
-
コントロールの属性
すべての Zen コントロールには、以下の共通属性があります。
属性 | 説明 |
---|---|
Zen コンポーネントの属性 |
コントロールは、あらゆる Zen コンポーネントと同じ汎用属性を持ちます。詳細は、以下のセクションを参照してください。
これらの属性の中で、name はコントロールで特に重要です。フォームの送信時に、コードで (id ではなく) この name を使用して、コントロールの値を取得する必要があります。コントロールに name が指定されていない場合、その値を取得することはできません。 Caché Server Pages で予約されている name 値とのクラッシュを回避するため、文字列 Cache で始まる Zen コントロールの name は使用しないでください。また、name の値では、句読点文字、特にアンダースコア文字 (_) の使用は避けてください。 すべてのコントロール・コンポーネントに適用される情報の詳細は、この章の “データのドラッグ・アンド・ドロップ” および “コントロール・メソッド” を参照してください。 |
clientType |
このコントロールの value に適用されると考えられる、クライアント側 (JavaScript) データ型を示します。既定では、コントロールはその value をクライアント側の正規化が行われない文字列として扱います。しかし、コントロールでは、value の値がクライアント側で文字列以外の値を持つように clientType を設定できます。可能な値は以下のとおりです。
|
controlClass | CSS スタイル・クラスの名前。Zen でこのコントロールをレイアウトすると、このコントロールで表示される主要な HTML 要素に、この値が割り当てられます。 |
controlStyle | CSS スタイル定義を指定した文字列。Zen では、このコントロールで表示される主要な HTML 要素にこのスタイルが割り当てられます。 |
dataBinding | このコントロールをデータ・コントローラに関連付けている場合、この属性は、このコントロールの値を指定する、<dataController> の modelClass に属する特定のプロパティを表します。“モデル・ビュー・コントローラ” の章を参照してください。 |
disabled |
True の場合、このコントロールは無効になります。外観は変わりませんが、ユーザ・アクションに反応しなくなります。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
invalid |
このコントロールの値が無効であることがわかっている場合は、True に設定します。Zen フォームの検証ロジックでは、この設定を行うことによって、コントロールの値が無効であることが判別できるようにコントロールを表示できます。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
invalidMessage |
invalid が True の場合に表示されるメッセージ・テキスト。既定値は以下のとおりです。 out-of-range or invalid value. この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
— |
このテーブルで、以下のいくつかの属性 (属性名が “on...” で始まるもの) は、コントロールに関連するユーザ・アクションのイベント・ハンドラを表します。Zen は関連するイベントが発生したときに、ハンドラを呼び出します。“Zen コンポーネントのイベント・ハンドラ” を参照してください。 |
onblur | コントロールがフォーカスを失うとトリガされます。 |
onchange | コントロールの値が変更されるとトリガされます。コントロールは、このイベントを間接的にトリガします。実際の onchange イベントは、このコントロールを所有するフォームに変更を通知する組み込みハンドラに送信されます。 |
onclick | コントロールでマウスをクリックするとトリガされます。 |
ondblclick | コントロールでマウスをダブルクリックするとトリガされます。 |
onfocus | コントロールがフォーカスを取得するとトリガされます。 |
onkeydown | このコントロールにフォーカスがあるときに、ユーザがキーを押すとトリガされます。対応する onkeyup は、ユーザがキーを離すとトリガされます。 |
onkeypress | このコントロールにフォーカスがあるときに、ユーザがキーを押した後に (つまり、ユーザがキーを押してから離した後に) トリガされます。 |
onkeyup | このコントロールにフォーカスがあるときに、キーを離すとトリガされます。 |
onmousedown | コントロールの領域内でマウス・ボタンを放すとトリガされます。 |
onmouseout | マウス・ポインタがコントロールの領域を離れるとトリガされます。 |
onmouseover | マウス・ポインタがコントロールの領域に入るとトリガされます。 |
onmouseup | コントロールの領域内でマウス・ボタンを押すとトリガされます。 |
onsubmit | このコントロールが属するフォームが送信されるとトリガされます。これにより、コントロールは送信する値を指定または変更できます。 |
onvalidate | このコントロールの値が親フォームで検証されるとトリガされます。 |
— | (イベント・ハンドラを表す属性リスト終わり) |
originalValue |
ユーザが変更する前の、このコントロールの元の値。変更されたコントロールを検出するために使用します。フォームを表示するときに自動的に初期化されるという点で、これは特殊な値です。 クライアント側では、このプロパティには直接アクセスしません。代わりに、クライアント側メソッドである getProperty および setProperty を使用します。クライアント側で (setProperty を使用して) originalValue プロパティを設定すると、このコントロールの現在の value はリセットされます。 |
readOnly |
True の場合、このコントロールは読み取り専用です。ユーザはこのコントロールの値を変更することはできませんが、コントロールが属するフォームが送信されても、コントロールはフォームに表示されたまま、このコントロールの値も送信します。readOnly を True に設定すると、コンポーネントが事実上無効になります。これは、コントロールの選択に関する標準的な HTML 動作です。readOnly の既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
required |
True の場合、このコントロールは必須です。つまり、ユーザはこのコントロールに値を指定する必要があります。指定しないと、既定のフォーム検証ロジックが失敗します。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
requiredMessage |
必須のコントロールに値が設定されていない場合に、フォーム検証メソッドによって警告ボックスに表示されるメッセージ・テキスト。既定の requiredMessage テキストは、以下のとおりです。 required. この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
tabIndex | HTML の tabIndex 属性の値を指定するために使用する整数。ブラウザでは、フォームにあるコントロールのタブ順序をこの属性で制御します。 |
value |
このコントロール内に表示される既定値。フォームを表示するときに自動的に初期化されるという点で、これは特殊な値です。value の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 クライアント側では、このプロパティには直接アクセスしません。代わりに、クライアント側メソッドである getValue および setValue を使用します。 |
データのドラッグ・アンド・ドロップ
すべての Zen コントロールは、以下のようにデータのドラッグ・アンド・ドロップ機能をサポートします。
-
データのドラッグ・アンド・ドロップ機能は、含まれる <page> の dragAndDrop 属性が True に設定されているときのみ有効です。
-
カーソルをコントロールの上に置いた状態でユーザがマウス・ボタンをクリックし、ボタンを押したままでマウスをコントロールから離すと、コントロールからのデータのドラッグが発生します。データのドラッグにより、ドラッグ操作が開始されたコントロールの現在の値が取得されます。論理値と表示値が異なる場合、データの取得の際にこの違いは保持されます。コントロールに複数の値がある場合 (複数の項目を表示するリストなど)、取得される値はユーザがマウス・ボタンをクリックしたときにカーソルが置かれていたリスト項目の値です。データのドラッグ機能は、ドラッグが開始されたコントロールの dragEnabled 属性が True に設定されているときのみ有効です。
-
別のコントロールからのドラッグ操作の後にユーザがマウス・ボタンを解放すると、コントロールへのデータのドロップが発生します。データのドロップにより、ドロップが発生したコントロールの論理値と表示値が、ドラッグされた値と置き換えられます。コントロールに複数の値がある場合 (複数の項目を表示するリストなど)、“ドロップ” 操作によって、ユーザがマウス・ボタンを解放したときにカーソルが置かれていた特定のリスト項目に値がドロップされます。データのドロップ機能は、ドロップが終了されたコントロールの dropEnabled 属性が True に設定されているときのみ有効です。
Zen コントロールのデータのドラッグ・アンド・ドロップの構成方法の詳細は、以下のセクションを参照してください。
-
"Zen の使用法" の “Zen コンポーネントの概念” の章の “ドラッグ・アンド・ドロップ” では、すべてのタイプのドラッグ・アンド・ドロップ操作を紹介しており、Zen ページに配置したコントロールでデータのドラッグ・アンド・ドロップ機能を有効にする方法と構成する方法を説明しています。簡単に言うと、この機能は dragEnabled 属性と dropEnabled 属性を True に設定することで有効にできます。これを行ったうえで、onafterdrag 属性、onbeforedrag 属性、ondrag 属性、および ondrop 属性を設定することにより、この機能を動作させる具体的な方法を構成できます。各コントロールには独自のドラッグ・アンド・ドロップの処理方法があるため、特別な構成は必ずしも必要ではありませんが、構成することも可能です。
-
"Zen アプリケーションの開発" の “カスタム・コンポーネント” の章にある “データのドラッグ・アンド・ドロップ” では、固有のドラッグ・アンド・ドロップ動作を持つカスタム・コントロール・コンポーネントの記述方法について説明しています。このようなコンポーネントを記述すると、あるコントロールに特別なドラッグ・アンド・ドロップ動作が必要な場合、開発者が onafterdrag 属性、onbeforedrag 属性、ondrag 属性、および ondrop 属性を設定してコントロールを構成しなくても、Zen ページにそのコントロールが配置されるたびに目的の動作が一貫して適用されます。
-
この章の “リスト” セクションの “<listBox> のドラッグ・アンド・ドロップ” では、<listBox> コントロールを使用して、ユーザがドラッグ・アンド・ドロップ動作によってリスト内のエントリの順序を変えたり、リスト間でエントリを移動したりする方法を説明しています。データのドラッグ・アンド・ドロップに加えて、このような機能も <listBox> ではサポートしています。
-
ほとんどの場合、データのドラッグ・アンド・ドロップは、それぞれが論理値と表示値を持つコントロール・コンポーネントのみに適用されます。ただし、コントロールではない <dynaTree> に対してもデータのドラッグを実行できます。これは、<dynaTree> のノードが実際にはそれぞれ論理値と表示値を持つためです。詳細は、“ナビゲーション・コンポーネント” の章にある “<dynaTree> のドラッグ・アンド・ドロップ” を参照してください。
コントロール・メソッド
各コントロールには、内部メソッドがあります。この内部メソッドの詳細は、%ZEN.Component.controlOpens in a new tab およびそのサブクラスについてのオンライン・クラス・ドキュメントを参照してください。
これらのメソッドで最も重要なものは、コントロールの value の操作に使用するメソッドです。value プロパティは、クライアント側の getProperty メソッドで取得し、setProperty メソッドで設定できます。実際、value だけでなく、“コントロールの属性” に挙げたどのプロパティも、プログラムの中で getProperty と setProperty を使用して扱うことができます。setProperty メソッドを呼び出すことにより、コントロールのコンテンツをページ上にレンダリングする処理など、プロパティ設定に関連するすべてのアクションも発生します。
Zen コントロールには、便利なクライアント側メソッドである getValue と setValue も定義されています。これらは、value プロパティでのみ使用できるので、変更するプロパティを指定する手間が不要です。
テキスト
Zen には、以下のテキストスタイル・コントロールが用意されています。
-
“<label>” — テキスト・ラベルを表示します。
-
“<text>” — ユーザがテキストを入力します。
-
“<textarea>” — ユーザが複数行のテキストを入力します。
-
“<password>” — ユーザがテキストでパスワードを入力します。
<label>
<label> コントロールは、静的なテキスト value を受動的に表示します。Zen では、<label> を <form> 上の他のコントロールと共に送信します。<label> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。
<text>
Zen の <text> コントロールは、HTML の <input type="text"> 要素のラッパです。Zen の <text> では、以下のようなテキスト入力ボックスが表示されます。
<text> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <text> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<text> の value はテキストの文字列です。 |
autocomplete | このテキスト・コントロールの値が既定でブラウザによって自動的に入力されるかどうかを示します。 |
maxlength | このテキスト・コントロールにユーザが入力できる最大文字数。 |
placeholder | 入力フィールドに期待される値を説明する短いヒント (例えば、サンプルの値や予想される形式の短い説明) を指定するプレースホルダ。このヒントは、入力フィールドが空のときに、このフィールドに表示されます。 |
size | このテキスト・コントロールの入力領域の HTML の幅を示す整数。既定の size は 20 です。 |
spellcheck | True の場合は、スペルチェックが有効です。これは、HTML5 の属性です。HTML5 準拠のブラウザでのみ正しく動作します。IE10 以降でのみサポートされています。既定値は True です。
spellcheck で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
<textarea>
Zen の <textarea> コントロールは、HTML の <textarea> 要素のラッパです。Zen の <textarea> では、複数行のテキスト入力ボックスが以下のように表示されます。
<textarea> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <textarea> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<textarea> の value は、ユーザの入力内容に応じて、改行文字の扱いを制御できるテキスト文字列です。多くのブラウザでは、区切りのない長いテキスト行 (空白を含まない 4,000 文字を超える行) を適切に処理できません。 |
cols | <textarea> コントロールの列の数。既定値は 19 です。 |
rows | <textarea> コントロールの行の数。既定値は 2 です。 |
spellcheck | True の場合は、スペルチェックが有効です。これは、HTML5 の属性です。HTML5 準拠のブラウザでのみ正しく動作します。IE10 以降でのみサポートされています。既定値は True です。
spellcheck で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
<password>
Zen の <password> コントロールは、HTML の <input type="password"> 要素のラッパです。Zen の <password> は、パスワードのテキスト入力ボックスを表示します。ユーザが <password> コントロールに入力したテキストはすべて、画面に表示されずにドットで表示されます。以下はその例です。
<password> 要素を使用して Zen アプリケーションへのアクセスを制御するユーザ・ログイン・ページの例は、"Zen アプリケーションの開発" の “Zen のセキュリティ” の章の “アプリケーションへのアクセスの制御” を参照してください。
<password> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <password> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<password> の value はテキストの文字列です。 |
maxlength | このコントロール内にユーザが入力できる最大の文字数。 |
size | このコントロールの入力領域の HTML の幅を示す整数。既定の size は 20 です。 |
選択
Zen には、以下の選択コントロールが用意されています。
-
“<checkbox>” — ユーザはチェック・ボックスにチェックを付けるか、チェックを外します。
-
“<multiSelectSet>” — ユーザは 1 つ以上のチェック・ボックスにチェックを付けるか、チェックを外します。
-
“<fileUpload>” — ユーザは参照してファイルを 1 つ選択します。
-
“<colorPicker>” — ユーザはパレットから色を 1 つ選択します。
-
“<radioSet>” — ユーザは並んでいるラジオ・ボタンのうち 1 つをクリックします。
-
“<radioButton>” — ラジオ・ボタンをページの任意の場所に配置できます。
<radioButton> と <radioSet> の違いは、<radioSet> のほうがレイアウトが容易である点です。選択肢を簡潔にまとめる場合は、<radioSet> を使用します。ラジオ・ボタンの選択肢の間に情報やイメージを挿入した複雑なページ・レイアウトが必要な場合や、ラジオ・ボタンを縦にまとめて配置する場合には、<radioButton> を使用します。
<checkbox>
Zen の <checkbox> コントロールは、HTML の <input type="check"> 要素のラッパです。Zen の <checkbox> コントロールは、チェック・ボックスの横にキャプションを表示し、そのキャプションのマウス・クリックをチェック・ボックスのクリックとして検出します。HTML のチェック・ボックスとは異なり、Zen の <checkbox> コントロールは、必ず value を送信します。Zen の <checkbox> は、以下のようになります。
<checkbox> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <checkbox> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<checkbox> の clientType は常に "boolean" に設定されています。したがって、<checkbox> の value は、XData Contents およびサーバ側コードでは 1 または 0、クライアント側コードでは True または False の値として表されます。value が 1 または True の場合はチェック・ボックスに現在チェックが付いていること、0 または False の場合はチェックが外れていることを表します。 |
caption |
チェック・ボックスの右に表示されるテキスト。上記の例で使用されているものは、以下のとおりです。 <checkbox caption="Enabled"/> この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 caption の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
captionClass |
caption テキストに適用される CSS スタイル・クラスの名前。既定値は以下のとおりです。 checkboxCaption |
<multiSelectSet>
<multiSelectSet> コントロールは、チェック・ボックスの列を表示し、ひと揃いの選択肢のセットを示します。ユーザは、リストされている選択肢から 1 つ以上選択できます。Zen の <multiSelectSet> は、以下のようになります。
<multiSelectSet> を定義するには、ユーザが選択する valueList を指定します。また、対応する displayList を指定すると、ユーザが確認できるキャプションが表示されます。例えば、前述の例の <multiSelectSet> は、XData Contents で以下の文を指定することで生成できます。
<multiSelectSet displayList="One,Two,Three,Four"
valueList="1,2,3,4" />
<multiSelectSet> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 |
<multiSelectSet> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<multiSelectSet> の value は、現在チェックが付けられている値のコンマ区切りのリストです。項目は、このリストに valueList 内と同じ順序で表示されます。 クライアント側 setValue メソッドを使用して、<radioSet> の value をプログラムで任意の値に設定することも可能です。<multiSelectSet> の value が valueList のどの項目とも一致しない場合、セットのすべてのチェック・ボックスがチェックを外した状態で表示されます。 |
captionClass | この <multiSelectSet> にあるチェック・ボックスのキャプションに適用する CSS スタイル・クラスの名前。既定値は、組み込み CSS スタイル・クラス multiSelectSetCaption です。 |
choiceColumn | dataCombo の choiceColumn 属性と同じ機能を提供します。“<dataCombo> の一般的な属性” を参照してください。 |
displayList |
<multiSelectSet> で表示する選択肢のコンマ区切りリスト。displayList は、valueList が定義されている場合にのみ適用されます。表示値は、実際の論理値に応じて異なる可能性があります。 以下のように、displayList に値が空 ("") である項目が存在するとします。 valueList=",A,B,C" この場合、空の値に該当する追加のチェック・ボックスが 1 つ表示されます。この空の値のキャプションは emptyCaption 属性で指定します。 displayList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる displayList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
emptyCaption |
この <multiSelectSet> の displayList で空の値 ("") が割り当てられているチェック・ボックスに使用する既定のキャプション。emptyCaption を指定しない場合、既定のキャプションは以下のようになります。 なし この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
titleList |
<multiSelectSet> の各チェック・ボックスのツールのヒントを表すテキスト文字列をコンマで区切って並べたリスト。 titleList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる titleList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
valueColumn | dataCombo の valueColumn 属性と同じ機能を提供します。“<dataCombo> の一般的な属性” を参照してください。 |
valueList |
<multiSelectSet> の論理値をコンマで区切ったリスト。valueList (例えば、"A,B,C") に空の値 ("") が存在する場合、その空の値に該当する追加のボタンが 1 つ表示されます。この空の値のラベルは emptyCaption で指定します。 <multiSelectSet> の value は、現在チェックが付けられている値のコンマ区切りのリストです。項目は、このリストに valueList 内と同じ順序で表示されます。displayList を使用して、ユーザに表示する選択肢の対応リストを指定します。 Zen ではセット内の値は互いに異なることが前提となっています。以下のように、valueList に重複する項目が存在するとします。 valueList="A,A,A" この場合、ユーザの選択により発生する動作は予期できません。 |
<fileUpload>
<fileUpload> コンポーネントは、HTML の <input type="file"> 要素の単純なラッパです。Zen の <fileUpload> コントロールは、以下のようになります。
厳密な外観およびコントロール内で使用されるテキストはブラウザによって決定されるため、ブラウザによって異なります。ユーザがファイルを選択すると、“No file chosen” というテキストがファイル名に置き換えられるか、または複数アップロードの場合は選択されたファイルの数を示すテキストに置き換えられます。
ユーザは、ボタンをクリックしてファイル・オープン・ダイアログを開いて目的のファイルに移動してから、ファイルを選択して開きます。次のアクションはブラウザによって異なります。<fileUpload> が含まれたフォームをユーザが送信する際は、一部のブラウザにおいて、<fileUpload> コンポーネントの値はファイル名を含むフル・パス名になります。多くの最近のブラウザでは、この値はファイル名のみになります。ブラウザの開発元は、セキュリティ対策として、このようにフル・パスがわからないようにしています。ブラウザがそのように設計されている場合は、このセキュリティ対策を Zen アプリケーションによって解除することはできません。
ユーザがどのブラウザを選択したかによってZen アプリケーションが影響を受けないようにするには、<fileUpload> コンポーネントの戻り値からフル・パス名を削除します。例えば、<fileUpload> コンポーネントの id が getFile であると想定します。%OnSubmit メソッド内には、次の ObjectScript コード行を記述できます。
ClassMethod %OnSubmit(pSubmit As %ZEN.Submit) As %Status
{
Set file = pSubmit.%GetValue("getFile")
Set file = ##class(%Library.File).GetFilename(file) // strip out the path on IE
// ... other lines of code here ...
Quit $$$OK
}
<fileUpload> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <fileUpload> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<fileUpload> の value はファイルのフル・パス名の文字列です。 |
accept | アップロード可能な MIME タイプのコンマ区切りのリスト。指定した値は、HTML の <input> 要素が持つ accept 属性として使用されます。 |
maxlength | このコントロール内にユーザが入力できる最大の文字数。ユーザがこのコントロールにファイル名を入力することがブラウザによって許可されていた際にこのプロパティが使用されていました。これは主に以前のバージョンの Caché との互換性のために保持されています。 |
multiple | True の場合は、一度に複数のファイルをアップロードできます。既定値は、false です。このプロパティは、HTML5 準拠ブラウザが必要です。 |
size | このコントロールの入力領域の HTML の幅を示す整数。既定の size は 20 です。 |
fileSelect ダイアログは、サーバ上でファイルを選択するメカニズムを提供します。“ファイル選択ダイアログ・ウィンドウ” セクションを参照してください。
<fileUpload> コンポーネントを使用する場合、ほとんどのブラウザで適用されるファイル・アップロード・コントロールの重要なセキュリティ制限について認識する必要があります。以下のパラグラフで、その制限について説明します。
ほとんどの最近のブラウザでは、セキュリティ上の目的で、ファイル・アップロード・コントロールの value フィールドを読み取り専用にしています。その理論的根拠は、その値フィールドがスクリプトを介して設定可能な場合、フォーム送信イベントをそのページ上の別のイベント・ジェネレータと容易にリンクできるということです。そのため、悪質なプログラマであれば、見えないフォームを埋め込み (非表示にする、1 ピクセル四方の領域に切り取るなど)、マウス・ポインタが移動するたびにクライアント・マシンから密かにファイルをコピーするようプログラムするなどということもできます。このため、フォーム送信でアップロードするファイルの値は、ほとんどのブラウザではユーザの直接操作によってのみ設定できます。最近のブラウザではバックグラウンドで値を密かに設定することはできません。
<colorPicker>
<colorPicker> コンポーネントは、色の選択肢を並べて表示します。ユーザは、色をクリックして選択できます。<colorPicker> を使用すると、<colorPane> の複雑なパレットの代わりに簡単な選択方法を提供できます。Zen の <colorPicker> は、以下のようになります。
<colorPicker> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <colorPicker> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<colorPicker> の value は、最近選択した CSS カラー値を表す文字列です。 |
colorList |
コントロール内で左から右へ記述する CSS カラー値のコンマ区切りリスト。既定の colorList 値は、上記の例で示したとおりで、次のようになります。 ",black,gray,darkblue,darkred,darkgreen,blue,red,green,yellow,orange,plum,purple,white" |
<radioSet>
<radioSet> コントロールは、ラジオ・ボタンを並べて表示し、ひと揃いの選択肢のセットを示します。Zen の <radioSet> は、以下のようになります。
<radioSet> の一般的な属性
<radioSet> を定義するには、ユーザが選択する valueList と、ユーザに表示する displayList を指定します。例えば、前述の例の <radioSet> は、XData Contents で以下の文を指定することで生成できます。
<radioSet id="QuarkStatus" name="QuarkStatus"
displayList="Up,Down,Charmed,Strange,Top,Bottom"
valueList="U,D,C,S,T,B"/>
<radioSet> には以下の汎用属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 |
<radioSet> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<radioSet> の value は、セットで現在選択されているボタンの論理値です。この論理値は、<radioSet> の対応する valueList から得られます。 クライアント側 setValue メソッドを使用して、<radioSet> の value をプログラムで任意の値に設定することも可能です。<radioSet> の value が valueList のどの項目とも一致しない場合、セットのすべてのボタンがチェックを外した状態で表示されます。 |
データ・ソースの属性 |
<radioSet> には、データ・ソースを指定するための、<tablePane> に似た属性があります。<radioSet> では、maxRows、queryClass、queryName、および sql がサポートされています。“<radioSet> のクエリ属性” を参照してください。 |
captionClass | この <radioSet> にあるラジオ・ボタンのキャプションに適用する CSS スタイル・クラスの名前。既定値は、組み込み CSS スタイル・クラス radioSetCaption です。 |
choiceColumn | dataCombo の choiceColumn 属性と同じ機能を提供します。“<dataCombo> の一般的な属性” を参照してください。 |
displayList |
<radioSet> で表示する選択肢のコンマ区切りリスト。displayList は、valueList が定義されている場合にのみ適用されます。表示値は、実際の論理値に応じて異なる可能性があります。 以下のように、displayList に値が空 ("") である項目が存在するとします。 valueList=",A,B,C" この場合、空の値に該当する追加のボタンが 1 つ表示されます。この空の値のキャプションは emptyCaption 属性で指定します。 displayList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる displayList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
emptyCaption |
この <radioSet> の displayList で空の値 ("") が割り当てられているボタンに使用する既定のキャプション。emptyCaption を指定しない場合、既定のキャプションは以下のようになります。 なし この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
titleList |
<radioSet> の各ラジオ・ボタンのツールのヒントを表すテキスト文字列をコンマで区切って並べたリスト。 titleList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる titleList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
valueColumn | dataCombo の valueColumn 属性と同じ機能を提供します。“<dataCombo> の一般的な属性” を参照してください。 |
valueList |
<radioSet> の論理値をコンマで区切ったリスト。ユーザがボタンをクリックすると、これらの論理値のうち、そのボタンに対応するものが <radioSet> の value になります。displayList を使用して、ユーザに表示する選択肢の対応リストを指定します。 Zen ではセット内の値は互いに異なることが前提となっています。以下のように、valueList に重複する項目が存在するとします。 valueList="A,A,A" この場合、ユーザの選択により発生する動作は予期できません。 |
<radioSet> のクエリ属性
<radioSet> では、valueList と displayList を指定する代わりに、SQL クエリを使用してそのボタンのデータ・ソースを指定できます。<radioSet> には、そのための属性が多数用意されています。この方法を使用すると、以下のように、クエリにより返される列によって <radioSet> の表示内容が決まります。
-
%ResultSetOpens in a new tab が 1 列の場合、この列の内容は、radioSet 内の論理値と表示値の両方として使用されます。
-
%ResultSetOpens in a new tab が複数列の場合、1 列目の内容が論理値、2 列目の内容が表示値としてそれぞれ使用されます。
<radioSet> には、クエリを使用して結果セットを生成することをサポートするいくつかの属性が用意されています。詳細と例は、“Zen のテーブル” の章にある以下のセクションを参照してください。
-
<radioSet> でクエリ属性を使用する方法
-
データ・ソース (maxRows)
-
SQL クエリの指定 (sql)
-
クラス・クエリの参照 (queryClass、queryName)
-
-
<radioSet> で <parameter> 要素を指定する方法
<radioButton>
Zen の <radioButton> コントロールは、HTML の <input type="radio"> 要素のラッパに拡張機能をいくつか備えたものです。Zen の <radioButton> コントロールには、以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 |
<radioButton> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。 name (id ではありません) は、ラジオ・ボタンとの関連付けを確立します。<radioButton> 要素を XData Contents に追加し、同じ name 値をセット内の各 <radioButton> に割り当てて、関連付けを持つラジオ・ボタンのセットを作成します。 実行時の value には、セット内で現在選択されているボタンの optionValue が必ず設定されています。セット内のいずれかのボタンをユーザが選択すると、Zen ではこのセットの各ボタンの value が、選択されたボタンの optionValue に再設定されます。これにより、セット内のいずれかのボタンの value プロパティをプログラムを使用して確認することで、セット内で現在選択されているボタンを非常に簡単に判断できます。 |
caption |
この <radioButton> のキャプション・テキスト。ユーザが選択肢を識別できるようにするため、セット内の各ボタンには caption が必要です。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 caption の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
captionClass | この <radioButton> のキャプションに適用する CSS スタイル・クラスの名前。既定値は、組み込み CSS スタイル・クラス radioButtonCaption です。 |
optionValue |
この <radioButton> に関連付けられる論理値を定義します。セット内の各ラジオ・ボタンの optionValue は、一意である必要があります。 optionValue には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
リスト
Zen には、以下のリスト・コントロールが用意されています。
-
“<select>” — HTML の <select> の Zen ラッパを使用して、リスト・ボックスを表示します。
-
“<listBox>” — ユーザが選択する固定したオプションを持つ、Zen のリスト・ボックスを定義します。
-
“<dataListBox>” — Zen で、実行時クエリに基づくリスト・ボックスを生成します。
-
“<combobox>” — ユーザが選択する固定したオプションを持つ、Zen のコンボ・ボックスを定義します。
-
“<dataCombo>” — Zen で、実行時クエリに基づくコンボ・ボックスを生成します。
-
“<lookup>” — オプションのリストから値を選択する方法を提供するコントロールを定義します。
リスト・ボックスはオプションの単純なリストですが、コンボ・ボックスは次の 2 つの部分から成ります。
-
コントロールの現在の値を表示するテキスト・コントロール
-
ユーザが選択するオプションのセットを表示するドロップダウン・リスト
コンボ・ボックスのドロップダウン・リストは、例えばコントロールの横にあるボタンをクリックする操作などにより、ユーザがアクティブにしたときに表示できます。ドロップダウン・リストを表示するには、多くの方法があります。イメージやボタンをクリックしたときにリストが表示されるようにできるほか、一定の時間コントロールの上にカーソルを置いたときに表示されるようにすることもできます。これらの詳細は、Zen フォームにリスト・コントロールを配置するときに指定できます。また、Zen に用意されている既定の特性をそのまま使用することもできます。
<select>
Zen の <select> コントロールは、HTML の <select> 要素のラッパです。Zen の <select> は、ユーザが項目を選択できるリストを作成します。
Zen の <select> リストを定義するには、ユーザが選択する valueList と、ユーザに表示する displayList を指定します。次のテーブルでは、Zen の <select> コンポーネントで使用できるこれらおよび他の属性について説明しています。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <select> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。<select> の value は、ユーザが <select> リストで現在選択している内容を示す文字列です。 |
データ・ソースの属性 |
Zen の <select> コントロールでは、valueList と displayList を指定するのではなく、SQL クエリを使用してリストのデータ・ソースを指定できます。<select> には、これを目的とする属性が多数用意されています。この方法を使用すると、以下のように、SQL クエリにより返される列によって <select> リストの表示内容が決まります。
<select> は、maxRows、queryClass、queryName、および sql というクエリ属性をサポートしています。詳細と例は、“Zen のテーブル” の章にある以下のセクションを参照してください。
|
choiceColumn | dataCombo の choiceColumn 属性と同じ機能を提供します。“<dataCombo> の一般的な属性” を参照してください。 |
displayList |
<select> リストで表示する値のコンマ区切りリスト。displayList は、valueList が定義されている場合にのみ適用されます。表示値は、実際の論理値に応じて異なる可能性があります。 displayList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる displayList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
emptyText | showEmpty が True の場合に追加される "empty" 項目に表示されるテキスト。既定は "" です。 |
showEmpty |
True の場合、<select> はドロップダウン・ボックスの先頭に追加の行を出力します。属性 emptyText は、この項目のコンテンツを提供します。emptyText の既定値は "" です。通常は、この動作が望ましいので、showEmpty の既定値は True です。<dataCombo> で required 属性を True に設定すると、showEmpty の値に関係なく、この空白行は表示されなくなります。 showEmpty で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
size | <select> リストに表示する行数。 |
valueColumn | dataCombo の valueColumn 属性と同じ機能を提供します。“<dataCombo> の一般的な属性” を参照してください。 |
valueList | <select> リストの論理値をコンマで区切ったリスト。 |
<listBox>
Zen の <listBox> コントロールは、リスト・ボックスを表示します。このリスト・ボックスのオプションは、個別に形式を指定できます。
Zen の <listBox> コントロールは、HTML の <select> のラッパではありません。Zen の <listBox> は、HTML 基本関数を使用して実装されます。これにより、<listBox> は HTML の <select> にはない以下の機能を提供できます。
-
リストの内容に対する制御の強化
-
CSS と相互運用する Internet Explorer に関する問題の解決策
<listBox> のオプション
Zen のリスト・ボックスを定義する最も簡単な方法は、<listBox> コンポーネント内の <option> 要素のセットを指定することです。以下の文は、前述のサンプル・リスト・ボックスを生成します。
<listBox id="listBox" label="listBox" listWidth="240px"
onchange="zenPage.notifyOnChange(zenThis);"
value="2">
<option value="1" text="Apple" />
<option value="2" text="Banana" style="font-size: 1.5em; "/>
<option value="3" text="Cherry" />
<option value="4" text="Pumpkin" />
<option value="5" text="Eggplant" style="font-size: 2.1em; "/>
</listBox>
<option> 要素は、%ZEN.Auxiliary.optionOpens in a new tab クラスの XML プロジェクションであり、次のテーブルで説明する属性をサポートします。
属性 | 説明 |
---|---|
style | このオプションに適用する CSS スタイル。 |
text |
表示値。これは、リスト・ボックスに表示されるテキストです。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
value | 論理値。これは、フォームを送信する際、このコントロールに対して Zen により送信される値です。リスト内の各オプションには、text と value の両方を指定する必要があります。 |
プログラムで %ZEN.Component.listBoxOpens in a new tab を扱うときは、リスト・コレクションである options プロパティのメンバとして <option> 要素を扱います。<listBox> の各 <option> は、options コレクションのメンバになり、位置の順序を表す 1、2、3 といった番号が付けられます。
<listBox> の一般的な属性
<listBox> と <dataListBox> には、以下の共通の汎用属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | リスト・ボックスは、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。リスト・ボックスの value は、コントロールで現在選択されている論理値を表すテキスト文字列です。 |
listHeight | CSS の長さの値。listHeight を定義すると、その値でリスト・ボックス・ウィンドウの既定の高さ (250px) がオーバーライドされます。 |
listWidth | CSS の長さの値。listWidth を定義すると、その値でリスト・ボックス・ウィンドウの既定の幅 (250px) がオーバーライドされます。 |
selectedIndex | リスト・ボックスで現在選択されているオプションのインデックス (先頭インデックスは 0)。既定の selectedIndex は –1 です (何も選択されていない状態)。 |
text | 現在選択されている項目に対応する表示テキスト。text 値には直接アクセスせず、getProperty('text') を使用してください。 |
<listBox> のドラッグ・アンド・ドロップ
すべてのコントロールと同様に、<listBox> は、<listBox> の dragEnabled 属性が True である場合にデータのドラッグをサポートします。これにより、アプリケーション・ユーザは値をリスト・ボックスからドラッグして、別のコントロール上にドロップすることができます。dropEnabled も同様に True である場合、別のコンポーネントの値を <listBox> 上にドロップすることができ、リストの末尾にその値が追加されます。これは、他の Zen コントロールに対してドラッグ・アンド・ドロップが提供する単純な置換とは異なります。<listBox> のこの特殊なケースにより、ユーザはリスト間でオプションをドラッグすることができます。ドラッグとドロップの両方が有効である場合、ユーザは、マウスを使用してリスト項目を新しい位置にドラッグしてからドロップすることで、<listBox> 内のリスト項目の順序を並べ替えることができます。
ドラッグ・アンド・ドロップ機能を有効にするには、<listBox> を含む <page> の dragAndDrop 属性が True に設定されている必要があります。詳細は、この章の冒頭の “データのドラッグ・アンド・ドロップ” を参照してください。
<dataListBox>
<dataListBox> は特殊なタイプの <listBox> で、SQL クエリを使用して実行時に取得したオプションのリストをユーザに表示します。<listBox> とは異なり、<dataListBox> では、<option> 要素の指定や、リスト内の個々のオプションのスタイルの設定はできません。これは、<dataListBox> がクエリを使用して動的なオプション・リストを取得するためです。<dataListBox> には静的に定義されたオプションがないため、<option> 要素がありません。
項目が選択された <dataListBox> は、以下のようになります。
<dataListBox> には以下の属性があります。
属性 | 説明 |
---|---|
リスト・ボックスの属性 | <dataListBox> は、<listBox> と同じ汎用属性を持ちます。詳細は、“<listBox> の一般的な属性” を参照してください。 |
データ・ソースの属性 |
<dataListBox> のリストは、サーバの %ResultSetOpens in a new tab オブジェクトを作成、実行、およびフェッチすることで得られます。この %ResultSetOpens in a new tab オブジェクトの作成方法は、<dataListBox> がその親クラスである %ZEN.Component.querySourceOpens in a new tab から継承する属性を使用して指定できます。 以下のように、SQL クエリにより返される列によって <dataListBox> リストの表示内容が決まります。
<dataListBox> で QuerySource 属性を使用する方法の詳細および例は、“Zen のテーブル” の章で以下のセクションを参照してください。
|
sqlLookup | <dataListBox> には、<dataCombo> と同様に機能する sqlLookup 属性があります。動作の主な違いは、sqlLookup によって検出された値がリストにまだ表示されていない場合に <dataListBox> がその値を表示しないことです。詳細は、“<dataCombo> の論理値と表示値” のセクションを参照してください。 |
OnDrawItem |
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。詳細は、このテーブルの後に記載されています。 |
itemCount | (読み取り専用) リスト内のオプションの数。これは、このコンポーネントのクエリを実行すると計算されます。このプロパティは、リストが表示されない限り、値を持ちません。 |
OnDrawItem メソッドは、指定された項目のセル内に表示される HTML を返します。ここで、HTML の表示前に、特殊文字をエスケープしたり、その他の HTML に対する最後の調整を行います。
Zen は、初めてリスト・ボックスを描画するときに、このメソッドを呼び出して、自動的に以下のパラメータを渡します。
-
%ResultSetOpens in a new tab — OnCreateResultSet からの結果セット (この <dataListBox> が結果セットを使用してそのコンテンツを生成する場合)。
-
%StringOpens in a new tab — その項目の論理値。
-
%StringOpens in a new tab — その項目の表示値。
このコールバックは、得られた HTML を含む %StringOpens in a new tab を返す必要があります。 以下に、有効なメソッド・シグニチャの例を示します。
Method DrawItem(pRS As %ResultSet,
pValue As %String,
pText As %String) As %String
{
Set tx=pText
Set tx=$REPLACE(tx,"&eacute;",$ZCVT($CHAR(233),"O","HTML"))
Set tx=$REPLACE(tx,"&ntilde;",$ZCVT($CHAR(241),"O","HTML"))
Quit tx
}
コールバックとして上のメソッドを使用するには、<dataListBox> で OnDrawItem="DrawItem" と設定します。
<combobox>
Zen の <combobox> は、以下のように、テキスト・フィールドの下にドロップダウン・リストを表示します。
この章で説明のある他の一部のコントロールと異なり、Zen の <combobox> コントロールは、HTML の <select> のラッパではありません。Zen の <combobox> は、HTML 基本関数を使用して実装されます。これにより、<combobox> は HTML の <select> にはない以下の機能を提供できます。
-
テキスト・ボックスの値を編集可能
-
リストの内容に対する制御の強化
-
CSS と相互運用する Internet Explorer に関する問題の解決策
<combobox> の論理値と表示値
<combobox> を定義するには、ユーザが選択する valueList と、ユーザに表示する displayList を指定します。次のテーブルは、これらの <combobox> 属性の説明です。
属性 | 説明 |
---|---|
displayList |
このコンボ・ボックスのリストに表示する値のコンマ区切りリスト。displayList は、valueList が定義されている場合にのみ適用されます。表示値は、実際の論理値に応じて異なる可能性があります。 displayList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる displayList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
valueList | valueList は、<combobox> 内で指定されている <option> 要素をすべてオーバーライドします (このテーブルの後の説明を参照)。valueList は、この <combobox> のドロップダウン・リストの論理値をコンマで区切って並べたリストです。valueList を指定する場合は、displayList も指定する必要があります。 |
<combobox> のオプション
valueList と displayList を指定する代わりに、<combobox> コンポーネント内で一連の <option> 要素を指定して、<combobox> を定義することもできます。<option> を使用すると、リストのエントリごとに CSS スタイルを適用できるので、valueList や displayList よりも高い柔軟性が得られます。以下はその例です。
<combobox id="comboboxEdit" label="combobox Editable" editable="true">
<option value="1" text="Apple" />
<option value="2" text="Banana" style="font-size: 2.5em; "/>
</combobox>
<listBox> コントロールも <option> を使用してエントリを追加します。詳細は、“<listBox> のオプション” のセクションを参照してください。
<combobox> の一般的な属性
<combobox> と <dataCombo> には、以下の共通属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | コンボ・ボックスは、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。コンボ・ボックスの valueは、コントロールで現在選択されている論理値を表すテキスト文字列です。 |
buttonCaption |
comboType が "button" の場合にボタンに使用されるキャプション。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
buttonImage | コンボ・ボタンの通常の状態を表示するイメージの URI。 |
buttonImageDown | コンボ・ボタンを押した状態を表示するイメージの URI。 |
buttonTitle |
comboType が "button" または "image" の場合にドロップダウン・ボタンに使用するポップアップ・タイトル。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
comboType |
コンボ・ボックスのドロップダウン・ボックスを有効にする方法は、以下のとおりです。
|
delay | comboType が "timer" の場合、delay は、ユーザによる入力の後、ドロップダウンを表示するまで待機する時間 (ミリ秒単位) を指定します。既定値は 250 ミリ秒です。 |
dropdownHeight | CSS の長さの値。dropdownHeight を定義すると、その値でドロップダウン・ウィンドウの既定の高さ (250px) がオーバーライドされます。 |
dropdownWidth | CSS の長さの値。dropdownWidth を定義すると、その値でドロップダウン・ウィンドウの既定の幅 (250px) がオーバーライドされます。 |
editable |
True の場合、ユーザは入力ボックスの値を、テキスト・フィールドのように直接編集できます。既定値は False です。 editable で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
maxlength | このコントロール内にユーザが入力できる最大の文字数。 |
scrollIntoView |
True の場合、Zen では JavaScript の scrollIntoView 関数を使用して、ドロップダウン内で現在選択されている項目が見えるようにします。 scrollIntoView で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
selectedIndex | ドロップダウン・リストで現在選択されているオプションのインデックス (先頭インデックスは 0)。既定の selectedIndex は –1 です (何も選択されていない状態)。 |
size | このコントロールのテキスト入力領域の HTML 幅。既定の size は 20 です。 |
unrestricted |
この値が True で、editable も True の場合は、ユーザが入力した値をコントロールの値として使用できます。False の場合、値はドロップダウン・リストの選択肢のいずれかに限定されます。既定値は False です。 unrestricted で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
%ZEN.Component.comboboxOpens in a new tab は %ZEN.Component.textOpens in a new tab コントロールのサブクラスです。これは、text コントロールで定義したさまざまなメソッドを使用して、<combobox> または <dataCombo> のテキスト・ボックス部分を操作できるということです。
<dataCombo>
<dataCombo> は特殊なタイプの <combobox> で、SQL クエリを使用して実行時に取得したオプションのリストをユーザに表示します。<combobox> とは異なり、<dataCombo> では、<option> 要素の指定や、リスト内の個々のオプションのスタイルの設定はできません。これは、<dataCombo> がクエリを使用して動的なオプション・リストを取得するためです。<dataCombo> には静的に定義されたオプションがないため、<option> 要素がありません。
検索語のテキストを入力した <dataCombo> は、以下のようになります。
<dataCombo> のクエリ属性
<dataCombo> のドロップダウン・リストは、サーバの %ResultSetOpens in a new tab オブジェクトを作成、実行、およびフェッチすることで得られます。ユーザ・アクションによりドロップダウンが表示されるまでは、最初、ドロップダウンの内容は空です。ドロップダウンを表示したときに、サーバに対する呼び出しでドロップダウンの内容をフェッチします。この動作は <dataCombo> の cached 属性を設定することで変更できます。
<dataCombo> で %ResultSetOpens in a new tab オブジェクトを作成する方法は、<dataCombo> がその親クラスである %ZEN.Component.querySourceOpens in a new tab から継承する属性を使用して指定できます。以下のように、SQL クエリにより返される列によって <dataCombo> リストの表示内容が決まります。
-
%ResultSetOpens in a new tab が 1 列の場合、この列の内容は、ドロップダウン・リストの論理値と表示値の両方として使用されます。
-
%ResultSetOpens in a new tab が複数列の場合、1 列目の内容が論理値、2 列目の内容が表示値としてそれぞれ使用されます。論理値を指定する列と表示値を指定する列を変更するには、valueColumn 属性と choiceColumn 属性を使用します。
-
%ResultSetOpens in a new tab が 3 列以上で構成されている場合は、displayColumns 属性と columnHeaders 属性を使用して、ドロップダウンを複数列表示にできます。
詳細と例は、“Zen のテーブル” の章にある以下のセクションを参照してください。
-
“データ・ソース” (maxRows)
-
“SQL クエリの指定” (sql)
-
“SQL クエリの生成” ( groupByClause、orderByClause、tableName、whereClause)
-
“クラス・クエリの参照” (queryClass、queryName)
-
“コールバック・メソッドの使用” (OnCreateResultSet、OnExecuteResultSet)
<dataCombo> のクエリ・パラメータ
<dataCombo> ドロップダウン・リストの内容を指定するために使用するクエリには、以下のような実行時の ? パラメータを 1 つ以上使用できます。
WHERE Name %STARTSWITH ?
クエリ・パラメータの値は、以下のいずれかの方法で指定できます。
-
“Zen のテーブル” のトピック “クエリ・パラメータ” の説明にあるように、<dataCombo> は <parameter> リストを定義できます。このパラメータの値は、? パラメータを、SQL クエリでの表示順に置き換えます。これらのパラメータの値は、プログラムを使用してクライアントから変更することが可能です。その場合は、必ず、%ZEN.Component.dataComboOpens in a new tab のメソッド clearCache を呼び出して、ドロップダウン・クエリが新しい値で再実行されるようにします。
-
0 以外の値を指定した searchKeyLen は、Zen がコンボ入力ボックスから取得して、ドロップダウン・リストの内容を提供する SQL クエリに最初のパラメータとして渡す、検索文字の最大数となります。
0 の場合、入力ボックスの内容はクエリ・パラメータとして使用されません。既定値は 0 です。
searchKeyLen が 0 以外で、editable が True である場合、入力ボックスの現在の内容のうち、先頭の searchKeyLen 個の文字が、最初のクエリ・パラメータの値 (つまり parms(1)) として使用されます。パラメータ・リストの最初のメンバが parms(2) の値になり、2 番目のメンバが parms(3) の値になり、以降同様となります。
パラメータの値が "?" の場合、現在の検索キーの値 (最初のパラメータに使用される値) は、このクエリ・パラメータにも同様に使用されます。
<dataCombo> の論理値と表示値
どのリスト・ボックスまたはコンボ・ボックスであっても、次のように現在の値が 2 つあります。
-
論理値 — getValue メソッドによって返され、実際に格納されている value
-
表示値 — ユーザに対して表示され、ユーザがドロップダウン・リストから選択する値
通常、これら 2 つの値は異なりますが、同じになることもあります。
<select>、<listBox>、および <combobox> の各 Zen コントロールは、論理値および表示値の固定リストを持ちます。アプリケーションでこれらのコントロールのいずれかの value を設定すると、新しい論理値が関連付けられる表示値をコントロール側では容易に識別できます。
<dataListBox> および <dataCombo> は値を動的に取得するので、論理値と表示値を一致させるには、さらに手順が必要になります。アプリケーションで <dataCombo> コントロールのローカル value を設定すると、内部的には <dataCombo> がこの論理値に最も適した表示値を探し出そうとします。この作業はサーバとクライアントでは以下のように異なります。
-
サーバでは、<dataCombo> はその sqlLookup 属性で定義された SQL 文を実行します。
-
クライアントでは、<dataCombo> はまず、指定された論理値に一致する値をドロップダウン・キャッシュで検索します。一致する値が見つからない場合は、sqlLookup クエリを実行するサーバ・メソッドを呼び出します。
例えば、表示値を Name、論理値を Customer の ID として、Customer の名前のセットを表示する <dataCombo> を定義するとします。このためには、以下の 2 つの SQL 文を使用して、<dataCombo> を定義します。
<dataCombo id="MyCombo"
sql="SELECT ID,Name FROM MyApp.Customer WHERE Name %STARTSWITH ? ORDER BY Name"
sqlLookup="SELECT Name FROM MyApp.Customer WHERE ID = ?"
editable="true"
searchKeyLen="10"
/>
このサンプルの <dataCombo> の定義には、以下のような効果があります。
-
Zen ページでドロップダウン・リストが表示されるたびに、sql 属性で指定された SQL クエリが呼び出されます。このクエリによって、<dataCombo> の論理値と表示値のセットが得られます。<dataCombo> は、前回の sql クエリで得られた結果をローカル・キャッシュに保存します。
-
sqlLookup 属性で指定された SQL クエリは、特定の論理値に対応する特定の表示値を検索するために呼び出されます。sqlLookup の ? パラメータの値は、<dataCombo> コントロールの現在の論理値から取得されます。
-
アプリケーションがこの <dataCombo> の論理値を実行時に設定しようとした場合、および論理値と表示値がまだキャッシュに格納されていない場合、sqlLookup クエリも実行されます。
-
この例の searchKeyLen 値は、Zen がコンボ入力ボックスから最大で最初の 10 文字までを、ドロップダウン・リストの内容を提供する SQL クエリへ渡すことを示しています。
sql クエリと sqlLookup クエリは、“<dataCombo> のクエリ・パラメータ” のセクションの説明にあるように、クエリ・パラメータを使用できます。
sqlLookup 属性で基本となるデータ型は %ZEN.Datatype.sqlOpens in a new tab です。これは、クライアントからアクセスできないことを示します。この属性の値はクライアントに送信される際、現在のセッション・キーを使用して暗号化されます。サーバに返された値は、自動的に解読されます。これにより、クライアントのユーザに機密データが表示されないようにしてクライアントにそのデータを保存し、将来、サーバで処理することが可能になります。
sqlLookup 属性を使用してテーブルからユーザが選択するデータのリストを取得する場合に、unrestricted 属性を True に設定して、基になるテーブルに存在しない値をユーザが入力できるようにしている場合は、sqlLookup で指定した検索は実行されません。unrestricted を設定すると、sqlLookup が無効になるからです。
sqlLookup 属性の値では、すべての XML 特殊文字をエスケープする必要があります。例えば、「より小さい」を意味するシンボル < の代わりに、以下のように XML エンティティ < を使用する必要があります。
sqlLookup=
"select * from infonet_daten.abopos where lieferadresse=? and status<9"
以下のテーブルは、sqlLookup 文字列内に記述すると不具合の原因となる XML 特殊文字とその代替となる XML エンティティを示しています。
文字 | XML エンティティ | 説明 |
---|---|---|
> | > | 右山括弧 (“より大きい” を意味するシンボル)。 |
< | < | 左山括弧 (“より小さい” を意味するシンボル)。 |
& | & | アンパサンド。 |
' | ' | 一重引用符またはアポストロフィ。一重引用符で囲んだ文字列では、' エンティティを使用して ' 文字を表現する必要があります。 |
" | " | 二重引用符。二重引用符で囲んだ文字列では、" エンティティを使用して " 文字を表現する必要があります。 |
<dataCombo> の一般的な属性
これまでのセクションで説明した属性に加えて、<dataCombo> は次の汎用属性もサポートしています。
属性 | 説明 |
---|---|
コンボ・ボックスの属性 | <dataCombo> は、<combobox> と同じ汎用属性を持ちます。詳細は、“<combobox> の一般的な属性” を参照してください。<dataCombo> では、静的なオプションが定義できないので、displayList 属性と valueList 属性がサポートされていません。 |
auxColumn | ドロップダウン・リストに複数のデータ列が表示される場合、auxColumn は、このコントロールの追加の補助値を指定する列の列番号 (先頭値は 1) となります。auxColumn を使用すると、表示値でも論理値でもない追加の値を指定できます。auxColumn 値が有効な列番号でない場合、補助データは指定できません。auxColumn の既定値は 0 です。 |
cached |
cached が True の場合、最初にページを表示するときに、ドロップダウン・リストの初期の内容をフェッチするクエリが実行され、itemCount プロパティはドロップダウンにある項目の数に設定されます。クライアントは、ドロップダウン・リストの内容を得る際、再度サーバにアクセスせず、これらのキャッシュされた結果からフェッチします。クエリの検索パラメータを変更するか、clearCache メソッドを呼び出すことによって、いつでもドロップダウンのキャッシュをクリアできます。 cached の既定値は False です。この場合、クエリで内容をフェッチするには、ドロップダウン・リストを要求するアクションをユーザが実行する必要があります。 cached 属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
choiceColumn | ドロップダウン・リストに複数のデータ列が表示される場合、choiceColumn は、このコントロールの表示値となる列の、1 から始まる列番号となります。choiceColumn の既定値は 2 です。指定した choiceColumn 値がクエリ内の列数よりも大きい場合、2 番目の列が使用されます。 |
clearOnLoad |
この属性が True で、この <dataCombo> がデータ・コントローラに結合されている場合は、新しいインスタンスがコントローラにロードされるとドロップダウン・リストの内容はクリアされます。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
columnHeaders |
columnHeaders は、定義されている場合、ドロップダウン・リストに表示する列ヘッダのコンマで区切られたリストです。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 あらゆる columnHeaders 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
contentType |
表示値をどのようにレンダリングするかを指定します。可能な値は以下のとおりです。
|
displayColumns | <dataCombo> の %ResultSetOpens in a new tab に複数のデータ列がある場合、displayColumns には 1 から始まる列番号のコンマ区切りリストを指定できます。このリストは、%ResultSetOpens in a new tab のどの列を表示するかを表します。 |
emptyText | showEmpty が True の場合に追加される "empty" 項目に表示されるテキスト。既定は "" です。 |
itemCount |
(読み取り専用) ドロップダウン・リスト内の項目の数。この値は、ドロップダウン・リストを生成したときの副次的結果として設定されます。このプロパティは、リストが表示されない限り、値を持ちません。 cached が True の場合は、ページが初めて表示されるときに、ドロップダウン・リストの初期内容をフェッチするクエリが実行され、ページの %OnAfterCreatePage コールバック・メソッドが実行された直後に、itemCount プロパティはドロップダウン・リスト内の項目数に設定されます。クライアントは、ドロップダウン・リストの内容を得る際、再度サーバにアクセスせず、これらのキャッシュされた結果からフェッチします。 クエリの検索パラメータを変更するか、clearCache メソッドを呼び出すことによって、いつでもドロップダウンのキャッシュをクリアできます。 cached の既定値は False です。この場合、クエリで内容をフェッチするには、ドロップダウン・リストを要求するアクションをユーザが実行する必要があります。 |
loadingMessage |
このメッセージは、サーバ側クエリが実行されて <dataCombo> リストが作成される間、一時的に表示されます。既定値は以下のとおりです。 $$$Text("Loading...","%ZEN"); この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
multiColumn |
この値が True で、結果セットが 3 列以上で構成されている場合、ドロップダウン・ボックスに複数の列が表示されます。既定値は True です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
onshowDropdown |
<dataCombo> の onshowDropdown イベント・ハンドラ。ドロップダウン・リストが表示される直前に、Zen によってこのハンドラが呼び出されます。“Zen コンポーネントのイベント・ハンドラ” を参照してください。この式が値を返す場合、入力ボックスに入力される値の代わりにこの値がドロップダウン・クエリのフィルタ値として使用されます。 |
searchKeyLen |
0 以外の値を指定した searchKeyLen は、Zen がコンボ入力ボックスから取得して、ドロップダウン・リストの内容を提供する SQL クエリに最初のパラメータとして渡す、検索文字の最大数となります。 0 の場合、入力ボックスの内容はクエリ・パラメータとして使用されません。既定値は 0 です。 searchKeyLen が 0 以外で、editable が True である場合、入力ボックスの現在の内容のうち、先頭の searchKeyLen 個の文字が、最初のクエリ・パラメータの値 (つまり parms(1)) として使用されます。パラメータ・リストの最初のメンバが parms(2) の値になり、2 番目のメンバが parms(3) の値になり、以降同様となります。 パラメータの値が "?" の場合、現在の検索キーの値 (最初のパラメータに使用される値) は、このクエリ・パラメータにも同様に使用されます。 |
showEmpty |
True の場合、<dataCombo> はドロップダウン・ボックスの先頭に追加の行を出力します。属性 emptyText は、この項目のコンテンツを提供します。emptyText の既定値は "" です。通常は、この動作が望ましいので、showEmpty の既定値は True です。<dataCombo> で required 属性を True に設定すると、showEmpty の値に関係なく、この空白行は表示されなくなります。 showEmpty で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
valueColumn | <dataCombo> の %ResultSetOpens in a new tab に複数のデータ列がある場合、valueColumn は、このコントロールの論理値を指定する列の列番号 (先頭値は 1) を表します。valueColumn の既定値は 1 です。指定した valueColumn 値がクエリ内の列数よりも大きい場合、1 番目の列が使用されます。 |
<dataCombo> の表示シーケンス
Zen で <dataCombo> がどのように表示されるかを詳しく説明するために、以下のテーブルに内部イベントの実行シーケンスを示します。このシーケンスは、ユーザの観点、ブラウザベースの実行、およびサーバ側の実行の各面から見たものです。通信の詳細部分のほとんどは、CSP テクノロジを基盤とする Zen が処理します。背景情報は、"Zen の使用法" の “Zen のクライアントおよびサーバ” の章を参照してください。
ユーザの観点 | ブラウザ | サーバ | |
---|---|---|---|
1 | ドロップダウンを選択します。 | ||
2 | ドロップダウンが有効になります。 | ||
3 | ハイパーイベントをサーバに送信し、SQL を実行します。 | ||
4 | ハイパーイベントを受信し、SQL を実行します。 | ||
5 | ハイパーイベントの応答 (JavaScript コードで構成されます) を送信し、ドロップダウン・ユニットを生成します。 | ||
6 | サーバからドロップダウン・リストへの入力が得られます。 | ||
7 | リストに項目が入力されます。 | ||
8 | ユーザが項目を選択します。 | ||
9 | ドロップダウン・アイテムが選択されます。 | ||
10 | クライアント側の選択イベント・ハンドラを呼び出します。 | ||
11 | ハイパーイベントをサーバに送信し、ZenMethod を開始します。 | ||
12 | ハイパーイベントを受信し、ZenMethod を開始します。 | ||
13 | サーバ側 DOM を更新します。 | ||
14 | ハイパーイベントの応答 (JavaScript コードで構成されます) を送信し、クライアント DOM とサーバ DOM を同期します。 | ||
15 | ZenMethod の実行中にサーバで発生した変更を反映して、クライアント側 DOM を更新します。 | ||
16 | DOM 結合コンポーネントの表示を、新しいクライアント側 DOM に合わせて更新します。 | ||
17 | 選択内容に基づいて、フォームのフィールドが埋まります。 |
<lookup>
<lookup> コントロールはオプションのリストから値を選択する方法を提供する、特殊なタイプのコントロールです。 これは、HTML5 のコンポーネントです。HTML5 準拠のブラウザでのみ正しく動作します。このコントロールは、以下の属性をサポートします。
属性 | 説明 |
---|---|
context | このコンポーネントの選択リストを決定するために使用するコンテキスト文字列。このコンテキスト文字列は、?parm1=value という形式にする必要があります。 |
displayBinding | このコントロールを <dataController> に関連付けられたフォームで使用する場合は、このコントロールの表示値を提供する <dataController> のプロパティ名をこの属性で指定します。 |
idProperty | ユーザが選択を行った後にコントロールの値を提供するデータ要素のプロパティ名。 |
imageProperty | イメージ・ファイルへのパスを提供するデータ要素のプロパティ名。この属性が定義されていて、指定のプロパティが存在している場合、このコントロールは、ポップアップに、テキスト値ではなくイメージを表示します。このイメージのパスは、Caché のインストール・ディレクトリ内の CSP/broker を基準として解決されます。ユーザが選択したときには、textProperty によって指定されたデータ要素が値を提供します。 |
lookupIcon | 検索ポップアップの起動に使用するイメージを提供するイメージ・ファイルへのパス。このイメージのパスは、Caché のインストール・ディレクトリ内の CSP/broker を基準として解決されます。 |
noResultsMessage |
利用可能な選択肢がないときに、検索ポップアップに表示するメッセージ。既定値は、“表示対象がありません!” です。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
ongetdata | ongetdata イベント・ハンドラ。このハンドラは、検索ポップアップに表示するデータの JavaScript 配列を返します。このイベント・ハンドラでは、オブジェクトまたはリテラル値の配列を返すことができます。 |
onshowPopup | onshowPopup イベント・ハンドラ。このハンドラは、ポップアップ表示の直前に起動されます。 |
popupLabel |
ポップアップに表示するタイトル。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
propertyList | ポップアップ・リストの表示テキストを作成するために使用するプロパティ名のコンマ区切りリスト。 |
showFilter | ポップアップにフィルタ・テキスト・ボックスを含める必要があるかどうかを指定します。 |
size | このコントロールのベース (非ポップアップ) 部分のサイズ。提示される数値を 10 倍すると幅が得られます。 |
styleList | ポップアップ・リストのすべてのセルに適用される CSS スタイルのコンマ区切りリスト。 |
text | このコントロールの表示値。value 属性には、論理値が格納されています。 |
textProperty | テキスト値を提供するデータ要素のプロパティ名。 |
以下のイメージは <lookup> コントロールで、そのメイン・コンポーネントが示されています。
このイメージは選択ポップアップで、そのメイン・コンポーネントが示されています。この例では、styleList プロパティを使用して、選択肢に青色を適用しています。テキスト・フィルタ・ボックスの表示/非表示は、プロパティ showFilter で制御します。ongetdata イベント・ハンドラが選択肢を返さない場合は、noResultsMessage で指定されるテキストで、選択肢のリストを置換します。
以下のコード例では、上記のイメージで示した <lookup> コントロールを作成します。
<page xmlns="http://www.intersystems.com/zen" title="">
<lookup
popupLabel="City Selector"
label="Choose a City:"
lookupIcon="MyApp/eye_16.png"
ongetdata="return zenPage.myData();"
styleList="color:blue,"
idProperty="id"
textProperty="text"
value="Seattle"
/>
</page>
ClientMethod myData() [ Language = javascript ]
{
var data = [
{id:1, text:'Boston',},
{id:2, text:'New York'},
{id:3, text:'Atlanta'},
{id:4, text:'Chicago'},
{id:5, text:'Tucson'},
{id:6, text:'Seattle'},
{id:7, text:'San Francisco'},
{id:8, text:'Los Angeles'},
{id:9, text:'San Diego'}
];
return data;
}
属性 imageProperty は、選択ポップアップでイメージを使用できるようにします。例えば、以下の <lookup> コントロールおよび ongetdata コールバックがあります。
<page xmlns="http://www.intersystems.com/zen" title="">
<lookup
label="Choose a Direction:"
ongetdata="return zenPage.myData();"
imageProperty="image"
textProperty="text"
/>
</page>
ClientMethod myData() [ Language = javascript ]
{
var data = [
{id:1, text:'Down', image:'images/arrowBD.png'},
{id:2, text:'Left', image:'images/arrowBL.png'},
{id:3, text:'Right', image:'images/arrowBR.png'},
{id:4, text:'Up', image:'images/arrowBU.png'} ];
return data;
}
以下の図に示すように、イメージを使用するポップアップになります。
属性 propertyList を使用すると、複数のデータ要素からポップアップの表示テキストを構成できます。この属性は、プロパティ名のコンマ区切りリストを提供します。<lookup> コントロールは、これらの名前に関連付けられた値を使用して、検索リストを生成します。
<page xmlns="http://www.intersystems.com/zen" title="">
<lookup
ongetdata="return zenPage.myData();"
idProperty="lname"
propertyList="fname,lname,dob"
/>
</page>
この結果、ポップアップの各行には、データ内の fname フィールド、lname フィールド、および dob フィールドからの値が格納されるようになります。idProperty によって指定されたフィールドのみがユーザが選択を行った後にコントロールの値になります。
CSS を使用してポップアップ内の項目の表示を制御することもできます。lookup 項目の CSS クラスは lookupItem です。例えば、以下の CSS は、ポップアップ内の各項目の背景を黄色に設定します。
.lookupItem {
background-color:yellow;
}
日付
Zen には、以下の日付選択コントロールが用意されています。
-
“<calendar>” — ユーザはポップアップ・カレンダーから日付を選択します。
-
“<dateSelect>” — ユーザは、月、日、および年を選択します。
-
“<dateText>” — ユーザはテキストを入力するか、日付を選択することができます。
このトピックで説明するコンポーネントは、ユーザがフォームの値として日付を入力できる、単純な日付選択コントロールです。Zen には、<schedulePane> という別のコンポーネントも用意されています。これは、日付選択コントロールではありません。<schedulePane> は、各日付のタイム・スロットと共に、日次、週次、または月次カレンダーを表示します。ユーザはアポイントメントを定義して、それを適切なタイム・スロットに配置できます。詳細は、“その他の Zen コンポーネント” の章にある “スケジュール・カレンダー” を参照してください。
<calendar>
<calendar> コンポーネントは、ナビゲート可能なカレンダーを、一度に 1 か月分表示します。ユーザは、カレンダーを表示し、カレンダーから日付を選択できます。<calendar> は初期状態では、現在の日付を太字でハイライト表示し (以下の例では 7 日)、現在選択されている日付を背景色が黄色の太字で表示します (以下の例では 14 日)。Zen の <calendar> は、以下のようになります。
<calendar> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <calendar> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。クライアントでは、<calendar> の value は YYYY-MM-DD 形式の文字列です。サーバでは、<calendar> の value のデータ型は %Timestamp です。 |
dayList |
カレンダーの上部に表示する、曜日の省略形のコンマ区切りのリスト。dayList の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("S,M,T,W,T,F,S") dayList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる dayList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
defaultTime |
<calendar> value の時刻部分に既定値を提供します。defaultTime は、以下の条件に合致した場合にポップアップ・カレンダー内に表示される初期時刻として使用されます。
カレンダー自体の時刻値は、時刻が指定されていない場合または渡された日付値が無効な場合、既定の "01:00:00" になります。 |
endYear | カレンダーの年のセレクタで選択できる最終年を 4 桁で表現した値。この属性を定義しない場合は、maxDate が定義されていれば、その年部分が既定値となります。maxDate が定義されていない場合は、endYear の既定値は現在から 30 年後になります。 |
firstDayOfWeek | 週の最初の日として表示する曜日を示す番号 (日曜日 =0、土曜日 =6)。既定値は 0 (日曜日) です。 |
fixedMonth |
True の場合、このカレンダーには 1 か月分のみが表示され、ユーザは月および年を変更できません。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
gapWidth | カレンダーの上部にある月表示と年表示の間隔のサイズを指定する、HTML の長さの値。この属性を設定すると、カレンダーの幅を調整できます。上記の例では、40px の既定値を使用しています。 |
maxDate |
YYYY-MM-DD 形式の文字列 (サーバでのデータ型は %Timestamp)。この属性に指定した値は、<calendar> で value として指定できる最後の日付となります。maxDate の値は、endYear が省略されていない限り、カレンダーに表示される年に影響を与えません。 maxDate に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
minDate |
YYYY-MM-DD 形式の文字列 (サーバでのデータ型は %Timestamp)。この属性に指定した値は、<calendar> で value として指定できる最初の日付となります。minDate の値は、startYear が省略されていない限り、カレンダーに表示される年に影響を与えません。 minDate に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
month | 現在のカレンダーに表示する月を指定する番号 (1 月 =1、12 月 =12)。これは、現在の <calendar> の value とは異なります。value では、曜日と年が指定されているほか、時刻も指定でき、さらに月も異なっていることがあります。 |
monthList |
ユーザがカレンダーから選択できる月のリストに表示される、月名のコンマ区切りのリスト。monthList の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("January,February,March,April,May,June,July,August,September,October,November,December") monthList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる monthList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
showTime |
True の場合、このコンポーネントはメイン・カレンダーの下にテキスト入力フィールドを表示します。上の例では、showTime は True です。既定値は False です。 ユーザは、24 時間形式の HH:MM:SS を使用して showTime フィールドに時刻を入力できます。フォームの送信時に、<calendar> の value は、YYYY-MM-DD HH:MM:SS という ODBC/JDBC タイムスタンプ形式で日付と時刻の両方の値を受け取ります。 showTime で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
startYear | カレンダーの年のセレクタで使用できる最初の年を 4 桁で表現した値。この属性を定義しない場合は、minDate が定義されていれば、その年部分が既定値となります。minDate が定義されていない場合は、startYear の既定値は 10 年前になります。 |
timeCaption |
showTime フィールドのキャプション・テキスト。timeCaption の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("Time:") この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
year | 現在のカレンダーに表示する年を指定する 4 桁の数値。これは、現在の <calendar> の value とは異なります。value では、曜日と月が指定されているほか、時刻も指定でき、さらに年も異なっていることがあります。 |
<dateSelect>
<dateSelect> コントロールは、3 つのドロップダウン・リストを表示します。ユーザはリストを使用して、(左から順に) 月、日、年を選択できます。ユーザがこれらのいずれかのフィールドに文字を入力すると、その文字で始まる値 (例えば M と入力した場合は “March” や “May” など) がそのリストに含まれている場合は、その値が表示されます。<dateSelect> は、誕生日や有効期限日などの場合に便利です。これらのケースでは、<dateText> のようなポップアップ・カレンダーでは非効率的な場合があります。
Zen の <dateSelect> コンポーネントは、以下のようになります。この例では、ユーザは月ドロップダウン・リストから選択しています。
<dateSelect> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 |
<dateSelect> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。 クライアントでは、<dateSelect> の value は YYYY-MM-DD 形式の文字列です。サーバでは、<dateText> の value のデータ型は %Timestamp です。 <dateSelect> に定義された任意の HTML イベント (onfocus、onclick など) は、3 つのドロップダウン・リストのそれぞれに独立して適用されます。 |
format |
ドロップダウン・リストを表示する順序 (左から右の順) を指定するための文字列。既定は "MDY" です。可能な値は以下のとおりです。
format に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
maxYear |
年ドロップダウン・リストで選択可能な最後の年を指定するための整数値。既定値は、現在の年 + 20 です。 maxYear に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
minYear |
年ドロップダウン・リストで選択可能な最初の年を指定するための整数値。既定値は 1900 です。 minYear に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
monthList |
ユーザがカレンダーから選択できる月のリストに表示される、月名のコンマ区切りのリスト。monthList の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("January,February,March,April,May,June,July,August,September,October,November,December") monthList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる monthList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
shortMonth |
True の場合、このコンポーネントでは、月のドロップダウン・リストに月名の最初の 3 文字が表示されます。上の例では、shortMonth は False です。既定値は False です。 shortMonth で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 shortMonth 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、3 文字の月名を別の言語に容易にローカライズできます。 |
showMonthNumber |
True の場合、このコンポーネントでは、月のドロップダウン・リストに、月の順序を示す数字と月の名前が一緒に表示されます。上の例では、showMonthNumber は False です。既定値は False です。 showMonthNumber で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 showMonthNumber 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、月選択用の長いテキストを別の言語に容易にローカライズできます。 |
<dateText>
<dateText> コントロールは、本質的にはコンボ・ボックスです。テキスト・ボックスとボタンが表示され、このボタンを押すとポップアップ・カレンダーが表示されます。このコントロールのテキスト領域に値を入力すると、それに最も近い日付の値に変換されるか、無効な日付であることを示すメッセージが表示されます。比較のために、"<dateSelect>" コンポーネントも参照してください。
Zen の <dateText> コンポーネントは、以下のようになります。
<dateText> には以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 | <dateText> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。クライアントでは、<dateText> の value は YYYY-MM-DD 形式の文字列です。サーバでは、<dateText> の value のデータ型は %Timestamp です。ただし、ユーザに表示される <dateText> の内容は変更できます。"format" および "separator" 属性を参照してください。 |
dayList |
カレンダーの上部に表示する、曜日の省略形のコンマ区切りのリスト。dayList の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("S,M,T,W,T,F,S") dayList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる dayList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
defaultTime |
<dateText> control value の時刻部分に既定値を提供します。defaultTime は、以下の条件に合致した場合にポップアップ・カレンダー内に表示される初期時刻として使用されます。
カレンダー自体の時刻値は、時刻が指定されていない場合または渡された日付値が無効な場合、既定の "01:00:00" になります。 |
firstDayOfWeek | 週の最初の日として表示する曜日を示す番号 (日曜日 =0、土曜日 =6)。既定値は 0 (日曜日) です。 |
format |
このコンポーネントの表示形式を指定する文字列。このコントロールの内部値は常に YYYY-MM-DD ですが、ユーザに表示される形式は変更できます。既定は "YMD" です。可能な値は以下のとおりです。
format に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
invalidDateMessage |
ユーザにより入力された日付の検証に失敗したときに表示されるメッセージ。既定値は以下のとおりです。 $$$Text("Invalid Date","%ZEN"); この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
maxDate |
YYYY-MM-DD 形式の文字列 (サーバでのデータ型は %Timestamp)。この属性に指定した値は、<dateText> で value として指定できる最後の日付となります。maxDate の値は、endYear が省略されていない限り、カレンダーに表示される年に影響を与えません。 maxDate に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
minDate |
YYYY-MM-DD 形式の文字列 (サーバでのデータ型は %Timestamp)。この属性に指定した値は、<dateText> で value として指定できる最初の日付となります。minDate の値は、startYear が省略されていない限り、カレンダーに表示される年に影響を与えません。 minDate に指定する値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
monthList |
ユーザがカレンダーから選択できる月のリストに表示される、月名のコンマ区切りのリスト。monthList の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("January,February,March,April,May,June,July,August,September,October,November,December") monthList 属性では、その ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 あらゆる monthList 文字列は、ローカライズした場合でもコンマ区切りリストの状態で維持する必要があります。 |
separator |
日付セグメント間で使用する区切り文字。既定値はハイフン文字 (-) です。ユーザがハイフンの代わりにスラッシュ (/) を入力した場合は、<dateText> コンポーネントはその値を受け付けますが、ハイフンが通常の形式です。 既定値のハイフンの代わりに、separator 属性を使用して別の日付区切り文字を指定できます。 時刻も表示する場合、時刻部分と日付部分は常にコロン (:) で区切られます。 |
showTime |
True の場合、このコンポーネントはメイン・カレンダーの下にテキスト入力フィールドを表示します。上の例では、showTime は True です。既定値は False です。 ユーザは、24 時間形式の HH:MM:SS を使用して showTime フィールドに時刻を入力できます。フォームの送信時に、<calendar> の value は、YYYY-MM-DD HH:MM:SS という ODBC/JDBC タイムスタンプ形式で日付と時刻の両方の値を受け取ります。 showTime で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
size | このコントロールのテキスト入力領域の HTML 幅。既定値は 15 です。 |
timeCaption |
showTime フィールドのキャプション・テキスト。timeCaption の値を指定しない場合、その既定値は以下のとおりです。 $$$Text("Time:") この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
value |
dateText コントロールの value プロパティにはプログラムによってアクセスできます。ただしその場合は、ユーザが入力フィールドにテキストを入力して日付を設定するときに Zen によって実行される日付一致機能が実行されません。 |
グリッド
<dynaGrid>
<dynaGrid> コントロールは、スプレッドシートに似た、編集可能な 2 次元のグリッドを表示します。ユーザがセル内をクリックすると、セル内に編集コントロールが表示され、そのセルの内容を編集できます。ユーザが Enter キーを押すと、変更内容が保存されます。新しく編集されたセルを持つ <dynaGrid> は、以下のようになります。
<dynaGrid> は、以下のいずれかの方法で作成できます。
-
データ・セット、行、および列を指定します。“<dynaGrid> のデータ・セット” を参照してください。
-
<dynaGrid> をデータ・コントローラと関連付けます。“モデル・ビュー・コントローラ” の章を参照してください。
<dynaGrid> のデータ・セット
<dynaGrid> に表示するデータは、%ZEN.Auxiliary.dataSetOpens in a new tab オブジェクトで指定します。dataSet は、サーバとクライアントの間で簡単に送受信できる形式で 1 次元、2 次元、または 3 次元のデータを定義するために使用される特別なデータ・コンテナ・オブジェクトです。
<dynaGrid> オブジェクトを初めて作成すると、自動的に 2 次元の dataSet オブジェクトが作成されます。このオブジェクトには、XData Contents の <dynaGrid> で定義された <gridRow> エントリの数の行 (ディメンジョン 1) と <gridColumn> エントリの数の列 (ディメンジョン 2) があります。以下の例では、初期状態の dataSet オブジェクトに 4 つの行と 4 つの列を指定します。
<dynaGrid id="myGrid" OnCreateDataSet="CreateDS">
<gridColumn width="100"/>
<gridColumn width="100"/>
<gridColumn width="100"/>
<gridColumn width="100"/>
<gridRow />
<gridRow />
<gridRow />
<gridRow readOnly="true" />
</dynaGrid>
アプリケーションでは、サーバ側コールバック・メソッドを定義することにより、初期状態の dataSet オブジェクトのサイズと内容を変更できます。このコールバック・メソッドの名前は、上記の例のように、<dynaGrid> の OnCreateDataSet 属性を使用して指定できます。OnCreateDataSet の値は、<dynaGrid> コントロールが属するページ・クラスで定義されたサーバ側コールバック・メソッドの名前とする必要があります。上の例では、このメソッドは CreateDS です。OnCreateDataSet コールバック・メソッドは、<dynaGrid> オブジェクトがサーバで最初に作成されたとき、<dynaGrid> が初めて表示される前に、1 回呼び出されます。
OnCreateDataSet コールバック・メソッドのシグニチャは以下のようになります。
Method CreateDS(
pGrid As %ZEN.Component.dynaGrid,
pDataSet As %ZEN.Auxiliary.dataSet) As %Status
{ }
以下はその説明です。
-
pGrid は、このコールバックを呼び出す dynaGrid オブジェクトです。
-
pDataSet は、dynaGrid オブジェクトに関連付けられた dataSet オブジェクトです。
-
このメソッドは、%StatusOpens in a new tab 値を返し、成功または失敗を示します。
通常、OnCreateDataSet コールバック・メソッドは以下のようになります。
Method CreateDS(
pGrid As %ZEN.Component.dynaGrid,
pDataSet As %ZEN.Auxiliary.dataSet) As %Status
{
// make sure dataSet is cleared out
Do pDataSet.%Clear()
// fill in contents of dataSet
// This is a 2-D data structure
// row labels (dimension 1)
Do pDataSet.%SetLabel("Boston",1,1)
Do pDataSet.%SetLabel("New York",2,1)
Do pDataSet.%SetLabel("Chicago",3,1)
Do pDataSet.%SetLabel("Miami",4,1)
// column labels (dimension 2)
Do pDataSet.%SetLabel("Cars",1,2)
Do pDataSet.%SetLabel("Trucks",2,2)
Do pDataSet.%SetLabel("Trains",3,2)
Do pDataSet.%SetLabel("Planes",4,2)
// get size of dataSet
Set rows = pDataSet.%GetDimSize(1)
Set cols = pDataSet.%GetDimSize(2)
// fill in initial data values
For r=1:1:rows {
For c=1:1:cols {
Set value = 0
Do pDataSet.%SetValue(value,r,c)
}
}
Quit $$$OK
}
上記の例は、4 行× 4 列の 2 次元 dataSet オブジェクトを定義しています。ここでは行と列にラベルを付け、セルをループ処理して初期値を設定しています。
OnCreateDataSet コールバックにより、3 次元を扱うように dataSet オブジェクトが変更されると、<dynaGrid> でデータの “pages” 間を移動できるようになります。各ページは、現在表示可能なページを表す 2 次元のグリッドとして表示されます。以下の図は、このデータ・モデルを表しています。図に示したラベル属性の詳細は、この章の “<gridRow>”、“<gridColumn>”、および “<dynaGrid> の属性” を参照してください。
<dynaGrid> に複数のページがある場合、gridLabel セルには以下のようにナビゲーション情報が表示されます。<< 記号をクリックすると前のページへ、>> 記号をクリックすると次のページへ移動します。番号は、現在表示されているページの番号を示します。
<dynaGrid> のメソッド
dataSet オブジェクトはサーバまたはクライアントの両方で機能するように設計されているので、どちらの環境についてもローカル API が用意されています。以下のテーブルは、サーバ側 (ObjectScript) メソッドの一覧です。詳細およびクライアント側 (JavaScript) メソッドの一覧は、%ZEN.Auxiliary.dataSetOpens in a new tab のクラス・ドキュメントを参照してください。
%ZEN.Component.dynaGridOpens in a new tab をプログラムを使用して操作する場合、サーバ側では、dynaGrid オブジェクトの dataSet プロパティを介して dataSet オブジェクトにアクセスできます。クライアントでは、dataSet に直接アクセスできません。この場合、dynaGrid オブジェクトの getDataSet メソッドを使用して dataSet オブジェクトを取得する必要があります。
サーバ・メソッド | 説明 |
---|---|
%Clear | dataSet のサイズやディメンジョン数を変更せずに、その内容をクリアします (すべてのセルを "" に設定します)。 |
%GetArray | dataSet の内容を、セル (行、列、ページ) の 1 から始まるディメンジョン・アドレスを添え字とする、多次元配列として取得します。この配列は、参照によって %GetArray に渡されます。 |
%GetDimensions | dataSet のディメンジョン数を返します。 |
%GetDimSize | ディメンジョン (行、列、ページ) を表す 1 から始まる番号を受け取り、そのディメンジョンのセル数を返します。 |
%GetLabel |
以下の 2 つの数値を受け取ります。
%GetLabel は、指定された位置のラベルの値を返します。 |
%GetValue | グリッド (行、列、ページ) 内の特定のセルを示す 1 から始まる番号を最大 3 つ (行、列、ページ) 受け取ります。その位置のセルの値を取得します。 |
%SetArray |
以下の最大 4 つの引数を受け取ります。
%SetArray は、配列の内容を dataSet にコピーします。 |
%SetDimensions | dataSet のディメンジョン数を 1、2、または 3 に設定します。 |
%SetLabel |
以下の 3 つの引数を受け取ります。
%SetLabel は、指定された位置のラベルに文字列をコピーします。 |
%SetValue |
以下の最大 4 つの引数を受け取ります。
%SetValue は、指定された位置のセルの値を設定します。さらに、%SetValue は、必要に応じてディメンジョン・サイズを更新します。 |
<gridRow>
0 より大きいディメンジョンを持つ <dynaGrid> では、グリッドの初期ディメンジョンを定義する 1 つ以上の <gridRow> 要素と <gridColumn> 要素を指定する必要があります。<gridRow> は、1 次元、2 次元、または 3 次元の <dynaGrid> のディメンジョン 1 を定義します。
<gridRow> 要素は、%ZEN.Auxiliary.gridRowOpens in a new tab クラスの XML プロジェクションであり、次のテーブルで説明する属性をサポートします。
属性 | 説明 |
---|---|
height |
この行に適用する高さの HTML 値。0.3in、3% など。 |
hidden |
True を指定すると、この行は表示されません。既定値は False です。 hidden で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
label |
行の既定のテキスト・ラベル。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
readOnly |
True の場合、この行のセルは読み取り専用になります。ユーザはそのセルを編集できません。既定値は False です。 readOnly で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。"Zen 属性のデータ型" を参照してください。 |
rowName | 行の論理名。 |
style |
この行のセルに適用する CSS スタイル。例えば、以下のようになります。 color: red; 指定されたセルに対して有効な列スタイルおよび行スタイルがある場合、列スタイルの前に行スタイルが適用されます。これは、列スタイルで行スタイルがオーバーライドされることを示します。 |
title |
この行の上にマウス・ポインタを置いたときに表示されるヘルプ・テキスト。指定されたセルに対して有効な列タイトルおよび行タイトルがある場合、列タイトルが行タイトルをオーバーライドします。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
プログラムで %ZEN.Component.dynaGridOpens in a new tab を扱うときは、dynaGrid の rows プロパティのメンバとして <gridRow> 要素を扱います。これは、%ZEN.Auxiliary.gridRowOpens in a new tab オブジェクトのリスト・コレクションです。XData Contents の元の <dynaGrid> で定義される各 <gridRow> は、rows コレクションのメンバになり、<dynaGrid> 内の位置の順序を表す 1、2、3 といった番号が付けられます。
<gridColumn>
0 より大きいディメンジョンを持つ <dynaGrid> では、グリッドの初期ディメンジョンを定義する 1 つ以上の <gridRow> 要素と <gridColumn> 要素を指定する必要があります。<gridColumn> は、2 次元または 3 次元の <dynaGrid> のディメンジョン 2 を定義します。
<gridColumn> 要素は、%ZEN.Auxiliary.gridColumnOpens in a new tab クラスの XML プロジェクションであり、次のテーブルで説明する属性をサポートします。
属性 | 説明 |
---|---|
columnName | 列の論理名。 |
hidden |
True を指定すると、この列は表示されません。既定値は False です。 hidden で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
label |
列の既定のテキスト・ラベル。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
readOnly |
True の場合、この列のセルは読み取り専用になります。ユーザはそのセルを編集できません。既定値は False です。 readOnly で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
style |
この列のセルに適用する CSS スタイル。例えば、以下のようになります。 color: red; 指定されたセルに対して有効な行スタイルおよび列スタイルがある場合、列スタイルの前に行スタイルが適用されます。これは、列スタイルで行スタイルがオーバーライドされることを示します。 |
title |
この列の上にマウス・ポインタを置いたときに表示されるヘルプ・テキスト。指定されたセルに対して有効な列タイトルおよび行タイトルがある場合、列タイトルが行タイトルをオーバーライドします。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
width |
この列に適用する幅の HTML 値。0.3in、3% など。 |
プログラムで %ZEN.Component.dynaGridOpens in a new tab を扱うときは、dynaGrid の columns プロパティのメンバとして <gridColumn> 要素を扱います。これは、%ZEN.Auxiliary.gridColumnOpens in a new tab オブジェクトのリスト・コレクションです。XData Contents の元の <dynaGrid> で定義される各 <gridColumn> は、columns コレクションのメンバになり、<dynaGrid> 内の位置の順序を表す 1、2、3 といった番号が付けられます。
<dynaGrid> の属性
<dynaGrid> 要素は XData Contents ブロック内に配置すると、以下の属性を割り当てることができます。プログラムで <dynaGrid> を扱うときは、これらの属性を dynaGrid オブジェクトのプロパティとして使用できます。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 |
<dynaGrid> は、あらゆる Zen コントロールと同じ汎用属性を持ちます。詳細は、“コントロールの属性” を参照してください。 他のほとんどのコントロールと異なり、<dynaGrid> は単一の value を持ちません。また、<dynaGrid> の width は、グリッドのレイアウト決定に関して特別な役割を果たします。詳細は、このテーブルの後の “<dynaGrid> のレイアウト” セクションを参照してください。 |
columnWidth |
幅が指定されていない列の既定の幅。columnWidth の値はピクセル単位 (75px など) で指定する必要があります。既定値は 100px です。 columnWidth が設定されておらず、<gridColumn> の width も指定されていない場合は、グリッドの残りの幅を、幅が指定されていない列の数で割ることで、列の幅が計算されます。 詳細は、このテーブルの後の “<dynaGrid> のレイアウト” セクションを参照してください。 |
controllerId | この <dynaGrid> がデータ・コントローラに関連付けられている場合、controllerId 属性は、この <dynaGrid> のデータを提供するコントローラを表します。controllerId の値は、その <dataController> に指定した id 値と一致している必要があります。“モデル・ビュー・コントローラ” の章を参照してください。 |
currColumn | グリッドで現在選択されているセルの列番号 (先頭番号は 1)。既定値は (ユーザが選択を行うまで) 1 です。 |
currPage | グリッド内に現在表示されているデータのページ番号 (先頭番号は 1)。このグリッドに関連付けられているデータ・セットに 3 次元データがある場合、currPage は現在表示されているページ (3 番目のディメンジョン) を表します。既定値は 1 です。 |
currRow | グリッドで現在選択されているセルの行番号 (先頭番号は 1)。既定値は (ユーザが選択を行うまで) 1 です。 |
gridClass | グリッドを表示する HTML テーブルに適用される CSS クラス。 |
gridLabel |
左上隅のセルに表示するキャプション。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。 “Zen 属性のデータ型” を参照してください。 |
nowrap |
True の場合、セルの内容はグリッドの中でワード・ラップされません。False の場合は、ワード・ラップされます。既定は True です。 nowrap で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
onchangecell |
<dynaGrid> の onchangecell イベント・ハンドラ。ユーザがセルの内容を変更するたびに、Zen によってこのハンドラが呼び出されます。“Zen コンポーネントのイベント・ハンドラ” を参照してください。 onchangecell 属性を省略すると、既定の動作では、ユーザが入力した値がセルに割り当てられます。 |
onclickcolumn | ユーザが列ヘッダ (列の最上部) のセルをクリックするたびに実行されるクライアント側 JavaScript 式。 |
onclickrow | ユーザが行ヘッダ (行の左端) のセルをクリックするたびに実行されるクライアント側 JavaScript 式。 |
OnCreateDataSet | OnCreateDataSet の値は、この <dynaGrid> に関連付けられたデータ・セットを指定するサーバ側コールバック・メソッドの名前です。詳細は、“<dynaGrid> のデータ・セット” を参照してください。 |
ondblclick | ユーザが <dynaGrid> をダブルクリックするたびに実行されるクライアント側 JavaScript 式。 |
ondrawcell | <dynaGrid> によってセルが描画される直前に実行されるクライアント側 JavaScript 式。このイベント・ハンドラが値を返す場合、この値はセルの内容を記述する DHTML として使用されます。この規約により、<dynaGrid> 内でカスタム・セル・フォーマットを表示できます。 |
oneditcell | <dynaGrid> のいずれかのセルでユーザ入力を受け付ける準備ができたときに実行されるクライアント側 JavaScript 式。oneditcell イベント・ハンドラが値を返す場合、この値はそのセルで使用されるエディタを表示する DHTML として使用されます。oneditcell を使用すると、<dynaGrid> 内でカスタム・セル・エディタを表示できます。既定の動作では、HTML 入力コントロールをグリッドの該当領域の上に配置して、ユーザがデータを入力できるようにします。この既定値をオーバーライドする必要はありませんが、可能です。 |
onnotifyView |
<dynaGrid> の onnotifyView イベント・ハンドラ。“Zen コンポーネントのイベント・ハンドラ” を参照してください。この属性は、<dynaGrid> がデータ・コントローラに関連付けられている場合に適用されます。この <dynaGrid> に接続されたデータ・コントローラがイベントを発生するたびに、Zen によってこのハンドラが呼び出されます。“モデル・ビュー・コントローラ” の章を参照してください。 |
onselectcell | ユーザが新しいセルに移動するたびに実行されるクライアント側 JavaScript 式。onselectcell が呼び出される前に、現在のセルの行番号と列番号が更新されます。イベント・ハンドラには、現在のセルの行番号と列番号 (開始番号は 1) が格納されている row と col の 2 つの変数が渡されます。 |
rowLabelWidth |
rowLabelWidth は、行ラベルの列に適用されます。rowLabelWidth の値はピクセル単位 (75px など) で指定する必要があります。既定値は 100px です。 詳細は、このテーブルの後の “<dynaGrid> のレイアウト” セクションを参照してください。 |
scrollIntoView |
True の場合、Zen では JavaScript の scrollIntoView 関数を使用して、グリッド内で現在選択されている項目が見えるようにします。 scrollIntoView で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showColumnLabels |
True の場合、グリッドの最上部の行に列ラベルが表示されます。既定値は True です。 showColumnLabels で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showRowLabels |
True の場合、グリッドの一番左側の列に行ラベルが表示されます。既定値は True です。 showRowLabels で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
<dynaGrid> のレイアウト
<dynaGrid> の既定のレイアウトが希望と合わない場合は、レイアウトを調整できます。<dynaGrid> のレイアウトには、いくつかの要因が関係しています。これらの要因は、相殺し合って意外な結果をもたらす可能性があります。ここでは、<dynaGrid> の基本レイアウト・スキームについて説明すると共に、希望どおりのページ・レイアウトを作成するために制御できる要因について説明します。
<dynaGrid> に対して指定する寸法によって、グリッドのコンテンツを表示するためのページ上のスペースが確保されます。グリッドのコンテンツは、<dynaGrid> の行と列で構成されます。実際には、コンテンツのサイズは、確保した表示スペースと比べて大きいことも、小さいことも、等しいこともあります。大きいか小さい場合は、表示スペースをコンテンツに合わせてサイズ変更できます。または表示スペースを固定して、グリッド・コンテンツの端部を “トリミング” したり “覆い隠したり” できます。これらのオプションは制御できます。
<dynaGrid> のレイアウトに関する主な相互作用は、次の 2 つの要因の間で発生します。
-
<dynaGrid> に対して指定された幅に基づいて、ページ上の表示スペースが確保されます。
-
<dynaGrid> 内の列に対して指定された幅に基づいて、表示スペースを基準にしたグリッド・コンテンツのレイアウトが決定されます。
<dynaGrid> を表示するために確保されたスペース
<dynaGrid> の属性を使用して指定した寸法によって、<dynaGrid> の指定内容に基づいて Zen によって生成されるエンクロージング HTML <div> のサイズが指定されます。この <div> のサイズは、<dynaGrid> の表示スペースのサイズです。このサイズを指定するには、<dynaGrid> の width 属性を指定するか、関連する CSS セクションで width 属性を指定するか、<dynaGrid> の enclosingStyle 属性で幅の値を指定します。
得られる <dynaGrid> のレイアウトは、幅が "auto" に設定されているのか、特定の固定幅に設定されているのかによって異なります。"auto" については 1 つの動作が存在し、固定幅については幅の設定内容に応じていくつかの動作が存在します。<dynaGrid> の幅を設定していない場合は、幅は既定値の "auto" に設定されます。
<dynaGrid> の幅設定のレイアウト・バリエーションは次のとおりです。
-
"auto" — 表示スペースは、グリッド・コンテンツの幅に合わせて拡大または縮小されます。
-
固定幅 — 次の 3 つのケースがあります。
-
<dynaGrid> のコンテンツが固定の表示スペースより大きいことが判明した場合でも、表示スペースのサイズはコンテンツに合わせて拡大されません。代わりに、グリッドの非表示領域を表示するためのスクロール・バーが追加されます。
-
<dynaGrid> のコンテンツが固定の表示スペースより小さいことが判明した場合でも、表示スペースのサイズはコンテンツに合わせて縮小されません。余ったスペースは空白のままになります。
-
<gridColumn> のすべての width 値がパーセントで指定されている場合は、表示スペースのサイズとぴったり合うように、列は比例的に拡大または縮小されます。
-
<dynaGrid> のデータ列の幅
<dynaGrid> のコンテンツのレイアウトを制御するには、<dynaGrid> の属性である rowLabelWidth と columnWidth、および <gridColumn> の属性である width を使用して列の幅を指定します。以下のセクションでは、これらの属性に指定した値がどのようにレイアウト結果に反映されるのかを説明します。
<dynaGrid> の rowLabelWidth
rowLabelWidth は、グリッドの左端に表示される行ラベルの列に適用されます。行ラベルの列はグリッドの垂直ヘッダの役割を果たすため、グリッド・データが含まれた <gridColumn> 要素と同じようには扱われません。
<gridColumn> の width 属性とは異なり、<dynaGrid> の rowLabelWidth はパーセント値をサポートしていません。rowLabelWidth の値はピクセル単位 (75px など) で指定する必要があります。既定値は 100px です。
<dynaGrid> の columnWidth
columnWidth は、幅が指定されていない列の既定の幅を指定します。<dynaGrid> の columnWidth は、パーセント値をサポートしていません。columnWidth の値はピクセル単位 (75px など) で指定する必要があります。既定値は 100px です。
<dynaGrid> で既定の幅設定 ("auto") が使用されており、<gridColumn> のすべての width 値がパーセントで指定されている場合は、columnWidth は既定の計算を行うために必須です。この場合は、Zen によって columnWidth を使用してデータ列の表示幅が計算されます。詳細は、“<gridColumn> の width” セクションを参照してください。
<dynaGrid> の合計幅は、すべてのデータ列の合計幅と、rowLabelWidth に指定されたピクセル数と、指定されたマージン、境界線、またはセル・パディングを表示するために必要なスペースを足し合わせたものです。<dynaGrid> の表示スペースのサイズは、グリッド全体が表示されるように自動的に調整されます。
<gridColumn> の width
<gridColumn> の width 属性に基づいて個別のデータ列の幅が決定されます。この属性の値はピクセル単位 (px) またはパーセント単位 (%) で指定できます。特定の <dynaGrid> の指定内容に含まれる複数の <gridColumn> 要素に対して、ピクセル単位とパーセント単位を自由に組み合わせて指定できますが、結果は次のようになります。
-
ピクセル単位の列幅は常に採用されます。
-
一部の列がパーセント単位で指定されており、他の列がピクセル単位で指定されている場合は、Zen は、ピクセル単位の列のサイズを使用して残りの列の幅を計算します。
-
すべての列幅がパーセント単位で指定されており、<dynaGrid> に固定サイズが指定されている場合は、グリッド側で適合サイズ調整処理が実行されて、グリッド、付随するヘッダ、境界線、および列データが定義済みの表示スペース内にぴったり収まるようになります。
すべての列幅がパーセント単位で指定されており、<dynaGrid> で "auto" のサイズが設定されているか、サイズがまったく指定されていない場合は、最も幅の狭い列には <dynaGrid> の columnWidth で指定された幅が割り当てられ、他のすべての列のサイズは、次のようにこの列のサイズを基準にして決定されます。
-
最も小さいパーセント値が指定された <gridColumn> を探します。これが最も幅の狭い列です。
-
<dynaGrid> の columnWidth 値を参照して、このピクセル数を最も幅の狭い列の幅として割り当てて、この結果を使用して 1% に対応するピクセル数を計算します。
例えば、<gridColumn> の最も小さい width 値が 5% であり、<dynaGrid> の columnWidth 値が 75px の場合は、Zen は、このグリッド内のすべてのデータ列にまたがる 150 ピクセルという合計幅について、1% あたり 15 ピクセルが存在すると計算します。
-
他のすべてのデータ列のパーセント値をピクセル数に変換します。
<dataGrid>
<dataGrid> は、テーブル形式のデータを表示および編集するためのコンポーネントを実装します。これは、HTML5 のコンポーネントです。HTML5 準拠のブラウザでのみ正しく動作します。
<dataGrid> には、以下の属性があります。
属性 | 説明 |
---|---|
コントロール・コンポーネントの属性 |
<dataGrid> には、あらゆる Zen コントロールと同様の汎用属性があります。詳細は、“コントロールの属性” を参照してください。 |
canResizeColumns |
True の場合、ユーザはカーソルを使用して列のサイズを変更できます。既定値は True です。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
cellHoverColor |
セルの上にカーソルを置いたときの、セルの背景色を指定します。既定値は #EEEEEE です。“データ・グリッドのレイアウト” を参照してください。 |
checkedRows |
コンマ区切りの値を格納する文字列。この文字列内の各値は、行セレクタ・チェック・ボックスが選択されている行の行番号を指定します (先頭番号は 1)。すべての行が選択される場合は、この値を "all" に設定します。 チェック・ボックスをユーザに表示して使用できるようにするには、プロパティ showRowSelector は “true” に設定する必要があります。 |
columnHeaderStyle |
このグリッドの列のヘッダに適用される追加の CSS スタイル。列のヘッダの表示/非表示は、プロパティ showColumnLabels で制御します。columnHeaderStyle を使用して、rowHeight または rowHeaderStyle を使用した行の高さ設定とは独立した列のヘッダの height を設定できます。 |
columnLabelSpan |
複数の子ラベルを含む親の列ラベルの表示方法を指定します。True の場合、それぞれの子のセットに対して 1 つの親ラベルが表示されます。False の場合、それぞれの子に対して親の行ラベルが繰り返されます。既定値は、false です。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
columnWidth |
幅が指定されていない列の既定の幅 (ピクセル単位)。 columnWidth が設定されておらず、列の width も指定されていない場合は、グリッドの残りの幅を、幅が指定されていない列の数で割ることで、列の幅が算出されます。 |
currCellBackground | 現在選択されているセルに適用する背景色。既定値は #D0D0FF です。“データ・グリッドのレイアウト” を参照してください。 |
currCellColor | 現在選択されているセルに適用する前景色。既定値は #000000 です。“データ・グリッドのレイアウト” を参照してください。 |
currColumn | グリッドで現在選択されているセルの列番号 (先頭番号は 1)。既定値は (ユーザが選択を行うまで) 1 です。 |
currPage | グリッド内に現在表示されているデータ・ページのページ番号 (先頭番号は 1)。グリッドのデータが複数のページに表示される場合は、現在表示されているページが currPage で示されます。既定値は 1 です。getCurrPage メソッドを使用すると、currPage の値を確認できます。属性 pageSize は、各ページの行数を指定します。“ページング” のセクションを参照してください。 |
currRow | グリッドで現在選択されているセルの行番号 (先頭番号は 1)。既定値は (ユーザが選択を行うまで) 1 です。 |
evenRowBackground |
属性 showZebra が True の場合に偶数行に適用する背景色。既定値は "#F8F8F8" です。“データ・グリッドのレイアウト” を参照してください。 |
evenRowColor |
属性 showZebra が True の場合に偶数行に適用する前景色。既定値は #000000 です。“データ・グリッドのレイアウト” を参照してください。 |
filterKey |
既にクライアント側にある結果に、フィルタを適用するために使用するキー (指定されている場合)。“フィルタ処理” を参照してください。 |
format |
このグリッドのセルに適用される既定の形式。これは DeepSee 形式の文字列です ("###.##" など)。行と列レベルの形式設定は、この形式をオーバーライドします。 |
gridStatusStyle |
グリッドのステータス領域に適用する CSS スタイル (オプション)。“データ・グリッドのレイアウト” を参照してください。 |
gridTitle |
グリッドの上部に沿って表示されるタイトル (オプション)。 |
gridTitleStyle |
グリッドのタイトルに適用する CSS スタイル (オプション)。“データ・グリッドのレイアウト” を参照してください。 |
multiSelect |
True の場合、ユーザはグリッド内でセルの範囲を選択できます。既定値は、false です。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
oddRowBackground |
属性 showZebra が True の場合に奇数行に適用する背景色。既定値は #FFFFFF です。“データ・グリッドのレイアウト” を参照してください。 |
oddRowColor |
属性 showZebra が True の場合に奇数行に適用する前景色。既定値は #000000 です。“データ・グリッドのレイアウト” を参照してください。 |
pageSize |
グリッドが複数ページにデータを表示する場合、各ページに表示する行数。getPageSize メソッドを使用すると、pageSize の値を確認できます。既定値は 0 です。この場合、単一のページにすべての行を表示します。“ページング” のセクションを参照してください。 |
pagingMode |
サーバとクライアントのどちらでページングを行う必要があるかを指定します。既定値は "client" です。 |
rowHeaderStyle |
このグリッドの行のヘッダに適用される追加の CSS スタイル。行のヘッダの表示/非表示は、プロパティ showRowLabels で制御します。このプロパティを使用して height が設定されていて、rowHeight も設定されている場合は、グリッドは 2 つの値のうちの大きいほうの値を使用します。 |
rowHeight |
既定の高さ (ピクセル単位)。高さが指定されていない行に使用します。定義されていない場合は、高さが計算されます。height が rowHeaderStyle でも設定されている場合は、グリッドは 2 つの値のうちの大きいほうの値を使用します。 |
rowLabelSpan |
複数の子ラベルを含む親の行ラベルの表示方法を指定します。True の場合、それぞれの子のセットに対して 1 つの親ラベルが表示されます。False の場合、それぞれの子に対して親の行ラベルが繰り返されます。既定値は True です。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
rowLabelWidth |
行ラベルの列の幅を指定します。指定した数値は、ピクセル数として解釈されます。値を指定しない場合は、幅が計算されます。 |
selectedRange |
整数のコンマ区切りリストとして、現在選択されているセルの範囲を指定します。このリストの形式は、startRow、startCol、endRow、endCol になります。すべてのセルの番号は 1 が先頭です。範囲が "" の場合は、選択されているセルはありません。このプロパティは、属性 multiSelect が True の場合にのみ使用されます。 |
selectMode |
グリッド内での選択動作を指定します。この値が "rows" の場合、ユーザは一度にすべての行を選択します。この値が "cells" の場合、ユーザは個々のセルの選択、およびそれらの間の移動が可能です。既定値は "rows" です。 |
showColumnLabels |
True の場合、グリッドの最上部の行に列ラベルが表示されます。既定値は True です。“データ・グリッドのレイアウト” を参照してください。 既定の列ラベルは、データ・ソースにより指定された列名です。列ラベルは、<columnDescriptor> の caption プロパティを使用して指定できます。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showRowLabels |
True の場合、グリッドの一番左側の列に行ラベルが表示されます。既定値は True です。“データ・グリッドのレイアウト” を参照してください。 既定の行ラベルは、行に割り当てられた行番号です (1 が先頭)。行ラベルは、<rowDescriptor> の caption プロパティを使用して指定できます。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showRowSelector |
True の場合、各行にチェック・ボックスが表示され、行を選択できます。showColumnLabels も True の場合、ユーザはグリッドの左端の列にあるチェック・ボックスを使用して、すべての行を一度に選択または選択解除できます。既定値は、false です。“データ・グリッドのレイアウト” を参照してください。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showZebra |
True の場合、行に交互に異なる色が適用された、“縞模様” のグリッドが表示されます。既定値は True です。“データ・グリッドのレイアウト” を参照してください。 属性 oddRowBackground と属性 evenRowBackground で使用する背景色を指定し、oddRowColor と evenRowColor で前景色を指定します。 基本のデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
sortColumn |
並べ替え可能なテーブルの場合、結果の並べ替えに使用する列の列番号 (先頭番号は 1) を指定します。並べ替えの方向は sortOrder で指定します。既定値は 0 です。これは、並べ替える列がないことを意味します。詳細は、“並べ替え” を参照してください。 |
sortMode |
並べ替えられる列の場所を示します。指定可能な値は "client" または "server" です。既定値は "client" です。今回のリリース以降、サーバ側の並べ替えは実装されなくなります。 |
sortOrder |
並べ替え可能なテーブルの場合、この属性は、sortColumn で指定した列の値の並べ替え順序を指定します。指定可能な値は "" (並べ替えなし)、"asc" (昇順)、または "desc" (降順) です。既定値は並べ替えなしです。詳細は、“並べ替え” を参照してください。 |
style |
このグリッドのセルに適用される追加のスタイル。これは、行レベルと列レベルのスタイルの前に適用されます。 |
summaryRow |
集計行の記述子 (オプション)。 |
useEngine | このプロパティを 0 に設定すると、グリッドをロードしてレンダリングするときのコード実行が無効になります。これは、特定の列で等号 (=) を入力するが、これが式ではない場合に便利です。これはグリッド全体の設定です。 |
valueColumn |
テーブル内の行に値を設定する列の列番号 (先頭番号は 1)。既定値は 1 です。 |
以下の図は、<dataGrid> の主なコンポーネントを示しています。この図では、ラベル付きの項目に加え、奇数行と偶数行の色と背景色についても示しています。
以下の属性は、イベント・ハンドラを指定します。“Zen コンポーネントのイベント・ハンドラ” を参照してください。
属性 | 説明 |
---|---|
onaction |
ユーザがセル内で操作 (列に定義されたチェック・ボックス、ボタン、またはリンクのクリックなど) を実行したときに実行されるクライアント側の JavaScript 式。通常、この式は、ページ・クラスで定義されたクライアント側 JavaScript メソッドを呼び出します。このメソッドは、グリッドの “onaction イベント・ハンドラ” になります。この呼び出しが行われる前に、現在のセルの行番号と列番号が更新されます。このイベント・ハンドラには、3 つの変数 row、name、および value が渡されます。これらの変数には、現在のセルの行番号 (先頭番号は 1)、列の論理名、および現在のアクション・コントロールの値 (該当する場合) が格納されます。 |
onchangecell |
グリッドの onchangecell イベント・ハンドラ。ユーザがセルの値の編集を終了するたびに、Zen によってこのハンドラが呼び出されます。“Zen コンポーネントのイベント・ハンドラ” を参照してください。この呼び出しが行われる前に、現在のセルの行番号と列番号が更新されます。イベント・ハンドラには、新しいセルの値が渡されます。このハンドラは、セルに配置される値を返します。編集をキャンセルする場合は NULL を返します。 |
ondrawcell |
グリッドの ondrawcell イベント・ハンドラ。セルが描画される直前に、Zen によってこのハンドラが呼び出されます。“Zen コンポーネントのイベント・ハンドラ” を参照してください。このイベント・ハンドラには、value、row、および col (先頭番号は 1) が渡されます。このイベント・ハンドラが値を返す場合、その値はセルの内容をレンダリングするために使用されます。このイベント・ハンドラの返り値は、NULL (セルに既定のレンダリングを使用する場合)、または以下のプロパティが含まれるオブジェクトのどちらかになります。
|
onfiltercell |
グリッドの onfiltercell イベント・ハンドラ。ユーザが新しい filterKey を入力すると、Zen によってこのハンドラが呼び出されます。このイベント・ハンドラには、オブジェクト info が渡されます。このオブジェクトには、プロパティ row、col、value、および key が含まれます。このイベント・ハンドラは、セルを含む行がフィルタと一致する場合は True を返し、それ以外の場合は False を返します。 |
ongetlookupdata |
グリッドの ongetlookupdata イベント・ハンドラ。このハンドラは、検索列のポップアップに表示するデータの JavaScript 配列を返します。返り値は、オブジェクトまたはリテラル値の配列になります。 |
ongetstatus |
グリッドの ongetstatus イベント・ハンドラ。定義されている場合、このイベント・ハンドラは、このグリッドのステータス領域に表示される HTML を返します。このステータス領域は、グリッドの下部に配置されます。 |
ongettitle |
グリッドの ongettitle イベント・ハンドラ。定義されている場合、このイベント・ハンドラは、このグリッドのタイトル領域に表示される HTML を返します。このタイトル領域は、グリッドの上部に配置されます。これは、gridTitle プロパティ (定義されている場合) よりも優先されます。 |
onheaderclick |
グリッドの onheaderclick イベント・ハンドラ。定義されている場合、このイベント・ハンドラは、ユーザが行ヘッダまたは列ヘッダをクリックしたときに起動されます。変数 which は、"row" (行) と "column" (列) のどちらがクリックされたかを示します。変数 index は、ヘッダの順序数 (先頭は 1) を返します。 |
onselectcell | ユーザが新しいセルに移動するたびに実行されるクライアント側 JavaScript 式。onselectcell が呼び出される前に、現在のセルの行番号と列番号が更新されます。イベント・ハンドラには、現在のセルの行番号と列番号 (開始番号は 1) が格納されている row と col の 2 つの変数が渡されます。“行とセルの選択” を参照してください。 |
onselectrow | グリッドの onselectrow イベント・ハンドラ。定義されている場合は、ユーザがグリッド内で表示されている行セレクタ・チェック・ボックスを切り替えたときにこのイベントが発生します。1 つの変数 range がイベント・ハンドラに渡されます。range は、現在チェックされている行を列挙する文字列です。この変数には 2 つの特別な値があります。"" は、現在チェックされている行がないことを示し、逆の値 "all" は、すべての行がチェックされていることを示します。これら両端の間の値について、range パラメータは現在チェックされている行のインデックス (1 から始まる) をリストする CSV 文字列になります。このイベントは行セレクタの切り換えとリンクされているため、showRowSelector が True の場合にのみ発生します。“行とセルの選択” を参照してください。 |
データ・グリッドの作成
空の <dataGrid> コントロールは、そのコンポーネントを Zen ページに追加するだけで作成できます。
<dataGrid id="grid"/>
<dataGrid> のサイズは、そのページの XData Style セクションに CSS スタイルを配置することで制御できます。例えば、グリッドの id が 'grid' の場合は、次のようになります。
#grid { width: 600px; height: 600px; }
また、グリッドのサイズは、JavaScript を使用し、グリッドの div の幅と高さを設定してから、グリッドの adjustSizes メソッドを呼び出して、グリッドの内部パーツをレイアウトすることでも制御できます。
zen('grid').adjustSizes();
グリッドのデータへの接続
<dataGrid> は、データ・ビュー・コンポーネントであり、<altJSONProvider> に接続できます。"Zen アプリケーションの開発" の “Zen の JSON コンポーネント” セクションを参照してください。例えば、オブジェクトの配列を提供する <altJSONProvider> があるとします。
<altJSONProvider id="json" OnGetArray="GetData" />
この <altJSONProvider> に <dataGrid> を接続するには、以下のように controllerId を設定します。
<dataGrid id="grid" controllerId="json" />
この時点で、グリッドには、<altJSONProvider> から提供されるデータが表示されます。この場合、<altJSONProvider> から提供されるすべてのプロパティが列として表示され、プロバイダから提供されるオブジェクト (データ系列) ごとに 1 つの行が含まれます。
フィルタ処理
<dataGrid> は、グリッド・コンテンツのクライアント側フィルタ処理をサポートしています。フィルタ処理により、実際に表示されるデータを制限します。この制限を行うには、クライアント側のデータをグリッドに表示する前に、このデータにフィルタ処理関数を適用します。既定のフィルタ処理の動作は、onfiltercell イベント・ハンドラをオーバーライドすることでオーバーライドできます。
検索
<dataGrid> は、サーバ側の検索をサポートしています。検索を実行するには、グリッドに表示するデータのフェッチに使用されているパラメータを変更します。一般に、これを行うには、<altJSONProvider> のコンテンツを再ロードします。
並べ替え
<dataGrid> は、列全体の並べ替えをクライアント側でサポートしています。並べ替えに使用する列は、属性 sortColumn で指定します。列の並べ替え順序は、属性 sortOrder で決定されます。showColumnLabels が True の場合は、以下の図に示すように、並べ替えた列の列ラベルに、並べ替え方向を示す矢印が表示されます。
属性 sortMode には、クライアント側の並べ替えと、サーバ側の並べ替えを示す “client” と “server” のどちらかの値を設定できます。既定値は “client” です。今回のリリース以降、サーバ側の並べ替えは実装されなくなります。
ページング
<dataGrid> コンポーネントは、ページングをサポートしています。グリッドの各ページには、固定された行のセットが表示されます。ページングは、クライアントとサーバのどちらかで実行できます。クライアントでページングが行われると、グリッドはクライアントにすべての行とユーザ・ページをロードします。サーバでページングが行われると、グリッドはサーバから一度に 1 ページをロードします。
クライアント側のページングを使用するには、以下の操作を実行します。
-
<dataGrid> の pagingMode 属性を、"client" に設定します。
<dataGrid pagingMode="client" />
-
<dataGrid> の pageSize 属性を、ページごとに表示する行数に設定します。
<dataGrid="10"/>
グリッドに表示される行数が、pageSize で指定した数より大きい場合は、グリッドの下部にページングのボタンのセットが表示されます。“データ・グリッドのレイアウト” を参照してください。
サーバ側のページングを使用するには、以下の操作を実行します。
-
<dataGrid> の pagingMode 属性を、"server" に設定します。
<dataGrid pagingMode="server" />
-
<dataGrid> の pageSize 属性は無視されます。その代わりに、<altJSONSQLProvider> の pageSize 属性を設定します。
行とセルの選択
onselectcell および onselectrow プロパティを使用すると、エンド・ユーザが <dataGrid> 内で行またはセルを選択したときに実行するイベント・ハンドラを定義できます。例えば、<altJSONProvider> と <dataGrid> を含む Zen ページは以下のようになります。
<page xmlns="http://www.intersystems.com/zen">
<altJSONProvider id="json" OnGetArray="GetData" />
<dataGrid id="grid"
controllerId="json"
showRowSelector="true"
onselectrow="zenPage.rowSelected(range);" />
</page>
また、rowSelected コールバックは以下のように定義されます。
ClientMethod rowSelected(range) [ Language = javascript ]
{
alert("Selected rows are: "+range);
}
現在選択されている行を表示する警告メッセージをポップアップ表示します。同様に、次のページのようになります。
<page xmlns="http://www.intersystems.com/zen">
<altJSONProvider id="json" OnGetArray="GetData" />
<dataGrid id="grid"
controllerId="json"
multiSelect="true"
selectMode="cells"
onselectcell="zenPage.cellSelected(row, col);" />
</page>
また、cellSelected コールバックは以下のように定義されます。
ClientMethod cellSelected(row, col) [ Language = javascript ]
{
alert("Selected cell is: "+ row + ", " + col);
var rng = zen('grid').selectedRange
alert("Selected range is: " + rng);
}
列記述子
グリッドのコンテンツは、1 つまたは複数の <columnDescriptor> オブジェクトを定義することで、より直接的に制御できるようになります。グリッドに <columnDescriptor> オブジェクトが含まれていると、グリッドは、データ・コントローラが提供するすべてのデータを自動的には表示しなくなります。グリッドに表示する列ごとに、<columnDescriptor> を指定する必要があります。value プロパティは、各列に表示されるデータを指定します。
<dataGrid id="grid" controllerId="json">
<columnDescriptor value="100"/>
<columnDescriptor value="=[@Name]"/>
<columnDescriptor value="=[@City]"/>
</dataGrid>
この例のグリッドには、3 つの列が表示されます。最初の列の各セルには、値 "100" が表示されます。2 番目の列には、altJSONProvider で指定される Name プロパティの値が表示されます。先頭の等号 "=" 文字は、これが式 (または数式) であることを示します。[ ] 括弧で、識別子を囲みます。識別子 "@Name" は、データ・コントローラから提供される Name プロパティを指定します。
<columnDescriptor> には、以下の属性があります。
属性 | 説明 |
---|---|
align | この列に適用する、横方向の配置 (オプション)。配置の制御には、style プロパティではなく、これを使用します。 |
caption | この要素に適用するキャプション (オプション)。列ラベルのテキストとしてグリッドに表示されます。 |
columns | この列の子記述子 (オプション)。 |
format | この要素に適用する形式 (オプション)。 |
headerAlign | この列のヘッダに適用する横方向の配置 (オプション)。定義しない場合、align で指定された値が使用されます。配置の制御には、style プロパティではなく、これを使用します。 |
headerStyle | この列のヘッダに適用するスタイル文字列。 |
hidden | この列は表示しないでください。 |
image | image 列の場合、これは表示するイメージの名前になります。 |
ongetlookupspec | このイベントは、この列の検索 (ポップアップ) 情報を計算するために使用されます。 |
priority | この要素に適用する優先度 (オプション)。 |
readOnly | この要素に適用する readOnly 属性 (オプション)。True の場合、この列の内容は編集できません。既定値は、false です。 |
style | この列のスタイル文字列。 |
type |
<dataGrid> の selectMode プロパティを "cells" に設定すると、列記述子の type プロパティを使用して、セルが選択されたときにそのセルに表示される編集コントロールのタイプを指定できます。type プロパティに使用可能な値は、以下のとおりです。
|
value | この列の既定値 (オプション)。これは、リテラル値、または "=[@Name]" のような式になります。
先頭の等号 "=" 文字は、これが式 (または数式) であることを示します。[ ] 括弧で、識別子を囲みます。識別子 "@Name" は、データ・コントローラから提供される Name プロパティを指定します。 value 属性を指定しない場合、グリッドは、データ・コントローラからの値を指定された順番で表示します。 |
width | 最初のレンダリングでこの列に使用されるオプションの既定最小幅 (ピクセル単位)。実際の幅は、セル内のデータの実際の幅に合わせて大きくなるように適宜調整される場合があります。この設定を行っていても、エンド・ユーザが手動で列幅をより小さい値に変更することは可能です。 |
CSS を使用して、<dataGrid> 内の編集可能セルの基本ではない表示プロパティを変更できます。編集可能セルの CSS クラスは dgCellEditor です。例えば、以下の CSS は編集中にセルの背景を黄色に設定します。
.dgCellEditor {
background-color:yellow;
}
lookup セルの表示プロパティ、具体的にはユーザーが lookup リストを開くときにクリックするボタンのイメージを変更することもできます。CSS クラスは dgAction です。イメージ・ファイルに指定される URL は、Caché インストール・ディレクトリの下にある csp/broker ディレクトリに解決されます。例えば、以下の CSS は、lookup ボタン・イメージを設定します。
.dgAction {
background-image:url("lookupicon.png");
}
行記述子
グリッドのコンテンツは、1 つまたは複数の <rowDescriptor> オブジェクトを定義することで、より直接的に制御できるようになります。グリッドに <rowDescriptor> オブジェクトが含まれていると、グリッドは、データ・コントローラが提供する内容を自動的には表示しなくなります。グリッドに表示する行ごとに、<rowDescriptor> を指定する必要があります。
<dataGrid id="grid" controllerId="json">
<rowDescriptor caption="ROW 1"/>
<rowDescriptor caption="ROW 2"/>
<rowDescriptor caption="ROW 3"/>
</dataGrid>
<rowDescriptor> には以下の属性があります。
属性 | 説明 |
---|---|
caption | この要素に適用するキャプション (オプション)。行ラベルのテキストとしてグリッドに表示されます。 |
format | この要素に適用する形式 (オプション)。 |
priority | この要素に適用する優先度 (オプション)。 |
readOnly | この要素に適用する readOnly 属性 (オプション)。True の場合、この行の内容は編集できません。既定値は、false です。 |
rows | この行の子記述子 (オプション)。 |
style | この列のスタイル文字列。 |