Zen のテーブル
Zen のテーブルはデータ駆動型です。これは SQL クエリにより返された結果セットを取得し、HTML テーブルとして表示します。Zen のテーブルの結果セットを生成する方法には、さまざまなものがあります。SQL 文を指定する方法、事前に定義されている SQL クエリを参照する方法などのほか、SQL クエリを生成するために必要な入力を Zen に対して指定することもできます。
データが手元にあれば、結果テーブルのスタイルをどのように指定してもかまいません。次の図は簡単な例を示しています。このテーブルでは、1 行ごとの “ゼブラ” パターンを使用しています。このユーザは、テーブルに表示される結果をフィルタ処理するために、テーブルのヘッダにデータを入力しました。ここでは、X で始まる名前と Active ステータスを持ち、Assistants でもあるエントリのみを選択しています。
この章では、Zen のテーブルの使用方法について、以下のトピックで説明します。
-
Zen ページにテーブルを配置する方法
-
Zen のテーブルのデータ・ソースを識別する方法
-
必要に応じて、テーブル・クエリのパラメータを指定する方法
-
Zen のテーブルで使用できる全般的なスタイル・プロパティ
-
行および列に対してデータ固有のスタイルを定義する方法
-
スナップショット・モードでの複数ページで構成したテーブルのサポート、およびリフレッシュ操作の簡略化
-
Zen のテーブルでのユーザ対話処理
-
テーブルの更新処理の機能と、その要求方法
<tablePane>
<tablePane> は、さまざまな用途を持つ %ZEN.Component.tablePaneOpens in a new tab クラスの XML プロジェクションです。Zen ページ上にテーブルを配置するには、そのページ・クラスの XData Contents ブロック内に <tablePane> コンポーネントを配置します。
この章では、テーブルをサポートするために Zen に用意されているさまざまなコンポーネントと予備クラスについて説明します。以下のリストは、XData Contents でこれらのクラスを表示するために使用されている XML 要素をまとめています。これらのうち最も重要なものは、<tablePane> です。
-
“<tablePane>” — SQL クエリに基づいて HTML テーブルを描画します。結果セットの各行は、テーブルの 1 行として表示されます。<tablePane> には、必要に応じて以下の要素を記述できます。
-
“<parameter>” — 各 <parameter> 要素は、<tablePane> クエリを構成するために必要なパラメータを 1 つ提供します。
-
“<column>” — 各 <column> 要素では、結果テーブル内の特定の列に対するレイアウト、スタイル、および動作の詳細を指定します。<column> 要素は、テーブルで結果セット内のすべての列を表示するときには、オプションになります。<column> 要素は、<tablePane> で結果セットから表示する列を選択する必要があるときには、必須になります。
-
“<condition>” — 各 <condition> 要素は、テーブルにある行と列に適用するデータ固有の詳細を 1 つ定義します。例えば、ある特定の値を含むセルの背景色を赤にし、エラー状態を示すことができます。この値を含む特定のセルは、テーブルが更新するたびに異なる場合があります。Zen は、これらの詳細を追跡し、すべてのセルに適切に色を付けます。
-
-
“<tableNavigator>” — 複数のページで構成したテーブルのページ間を移動するための標準ボタン・セットを自動的に提供します。
-
“<tableNavigatorBar>” — <tableNavigator> の代わりに使用するボタンを提供し、複数ページで構成した大規模なテーブルを操作できるようにします。
<tablePane> には以下の汎用属性があります。
属性 | 説明 |
---|---|
dataSource |
%ResultSetOpens in a new tab のどの列を、どの順序で表示するかを指定します。可能な値は以下のとおりです。
<tablePane> で dataSource を省略すると、Zen では既定値 "query" が使用されます。ただし、<column> エントリを定義しておくと、dataSource 値はすべて無視され、"columns" が使用されます。 |
initialExecute |
initialExecute が True の場合、<tablePane> は、テーブルが最初に表示されるときに、関連付けられたクエリを実行します。それ以外の場合、<tablePane> は要求に応じてこのクエリを実行します。既定値は True です。 initialExecute で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
unlockSession | <tablePane> コンポーネントへの更新で、サーバからデータを取得する際に CSP セッションをロック解除するかどうかを示します。この属性を True に設定すると、サーバ上で遅いクエリを実行している際に応答 UI の維持が容易になります。一般に、この機能はサーバがセッション・データを更新しないときに使用します。既定値は、false です。
unlockSession で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
<tablePane> には、レイアウト、スタイル、および動作の構成に使用できる追加属性が多数あります。以下のトピックでは、それらについて説明します。
データ・ソース
<tablePane> 要素では、次のいずれかの方法で、テーブルのデータ・ソースを示す必要があります。
-
“SQL クエリの指定”
-
“SQL 文の生成”。Zen で使用する簡単な記述を指定して SQL 文を生成する。
-
“クラス・クエリの参照” により結果セットを取得する。
-
“コールバック・メソッドの使用” により結果セットを取得する。
-
“プログラムによるデータソースの変更”。実行時にテーブルに対して行う。
これ以降のトピックでは、それぞれの方法について詳しく説明します。
使用するオプションに関係なく、すべての方法で maxRows 属性がサポートされます。これは、返されるデータのサイズを制御します。次のテーブルでは、maxRows について説明しています。
属性 | 説明 |
---|---|
maxRows |
取得する行の最大数。一般的なテーブルでは、表示する行数の最大値です。スナップショット・テーブルの場合、maxRows はスナップショットの最大サイズで、pageSize は 1 ページに表示される行数です。maxRows の既定値は 100 です。 <radioSet>、<select>、<dataListBox>、<dataCombo>、および <repeatingGroup> の各コンポーネントも maxRows 属性をサポートしています。 |
SQL クエリの指定
<tablePane> は、sql 属性の値として、完全な SQL 文を提供できます。以下はその例です。
<tablePane id="table"
sql="SELECT ID,Name FROM MyApp.Employees
WHERE Name %STARTSWITH ? ORDER BY Name"
>
<parameter value="Z"/>
</tablePane>
次のテーブルでは、sql について説明しています。
属性 | 説明 |
---|---|
sql |
この属性の値は完全な SQL 文であり、Zen は実行時にこの文を実行してテーブルのコンテンツを提供します。<radioSet>、<select>、<dataListBox>、<dataCombo>、および <repeatingGroup> の各コンポーネントも sql 属性をサポートしています。 SQL クエリに任意の入力パラメータ値を指定するには、<tablePane> コンテナ内に <parameter> 要素を配置します。詳細は、“クエリ・パラメータ” を参照してください。 |
sql 属性は、%ZEN.Component.tablePaneOpens in a new tab のプロパティ sql の XML プロジェクションです。したがって、sql 属性の値に含まれるすべての XML 特殊文字をエスケープする必要があります。例えば、「より小さい」を意味するシンボル < の代わりに、以下のように XML エンティティ < を使用する必要があります。
sql="select * from infonet_daten.abopos where lieferadresse=? and status<9"
以下のテーブルは、sql 文字列内に記述すると不具合の原因となる XML 特殊文字とその代替となる XML エンティティを示しています。
文字 | XML エンティティ | 説明 |
---|---|---|
> | > | 右山括弧 (“より大きい” を意味するシンボル)。 |
< | < | 左山括弧 (“より小さい” を意味するシンボル)。 |
& | & | アンパサンド。 |
' | ' | 一重引用符またはアポストロフィ。一重引用符で囲んだ文字列では、' エンティティを使用して ' 文字を表現する必要があります。 |
" | " | 二重引用符。二重引用符で囲んだ文字列では、" エンティティを使用して " 文字を表現する必要があります。 |
他のほとんどの %ZEN.Component.tablePaneOpens in a new tab プロパティとは異なり、sql プロパティを実行時にクライアントから設定することはできません。このプロパティは、XData Contents からのみ設定できます。これは、sql が暗号化された属性であるためです。sql 属性値はクライアントに送信される際、現在のセッション・キーを使用して暗号化されます。サーバに返された値は、自動的に解読されます。
これにより、ユーザがブラウザでページ・ソースを表示しても SQL 文の定義は表示されず、クライアント側のロジックでは勝手にクエリを構築できないようになります。セキュリティ上の理由から、クエリ操作は必ずサーバでのみできるように制限します。
SQL クエリの生成
<tablePane> コンポーネントは、簡単な記述に基づいて自動的にクエリを生成できる属性をサポートしています。この方法は、コールバック・メソッド (詳細は後述) を使用することと似ていますが、唯一の相違点として、Zen では、ユーザが指定したクエリの記述内容に基づいてコールバック・メソッドが自動的に生成されます。<dataListBox> および <dataCombo> も、これらの属性をサポートします。
属性 | 説明 |
---|---|
groupByClause | SQL の GROUP BY 節。"Year,State" など。groupByClause の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
orderByClause | SQL の ORDER BY 節。"Name,State" など。これを指定していない場合は、ユーザが列のヘッダをクリックすると、次に実行するクエリにはユーザの選択に基づいて適切な ORDER BY 節が記述されます。orderByClause の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
tableName | テーブルのデータを提供する SQL テーブルの名前。この値は、生成されたクエリの FROM 節で使用されます。tableName の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
whereClause |
SQL の WHERE 節。"Name='Elvis'" など。 XData Contents の <tablePane> 定義内で whereClause が指定されている場合、それにより、tablePane オブジェクトの whereClause プロパティの初期値が設定されます。クライアント側またはサーバ側のコードで後からこの whereClause プロパティの値を変更すると、新しい値で元の値がオーバーライドされます。つまり、当初、特定の値のみを表示するようにテーブルをセットアップしておいて、別のコード行により whereClause の値を変更できるということです。この場合、whereClause の値が更新されると、ユーザに別の値のセットが表示されることになります。 例えば、このテーブルで任意の列フィルタが定義されている場合、ユーザによって選択された現在のフィルタ値に基づいて、<tablePane> の WHERE 節が Zen で動的に作成されます。 whereClause の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
<tablePane> で SQL クエリを生成するには、以下の手順を実行します。
-
tableName 属性の値を指定します。
-
sql、queryClass、queryName、および OnCreateResultSet には値を指定しないでください。これらの属性はすべて、このトピックで説明している動作よりも優先されます。
この最初の 2 つの条件が成立していれば、dataSource の値は "columns" であると見なされます。
-
<tablePane> の内部に <column> 要素を記述して、1 つ以上の列の名前を定義します。列は 1 つ以上定義する必要があります。定義しないと、“SELECT リストがない” というエラーが生成されます。
-
クエリ・パラメータを追加するには、<tablePane> の内部に <parameter> 要素を記述します。
-
生成されたクエリに節を追加するには、<tablePane> の属性 groupByClause、orderByClause、または whereClause を指定するか、前述のテーブルで説明した既定値が使用されるようにします。
以下の簡単な例で説明します。
<tablePane id="table"
tableName="MyApp.Employee">
<column colName="ID" hidden="true"/>
<column colName="Name"/>
</tablePane>
この <tablePane> の例では、以下のような SQL 文が生成されます。
SELECT ID,Name FROM MyApp.Employee
Zen は、このクエリを実行してテーブルのコンテンツを提供します。この例では、ID 列は hidden とマークされています。つまり、その値はフェッチされ、条件やアクションの指定には使用できますが、表示はされません。hidden などの <column> の属性の詳細は、“テーブル列” を参照してください。
クラス・クエリの参照
<tablePane> は既存のクラス・クエリを参照し、%ResultSetOpens in a new tab オブジェクトを取得できます。この方法は次のコンポーネントでもサポートされています。<radioSet>、<select>、<dataListBox>、<dataCombo>、および <repeatingGroup>。
属性 | 説明 |
---|---|
queryClass | クエリを含むクラスの名前。queryName の値も指定する必要があります。 |
queryName | この <tablePane> の %ResultSetOpens in a new tab を指定するクラス・クエリの名前。queryClass の値も指定する必要があります。 |
<tablePane> に <parameter> 要素を記述すると、クエリに任意の入力パラメータ値を指定できます。以下はその例です。
<tablePane id="table"
queryClass="MyApp.Employee"
queryName="ListEmployees">
<parameter value="Sales"/>
<parameter value="NEW YORK"/>
</tablePane>
<tablePane> のパラメータの値は、%ResultSetOpens in a new tab オブジェクトの作成に使用された値です。この値は、どのような場合でも、クラス・クエリ内に設定されたの既定の値をオーバーライドします。
コールバック・メソッドの使用
<tablePane> はコールバック・メソッドを使用して %ResultSetOpens in a new tab オブジェクトを取得できます。以下の <tablePane> 属性は、このアプローチをサポートしています。<dataListBox>、<dataCombo>、および <altJSONSQLProvider> も、これらの属性をサポートしています。
属性 | 説明 |
---|---|
OnCreateResultSet |
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。詳細は、"OnCreateResultSet" を参照してください。 |
OnExecuteResultSet |
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。詳細は、"OnExecuteResultSet" を参照してください。 |
showQuery |
showQuery は、テーブルの生成に OnCreateResultSet コールバックが使用されており、かつそのコールバック・メソッドで、該当のクエリのテキストが記述されるように、QueryInfo オブジェクトの queryText プロパティが設定されている場合にのみ機能します。コールバック・メソッドを使用して SQL クエリを生成するさまざまなコンポーネントの中でも、<tablePane> および <dataCombo> のみが showQuery 属性をサポートします。 showQuery が True の場合、Zen ページには <tablePane> コンポーネントまたは <dataCombo> コンポーネントのコンテンツの指定に使用する SQL クエリが表示されます。これはアプリケーション開発段階でのトラブルシューティングに便利です。showQuery の既定値は False です。 showQuery で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 showQuery の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
OnCreateResultSet
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。このメソッドは、%ResultSetOpens in a new tab オブジェクトをインスタンス化し、適宜 %ZEN.Auxiliary.QueryInfoOpens in a new tab “QueryInfo プロパティ” を設定します。 Zen は、テーブルを描画するたびに、このメソッドを呼び出して、自動的に以下のパラメータを渡します。
-
%StatusOpens in a new tab — メソッドのステータスの出力パラメータ
-
%ZEN.Auxiliary.QueryInfoOpens in a new tab — <tablePane> の QueryInfo オブジェクト
コールバックは %ResultSetOpens in a new tab オブジェクトを返す必要があります。以下に、有効なメソッド・シグニチャを示します。このテーブルの後に示す詳細な例も参照してください。
Method CreateRS(Output tSC As %Status,
pInfo As %ZEN.Auxiliary.QueryInfo)
As %ResultSet
{ }
コールバックとして上のメソッドを使用するには、<tablePane> で OnCreateResultSet="CreateRS" と設定します。
これが定義されると、OnCreateResultSet が他の <tablePane> のデータ指定方法より優先されます。
OnExecuteResultSet
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。このメソッドは OnCreateResultSet コールバックで返された %ResultSetOpens in a new tab オブジェクトを実行します。Zen は、OnCreateResultSet コールバックの後、自動的にOnExecuteResultSet コールバックを呼び出して、これに以下のパラメータを渡します。
-
%ResultSetOpens in a new tab — OnCreateResultSet からの結果セット
-
%StatusOpens in a new tab — メソッドのステータスの出力パラメータ
-
%ZEN.Auxiliary.QueryInfoOpens in a new tab — <tablePane> の QueryInfo オブジェクト
オプションで、OnExecuteResultSet コールバックの呼び出しを抑制できます。その場合、OnCreateResultSet コールバックの最後に QueryInfo の queryExecuted プロパティを True に設定します。
OnExecuteResultSet コールバックは、結果セットが実行されたかどうかを示す %ZEN.Datatype.booleanOpens in a new tab を返す必要があります。以下に、このコールバックの有効なシグニチャを示します。
Method ExecuteRS(myRS As %ResultSet,
Output pSC As %Status,
pInfo As %ZEN.Auxiliary.QueryInfo)
As %Boolean
{ }
コールバックとして上のメソッドを使用するには、<tablePane> で OnExecuteResultSet="ExecuteRS" と設定します。
コールバックの例
ここでは、コールバック・メソッドを使用して tablePane の %ResultSetOpens in a new tab を作成するための、さらに詳しい例について説明します。このコールバック・メソッドは、tablePane の sortOrder プロパティおよび sortColumn プロパティの現在の値に応じて、動的な SQL 文を構成します。tablePane は、入力 %ZEN.Auxiliary.QueryInfoOpens in a new tab オブジェクトの対応するプロパティとして、これらの値を自動的にコールバック・メソッドに渡します。
また、このメソッドが終了する前に QueryInfo の queryText プロパティにどのように SQL 文のテキストが配置されるかという点にも注意してください。<tablePane> の showQuery の値が True の場合、このテーブルのほか、このテーブルを生成したクエリも表示されます。
Method CreateRS(Output tSC As %Status,
pInfo As %ZEN.Auxiliary.QueryInfo) As %ResultSet
{
Set tRS = ""
Set tSC = $$$OK
Set tSELECT = "ID,Name,Title"
Set tFROM = "MyApp.Employee"
Set tORDERBY = pInfo.sortColumn
Set tSORTORDER = pInfo.sortOrder
Set tWHERE = ""
// Build WHERE clause based on filters
If ($GET(pInfo.filters("Name"))'="") {
Set tWHERE = tWHERE _ $SELECT(tWHERE="":"",1:" AND ") _
"Name %STARTSWITH '" _ pInfo.filters("Name") _ "'"
}
If ($GET(pInfo.filters("Title"))'="") {
Set tWHERE = tWHERE _ $SELECT(tWHERE="":"",1:" AND ") _
"Title %STARTSWITH '" _ pInfo.filters("Title") _ "'"
}
Set sql = "SELECT " _ tSELECT _ " FROM " _ tFROM
Set:tWHERE'="" sql = sql _ " WHERE " _tWHERE
Set:tORDERBY'="" sql =
sql _ " ORDER BY " _tORDERBY _ $SELECT(tSORTORDER="desc":" desc",1:"")
Set tRS = ##class(%ResultSet).%New()
Set tSC = tRS.Prepare(sql)
Set pInfo.queryText = sql
Quit tRS
}
QueryInfo のプロパティ
以下のテーブルは、両方のコールバック・メソッドのシグニチャで使用される %ZEN.Auxiliary.QueryInfoOpens in a new tab オブジェクトのプロパティについて説明しています。
tablePane と同様に、dataCombo、dataListBox、および repeatingGroup コンポーネントも、コールバックを使用して %ResultSetOpens in a new tab からコンポーネントを生成できます。QueryInfo オブジェクトのプロパティの中には、tablePane クエリにのみ適用されるものがあります。dataCombo、dataListBox、および repeatingGroup は、列、フィルタ、並べ替えなどのテーブル専用プロパティをすべて無視します。
tablePane および dataCombo のみが queryText プロパティをサポートします。
プロパティ | 説明 |
---|---|
columnExpression | <tablePane> の各 <column> にある colExpression の値。columnExpression では、これらの値は、添え字として <column> colName が付いた多次元配列として編成されます。 |
columns | <tablePane> の各 <column> にある colName の値。columns では、これらの値は、添え字として列番号 (先頭は 1) が付いた多次元配列として編成されます。 |
filterOps | <tablePane> の各 <column> にある filterOp の値。filterOps では、これらの値は、添え字として <column> colName が付いた多次元配列として編成されます。 |
filters | <tablePane> の各 <column> にある filterValue の値。filters では、これらの値は、添え字として <column> colName が付いた多次元配列として編成されます。 |
filterTypes | <tablePane> の各 <column> にある filterType の値。filterTypes では、これらの値は、添え字として <column> colName が付いた多次元配列として編成されます。 |
groupByClause | <tablePane> の groupByClause の値 (指定されている場合)。 |
orderByClause | <tablePane> の orderByClause の値 (指定されている場合)。 |
parms | 添え字としてパラメータ番号 (先頭は 1) が付いた多次元配列。この配列には、<tablePane> の <parameter> 要素で指定された入力値が記述されます。 |
queryExecuted | 新たに作成された %ResultSetOpens in a new tab が既に実行されていて、OnExecuteResultSet で指定したメソッドを呼び出す必要がないことを示すには、OnCreateResultSet で特定されるメソッドで、このプロパティを True に設定します。既定値は False です。 |
queryText | OnCreateResultSet で指定したメソッドでは、この値を実際のクエリ・テキストに設定できます。これにより、showQuery の値が True の場合に、このテキストが表示されます。 |
rowCount |
この値をコールバックで設定すると、コールバックが返るときに rowCount プロパティにはクエリが返す行数が設定されます。クエリの実行後の rowCount の値は、rows とは異なっている可能性があります。 rowCount の値は、"" または "100+" になる可能性があるので、数値ではなく文字列です。行数が 100 行を超える場合、このプロパティの値は "100+" となります。JavaScript で rowCount をテストする場合、これを数値に変換するには、次のように 10 進数を指定して parseInt を使用します。 rowCount = parseInt(rowCount,10); |
rows | 要求された行数。テーブルの場合、これは maxRows の値です。 |
sortColumn | ユーザが選択した現在のソート列の colName。 |
sortOrder | "asc" や "desc" など、現在、テーブルに対して設定されているソート順 (通常はユーザのクリック操作で決まります)。 |
tableName | <tablePane> の tableName の値。 |
whereClause | <tablePane> の whereClause の値 (指定されている場合)。 |
プログラムによるデータ・ソースの変更
<tablePane> のデータ・ソースは、実行時にさまざまな方法で変更できます。この場合は、データ・ソースはサーバ上にあるため、クライアント側のユーザ・アクションに基づいてテーブルのデータ・ソースを変更するには、このトピックで示すようにサーバ側に戻って操作を実行する必要があります。
次の例では、queryClass と queryName を使用してデータ・ソースが定義されていたため、サーバ側でこれらを新しい値に変更する必要があります。この例では、手順 2 で JavaScript メソッドを使用して、手順 3 で ZenMethod を使用しています。データ・ソースの変更時にクライアント側で他のアクションを実行する必要がある場合は、手順 2 のように JavaScript メソッドを間に挟んで使用すると便利です。または、手順 1 の onclick によって ZenMethod を直接呼び出して、手順 2 を省略することもできます。
-
Zen ページ上に存在するあるコンポーネントは、onclick (または他の何らかのユーザ・アクション) に対する応答として、クライアント側の JavaScript メソッドを呼び出します。次に例を示します。
<button caption="Display Form" onclick="zenPage.setUpContextForm()" />
-
このクライアント側の JavaScript メソッドは、<tablePane> のデータ・ソース・プロパティを操作するサーバ側の ZenMethod を呼び出します。次に例を示します。
ClientMethod setUpContextForm() [ Language = javascript ] { this.SetQueryClassAndName("LTD.DomainModel.ContextList","GetAll") ctrl = this.getComponentById('ctrlList') ctrl.setModelClass('LTD.DomainModel.ContextList',this.getCurrentListId()) zenSetProp('ContextId', 'hidden', 0) zenSetProp('ContextType', 'hidden',0) }
-
このサーバ側の ZenMethod は、<tablePane> コンポーネントを取得して、そのデータ・ソース・プロパティを設定します。次に例を示します。
Method SetQueryClassAndName(queryClass As %String, queryName as %String) As %Status [ ZenMethod ] { Set obj=%page.%GetComponentById("listTable") Set obj.queryClass = queryClass Set obj.queryName = queryName Quit $$$OK }
クエリ・パラメータ
Zen のテーブルのデータを生成する SQL クエリを扱うとき、クエリでは ? 文字で定義したクエリ入力パラメータの値を指定することが必要になる場合があります。このためには、<tablePane> 要素内で <parameter> 要素を使用します。<radioSet>、<select>、<dataListBox>、<dataCombo>、<repeatingGroup>、および <multiSelectSet> も、クエリをサポートするために <parameter> 要素を含むことができます。
属性 | 説明 |
---|---|
value |
次のパラメータ値を指定します。 <parameter value="Here is my value!"/> パラメータに使用する value には、リテラル文字列のほか、Zen #()# 実行時式も指定できます。 |
クエリを直接指定する場合は、sql 属性の場合のように、各 <parameter> 要素はクエリ構文内で 1 つの ? の代わりとなります。これは左から右の順序で、これらの値が同じ場合でも同様です。次に例を示します。
<tablePane id="table"
sql="SELECT ID,Name FROM MyApp.Employees
WHERE Name %STARTSWITH ? AND
((Salary < ?) OR (TotalCompensation < ?))
ORDER BY Name"
>
<parameter value="Z"/>
<parameter value="100000"/>
<parameter value="100000"/>
</tablePane>
この章の “データ・ソース” セクションでは、以下のクラス・クエリの例を含めて、<parameter> 要素の使用法の例を他にいくつか紹介しています。ここでは、各 <parameter> 要素はクラス・クエリ内の 1 つの引数の代わりとなります。
<tablePane id="table"
queryClass="MyApp.Employee"
queryName="ListEmployees">
<parameter value="Sales"/>
<parameter value="NEW YORK"/>
</tablePane>
%ZEN.Component.tablePaneOpens in a new tab をプログラムにより操作している場合に、setProperty を実装しない <radioSet>、<select>、または <multiSelectSet> クラスのいずれかを使用するときは、先にパラメータに対する id を設定する必要があります。
<parameter value="Sales" id="param1"/>
次の例では、最初のパラメータの値を Finance に変更し、このクエリをサーバで再実行した後、tablePane の内容を更新して新しい結果を表示します。
ClientMethod changeParams() [ Language = javascript ]
{
// find the tablePane component
var table = zenPage.getComponentById('table');
var param1 = zenPage.getComponentById("p1");
param1.value='Finance';
table.executeQuery();
}
テーブル列
この章の “データ・ソース” のセクションでは、任意の SQL クエリに基づいて <tablePane> で HTML テーブルを描画できることを説明しています。テーブルは、各行をクエリ結果セットにテーブル行として表示します。<tablePane> には、1 つ以上の <column> 要素も含まれていることがあります。<column> 要素では、クエリの結果セットに含まれる列のうち、表示する列を選択し、各列のレイアウト、スタイル、および動作も指定します。
<tablePane> の showRowSelector 属性は既定では True です。showRowSelector が True の場合は、テーブルの左端に追加の列が表示されます。この列は、テーブルが初めて表示されたときは空です。この列の役割は、ユーザが行を選択する際に、どの行が選択されているのかを示すことです。<tablePane> でこの列を非表示にするには、showRowSelector を False に設定します。
“SQL クエリの生成” のセクションでは、次のような、<column> 要素でテーブルを生成する方法の例を紹介しています。
<tablePane id="table"
tableName="MyApp.Employee">
<column colName="ID" />
<column colName="Name"/>
<column colName="Title" style="color: blue;"/>
</tablePane>
<column> 要素は、%ZEN.Auxiliary.columnOpens in a new tab クラスの XML プロジェクションであり、以下のテーブルの説明にある汎用属性をサポートします。
属性 | 説明 |
---|---|
cellTitle |
列にある任意のセルについてのツールのヒントを表すテキスト。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
colExpression | SQL クエリでテーブルを自動的に作成する場合に、この列の値を取得するために使用する SQL 式です。例 : colExpression="Customer->Name"。
エイリアスはサポートしません。colExpression を使用する場合、colName も指定する必要があります。 |
colName |
この列が関連付けられている SQL データ列の名前。詳細は、"colName" を参照してください。 |
disableSort |
True の場合は、ユーザが列ヘッダをクリックしたときにこの列を並べ替えません。False の場合は、並べ替えが有効になります。格納元の <tablePane> の useSnapshot 属性が True に設定されている場合は、既定では各列の並べ替えは有効になっています。 |
header |
列のヘッダを表すテキスト。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 header の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
hidden |
True を指定すると、この列は表示されません。既定値は False です。 hidden で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 hidden の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
OnDrawCell |
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。詳細は、"OnDrawCell" を参照してください。 |
seed | OnDrawCell コールバックに任意の値を渡せるようにします。 |
style |
この列にあるセル (HTML の <td> 要素) に適用する CSS スタイル値。例 : "color:red;" style の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
title |
ユーザが列のヘッダにマウスを重ねたときに表示されるツールのヒントを表すテキスト。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.booleanOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
width |
通常、Zen のテーブルに対する HTML の style 値は "fixed" です。つまり、生成された HTML ページでは各列が固有の width 値を持ちます。Zen では、この値は次のように決まります。
width の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
<column> も、Zen のテーブル列の動的なフィルタおよびリンクをサポートする属性を提供しています。こういった特殊な目的を持つ <column> 属性については後述します。
-
“列のフィルタ”
-
“列のリンク”
ユーザの選択に応じて列のレイアウトを動的に対応させる場合、<tablePane> でテーブルのすべての列に対してこれに対処する属性を指定します。詳細は、以下のセクションを参照してください。
-
“テーブルの並べ替え”
-
“行と列の選択”
プログラムで %ZEN.Component.tablePaneOpens in a new tab を扱うときは、%ZEN.Auxiliary.columnOpens in a new tab オブジェクトのリスト・コレクションである、tablePane の columns プロパティのメンバとして <column> 要素を扱います。<tablePane> の各 <column> は、tablePane 内の columns コレクションのメンバになり、位置の順序を表す 1、2、3 といった番号が付けられます。
colName
colName 属性は、この列が関連付けられている SQL データ列の名前を指定します。colName の値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。
<tablePane> の中で colName の値が重複している場合、重複の 2 番目の列には “(duplicate) colName” と表示されます。これは、この 2 番目の列の名前を変更しないと、<tablePane> が予期しない動作をする可能性があることを示しています。
列に colName を指定していない場合、データ値のない列が表示されます。通常、このテクニックは、行にリンク・アクションを表示するために使用されます。
OnDrawCell
Zen ページ・クラスのサーバ側コールバック・メソッドの名前を提供する OnDrawCell 属性。このメソッドは、&html<> 構文または WRITE コマンドを使用して、列内のセルに HTML コンテンツを挿入します。Zen は、列を描画するたびに、このメソッドを呼び出して、自動的に以下のパラメータを渡します。
-
<tablePane> オブジェクトへのポインタ。
-
この <column> が関連付けられている SQL データ列の名前を示す文字列。
-
<column> 内の seed 属性値。
このコールバックは、データ型が %StatusOpens in a new tab である値を返す必要があります。以下に、有効なメソッド・シグニチャを示します。
Method DrawYesNo(pTable As %ZEN.Component.tablePane,
pName As %String,
pSeed As %String) As %Status
{ }
コールバックとして上のメソッドを使用するには、<column> 文で OnDrawCell="DrawYesNo" と設定します。
<column colName="WorkDone" header="Complete?"
OnDrawCell="DrawYesNo" />
次の OnDrawCell コールバック・メソッドは、ブーリアン値 (1 または 0) を解釈して、<tablePane> 列に Yes または No という文字列を表示します。
Method DrawYesNo(pTable As %ZEN.Component.tablePane,
pName As %String,
pSeed As %String) As %Status
{
If %query(pName)
{
Write $$$Text("Yes")
}
Else
{
Write $$$Text("No")
}
Quit $$$OK
}
OnDrawCell コールバック・メソッド内にいる最中に SQL 列からデータ値を取得するには、上記のコード例のように %query 関数を使用します。%query 関数は、SQL 列の名前を識別する文字列を表す 1 つの引数を受け取ります。OnDrawCell メソッドのシグニチャは、pName という入力パラメータ内にこの値を自動的に提供します。このため、メソッド内の %query(pName) という式は、この <tablePane> の <column> に対応する SQL 列に格納された値に解決されます。
この例では、%query(pName) という式が 0 でないかどうかを判定します。0 でない場合は、<tablePane> の列に Yes という語が配置され、0 の場合は、<tablePane> の列に No という語が配置されます。
%query 関数を OnDrawCell コールバック・メソッドで使用することは、%query 特殊変数を Zen 実行時式で使用することと同じではありません。ドット構文と組み合わせた %query 特殊変数の使用に関する詳細と例については、“Zen アプリケーションの開発” の “Zen の特殊変数” セクションと “Zen 実行時式” セクションを参照してください。
テーブルのスタイル
テーブルの全般的なスタイルを制御するために、<tablePane> には次の属性が用意されています。
属性 | 説明 |
---|---|
caption |
このテーブルに表示するキャプションを表すテキスト。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.booleanOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
extraColumnWidth | 複数の行が選択されたときや tablePane に行番号を表示するときなどに追加する列に適用する HTML 幅。追加の列の既定の幅は 30 です。 |
fixedHeaders |
True を指定すると、テーブルの本文がスクロールされてもテーブルのヘッダの位置は固定されたままになります。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
bodyHeight | fixedHeaders が True の場合、bodyHeight は、HTML 長さの値でテーブルの本文の高さを指定します。bodyHeight の既定値は "20.0em" です。 |
nowrap |
True の場合、テーブルのセルで行を折り返すことはできません。False の場合は可能です。既定値は True です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showRowNumbers |
True の場合、tablePane の左端に行番号の列が表示されます。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showValueInTooltip |
True の場合、テーブルのセルについて表示されるツールのヒント (HTML の title 属性) には、そのセルの現在値が表示されます。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
showZebra |
True の場合、ゼブラ・ストライプ (暗い行と明るい行を交互に表示) を使用して tablePane が表示されます。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
行またはセルに対する条件付きスタイル
<tablePane> には、1 つ以上の <condition> 要素を記述できます。各 <condition> は、指定された行の値に基づく単純な式で、行のスタイルや、その行にある個々のセルのスタイルを制御します。次に例を示します。
<tablePane id="table"
sql="SELECT Name,Home_State FROM MyApp.Employee">
<condition colName="Name"
predicate="STARTSWITH"
value="A"
rowStyle="background: plum;"/>
</tablePane>
上記の例では、Name 列の行のうち、“A” で始まる値を持つ行の背景色はすべて濃い紫色 (plum) で表示されます。
通常、条件付きスタイル機能は、特定の値 (範囲外やエラーの場合など) を含む行やセルを強調表示するために使用します。条件を追加するとテーブルの表示に必要な処理量が増加するので、条件は可能な限り少なくします。
<condition> 要素では、次の属性がサポートされています。
属性 | 説明 |
---|---|
cellStyle |
目的の列の中で、この条件が True となる行のセルに適用する CSS スタイル。 以下はその例です。 "color: red;" |
colName | 必須項目。<condition> の適用対象となるデータ値を持つ列の名前。colName には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
predicate |
条件を評価するための論理演算子。predicate に指定できる比較演算子は、""、"GT"、"EQ"、"LT"、"NEQ"、"GTEQ"、"LTEQ"、"EXTEQ"、"STARTSWITH"、または "CONTAINS" のいずれかです。predicate の既定値は "EQ" です。各演算子の詳細は、以下の “<condition> の predicate に指定できる値” のテーブルを参照してください。 |
rowStyle |
この条件が True となる行に適用する CSS スタイル。以下はその例です。 "font-weight: bold;" |
targetCol |
cellStyle を適用する列の名前。指定しない場合は、colName が使用されます。 "列のリンク" セクションで説明するように、目的の列にリンクを表示する場合、targetCol は <column> の linkCaption 属性と一致する必要があります。 targetCol には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
value |
colName で指定した列の値と比較するリテラル値。"{Title}" のように {} で囲むと、value は別の列の名前として扱われ、その列にある値が使用されます。 value には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
テーブルを表示すると、<tablePane> 内の <condition> 要素はすべて、このテーブル内の行それぞれについて個別に評価されます。<condition> が True となる場合、行にはこの条件の rowStyle が適用され、セルには cellStyle が適用されます。
<condition> の predicate 属性には次の値を指定できます。
述語 | 説明 |
---|---|
CONTAINS | colName で指定した列の値に、value で指定した値が使用されている場合は True。 |
EQ | colName で指定した列の値と value で指定した値が等しい場合は True。 |
EXTEQ | colName で指定した列にあるファイル名が、value で指定したファイル拡張子を持っている場合は True。 |
GT | colName で指定した列の値が、value で指定した値よりも大きい場合は True。 |
GTEQ | colName で指定した列の値が、value で指定した値以上である場合は True。 |
LT | colName で指定した列の値が、value で指定した値未満の場合は True。 |
LTEQ | colName で指定した列の値が、value で指定した値以下である場合は True。 |
NEQ | colName で指定した列の値と value で指定した値が等しくない場合は True。 |
STARTSWITH | colName で指定した列の値が、value で指定した値で始まる場合は True。 |
プログラムで %ZEN.Component.tablePaneOpens in a new tab を扱うときは、%ZEN.Auxiliary.conditionOpens in a new tab オブジェクトのリスト・コレクションである、tablePane の conditions プロパティのメンバとして <condition> 要素を扱います。<tablePane> の各 <condition> は、tablePane 内の conditions コレクションのメンバになり、位置の順序を表す 1、2、3 といった番号が付けられます。
スナップショット・モード
<tablePane> はスナップショット・モードで動作できます。このモードでは、Zen はテーブルのクエリを一度実行し、その結果をサーバ上の一時保管場所にコピーします。その後、画面を更新すると、クエリが再度送信されるのではなく、この一時保管場所にあるデータが表示されます。一時的なスナップショット・データの作成とライフサイクルは、Zen により自動的に管理されます。スナップショット・モードは、複数ページから成るテーブルを操作する場合に特に便利です。スナップショット・モードの使用時には、refreshRequired は何の効果もなくなることに注意してください。
一時的なスナップショット・データ構造が保持できるデータ値のサイズには制限があります。このため、列内のどの単一のデータ値にも n 文字より多く格納することはできません。つまり、その列のどのデータ値の MAXLEN も n より大きい値に設定できないということです。これより大きい値に設定されている場合は、ユーザがその列を並べ替えようとすると <SUBSCRIPT> エラーが発生します。n の値は、使用されている文字セットによって異なります。n は、ObjectScript 内のグローバル添え字文字列の最大長です。この長さは文字セットによって異なり、英語の場合は上限値は 508 であり、日本語の場合は 200 未満です。詳細は、"Caché グローバルの使用法" の “添え字の最大長の決定” のセクションを参照してください。
<tablePane> 要素では、スナップショット・モードで次の属性がサポートされています。
属性 | 説明 |
---|---|
useSnapshot |
True の場合、この <tablePane> はスナップショット・モードです。つまり、フェッチされたデータはサーバ側の一時的な保管場所にコピーされます。ページングや並べ替えの操作では、このスナップショット・データが使用されます。クエリが再実行されることはありません。 ユーザが列ヘッダをクリックすることでテーブル列を並べ替えできるようにするには、useSnapshot を True に設定する必要があります。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
pageSize | スナップショット・テーブルでは、この属性は、データを複数ページに表示すること、およびそのページ・サイズを指定します。既定値の 0 は、すべてのデータを最初のページに表示することを示します。ここでは、テーブルがスナップショット・モードのときに 0 以外の値を設定することのみ可能です。<tablePane> クエリでフェッチする行数を表す maxRows と比較してください。 |
この章で説明したクエリ機能はいずれも、スナップショップ・モードまたはダイレクト (非スナップショット) モードで使用できます。次の例では、スナップショット・モードで使用する SQL クエリを指定しています。
<tablePane id="table"
sql="SELECT Name,Home_State FROM MyApp.Employee"
useSnapshot="true"
pageSize="25"
/>
次に示す %ZEN.Component.tablePaneOpens in a new tab のプロパティは、<tablePane> 定義で XML 属性として使用することはできませんが、ページの作成後は、スナップショット・テーブルの操作に活用できます。
属性 | 説明 |
---|---|
clearSnapshot | クライアント側で True に設定することで強制的にテーブル・クエリを再実行できるようになる実行時フラグ。False に設定すると、保存されているスナップショットが使用されます。既定値は False です。 |
currPage | 複数ページにわたるデータを持つスナップショット・テーブルで、現在表示されているデータ・ページのインデックス番号 (先頭は 1) です。 |
また、元の値が XData Contents の <tablePane> で設定されている useSnapshot および pageSize の値をプログラムで設定することもできます。
サーバからのデータのフェッチ
%ZEN.Component.tablePaneOpens in a new tab クラスは、スナップショット・モードでのみ、テーブルに getRowData メソッドを提供します。getRowData は、サーバ側のスナップショット・データから、指定された行 (先頭行は 0) のデータ値をフェッチします。このデータは、スナップショット・テーブルにある列の名前に対応するプロパティを持つ JavaScript オブジェクトにパッケージされます。データ型は適切に変換されます。スナップショットではないテーブルや範囲外の行番号を指定すると、getRowData からは NULL が返されます。
列のフィルタ
Zen のテーブルでは、“フィルタ” を作成し、任意の列ヘッダの上部に配置できます。フィルタは入力フィールドが付いた単純なボックスで、このフィールドには 1 つ以上の検索条件を入力できます。この変更を送信すると、新しい条件を使用して、<tablePane> に関連付けられたクエリが再実行されます。Zen によりテーブルは更新されますが、ページにあるそれ以外のものは変更されません。
フィルタを使用できるのは、自動生成された SQL 文を <tablePane> で使用している場合、または OnCreateResultSet コールバックを <tablePane> で使用していて、このコールバックでデータ・フィルタの実装に適した WHERE ロジックを生成している場合のみです。生成された SQL クエリをテーブルで使用している場合、ページ・クラスはユーザ入力を収集し、これを %ZEN.Component.tablePaneOpens in a new tab のプロパティである groupByClause、orderByClause、および whereClause に適した書式とした後、テーブルのクエリを再実行します。
フィルタを作成するには、フィルタを指定する <column> 要素で colName の値を指定する必要があります。
<column> 要素には、フィルタのために以下の属性が用意されています。
属性 | 説明 |
---|---|
filterEnum |
filterType が "enum" の場合、filterEnum は、フィルタで使用する列挙値をコンマ区切りリストの形式で定義します。以下はその例です。 "red,green,blue" この列挙値は、コンボ・ボックスに表示されます。filterEnum リストで指定した名前は、filterEnumDisplay が定義されていない限り、コンボ・ボックスに選択肢として表示されます。 |
filterEnumDisplay |
filterType を "enum" として、filterEnumDisplay にコンマ区切りリストの形式で値を指定すると、コンボ・ボックスには、対応する filterEnum 値の代わりにこれらリストの値が表示されます。 filterEnumDisplay 属性では、ZENLOCALIZE データ型パラメータが 1 (True) に設定されています。これにより、そのテキストを他の言語にローカライズしやすくなり、クライアント側コードやサーバ側コードからこのプロパティに値を割り当てるときには $$$Text マクロを使用できます。 ローカライズ済みの filterEnumDisplay 文字列が元の言語でコンマ区切りのリストとなっていた場合、コンマ区切りのリストのままにする必要があります。 |
filterLabel | このフィルタ・コントロールに表示されるラベルです。マルチパートのフィルタ・コントロール (filterType が "range" の場合など) がある場合、filterLabel には、コンマ区切りリストの形式で複数のラベルが指定されているものと見なされます。 |
filterOp | この列にフィルタが設定されている場合、filterOp は、フィルタと共に使用される SQL 演算子の名前です。サポートされている値は、""、"%STARTSWITH"、"="、">="、"<="、"<>"、">"、"<"、"["、"BETWEEN"、"IN"、"%CONTAINS"、および "UP[" です。 |
filterQuery | filterType が "query" の場合、filterQuery は、ドロップダウン・リストの値セットを指定する SQL 文を定義します。クエリに複数の列がある場合、先頭列は論理値 (検索で使用する値) として使用され、2 列目は表示値として使用されます。 |
filterTitle |
ユーザが列のフィルタ・コントロールにマウス・カーソルを置いたときに表示されるツールのヒントを表すテキスト。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
filterType | この列に検索フィルタ・コントロールを表示することを指定し、表示するフィルタ・コントロールのタイプを示します。filterType に指定可能な値は以下のとおりです。
|
filterValue |
この列に対する列フィルタの現在の値。普通、filterValue には、ユーザがフィルタ・コントロールに値を入力した後で値が取得されますが、初期値を定義するように設定しておくこともできます。 filterValue の意味は filterOp の設定によって異なります。filterOp の設定による違いは次のとおりです。
|
maxDate | filterType が “date” または “datetime” の場合に、カレンダー・セレクタで使用できる最大の日付を指定します。 |
minDate | filterType が “date” または “datetime” の場合に、カレンダー・セレクタで使用できる最小の日付を指定します。 |
OnDrawFilter |
Zen ページ・クラスのサーバ側コールバック・メソッドの名前。このメソッドは、&html<> 構文または WRITE コマンドを使用して、この列のフィルタに HTML コンテンツを挿入します。このテーブルの後に追加情報が示されます。 |
Zen は、その時点での filterType の値が "custom" の場合のみ、その列の描画時に OnDrawFilter メソッドを呼び出します。Zen は、自動的にこのメソッドに以下のパラメータを渡します。
-
%ZEN.Component.tablePaneOpens in a new tab — <tablePane> オブジェクト
-
%StringOpens in a new tab — <column> 内の colName 値
-
%ZEN.Auxiliary.columnOpens in a new tab — <column> オブジェクト
このコールバックは、データ型が %StatusOpens in a new tab である値を返す必要があります。以下に、有効なメソッド・シグニチャを示します。
Method DrawFil(pTable As %ZEN.Component.tablePane,
pName As %String,
pColinfo As %ZEN.Auxiliary.column)
As %Status
{ }
コールバックとして上のメソッドを使用するには、<column> で OnDrawFilter="DrawFil" と設定します。
以下の例では、<tablePane> により、従業員の Name と Department を表示する SQL 文が生成されます。
<tablePane id="table"
useSnapshot="true"
tableName="MyApp.Employee">
<column colName="ID" hidden="true"/>
<column colName="Name" filterType="text" />
<column colName="Department"
filterType="enum"
filterEnum="Sales,Accounting,Marketing"
filterOp="=" />
</tablePane>
この例は、<column> の filterType 属性を使用して、Name 列に列フィルタが表示されるように指定しています (“text” は、ユーザがテキストを入力できるボックスがこのフィルタで表示されることを表しています)。ユーザがこのボックスに値、例えば “A” を入力し、Enter キーを押すと、テーブルが更新され、“A” で始まる値が Name 列にある行のみが表示されます。<column> で filterOp の値を指定していない場合の既定の照合操作は %STARTSWITH です。
Department 列には、例ではより高度なフィルタ、つまり指定可能な値を 3 つ持つコンボ・ボックスが表示されます。このためには、<column> の filterType に “enum” を、filterEnum に、指定可能な値をコンマ区切りリストの形式で設定します。また、filterOp の値を "=" に設定することにより、完全な一致が要求されることを指定します。
<tablePane> には、既定でアクティブになっていて有効なフィルタを指定します。フィルタを有効にするために、<tablePane> 属性を指定する必要はありません。既定の設定をオーバーライドする必要がある場合のために、<tablePane> には以下の属性が用意されています。これらの属性は、個々の列ではなく、テーブル全体に対するフィルタを制御します。
属性 | 説明 |
---|---|
autoExecute |
True の場合、フィルタの値を変更するたびにテーブル・クエリが実行されます。autoExecute の既定値は、"True" です。False の場合、<tablePane> の executeQuery メソッドを呼び出すことで、ページで明示的にクエリを実行する必要があります。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
filtersDisabled |
True の場合、列フィルタがあれば、それが無効になります。True の場合、列フィルタは表示されたままですが、アクティブではありません。既定値は False です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
headerLayout |
列フィルタを使用する際のテーブル・ヘッダの表示方法を制御します。可能な値は以下のとおりです。
|
showFilters |
True の場合、列フィルタがあれば、それが列ヘッダの上に表示されます。False の場合、フィルタは表示されません。既定値は True です。 この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。“Zen 属性のデータ型” を参照してください。 |
列のリンク
Zen のテーブル内の列にはリンクを表示できます。このリンクを使用すると、例えば、別のページに移動して、現在の行に表示されているオブジェクトの詳細を編集するなどの処理が可能です。このリンクは、テーブル上でデータ値を含む列 (この場合、データ値はリンクとして表示されます) に表示するか、そのリンクを含む追加列として表示できます。
<column> 要素には、リンクのために以下の属性が用意されています。
属性 | 説明 |
---|---|
link |
この属性を指定した列はリンクとして表示され、その URI として link プロパティの値が使用されます。そのリンクでクライアント側の JavaScript メソッドを呼び出すには、以下のように URI の先頭に javascript: を使用します。 link="javascript:zenPage.myMethod();" この規約の詳細は、この表の後に示す例を参照してください。 または、link を # に設定して、onclick イベントを使用して、ユーザがこの列をクリックしたときのアクションを設定します。こうすることで、お使いの CSS スタイルシートで割り当てられた任意のリンク スタイルを使用して、linkCaption のテキストがフォーマットされます。 <column onclick="return zenPage.test('#(%query.Name)#');" linkCaption="Test" link="#"/> |
linkCaption |
この列にアクションが定義 (link または onclick) されている場合に、この列にデータ値が表示されない場合は、linkCaption に指定したテキストがリンクのキャプションとして表示されます。条件付きスタイル (セクション "行またはセルに対する条件付きスタイル" を参照) を使用している場合、linkCaption はスタイルを指定する <condition> 要素の targetCol 属性と一致する必要があります。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
linkConfirm |
この列で link を定義し、さらにこの linkConfirm を指定すると、この属性で指定したテキストがリンクの実行前に確認メッセージとして表示されます。この列に onclick アクションが定義されている場合は、linkConfirm は無視されます。 この属性に普通のテキストを入力できる場合でも、基本となるデータ型 %ZEN.Datatype.captionOpens in a new tab が与えられます。“Zen 属性のデータ型” を参照してください。 |
onclick |
この列のセルをユーザがクリックするたびに実行されるイベント・ハンドラ。“Zen コンポーネントのイベント・ハンドラ” を参照してください。 この列にデータが関連付けられていない場合は、linkConfirm プロパティを設定して、ユーザがクリックするテキストを表示する必要があります。onclick を使用するときには、このテーブルの link で説明するように、link を # に設定します。 |
以下は、<column> link 値を使用して別のページに移動する前に、この値をさらに処理するための JavaScript コードの使用例です。
<tablePane id="table"
sql="SELECT TOP 100 ID,Item,Price FROM MyApp.Inventory ORDER BY Price">
<column colName="ID" hidden="true"/>
<column colName="Item"
link="MyApp.ItemEdit.cls?ID=#(%query.ID)#"
linkCaption="View information on this item."
/>
<column link="javascript:zenPage.addToCart('#(%query.ID)#');"
linkCaption="Add to cart"
linkConfirm="Do you wish to add this item to your cart?"
/>
</tablePane>
この例は、以下を実行します。
-
この <tablePane> の sql 値は、価格順に並べられている MyApp.Inventory テーブル内の上位 100 項目に関する情報を、このテーブルに表示することを指定します。
-
<tablePane> では (リンクの一部として) “ID” 列の値が必要になりますが、この値を表示する必要はありません。したがって、<column> の hidden の値は True です。
-
<tablePane> の “Item” 列には、特定の項目に関する情報を表示するページへのリンクを記述する必要があります。したがって、<column> の link の値にこのリンクを定義します。<column> の linkCaption の値は、ユーザがこのリンクの上にマウス・カーソルを置いたときに表示されるツールのヒントを定義します。
-
<tablePane> は、“Add to cart” リンクを記述した追加列 (その中に値は表示されません) を定義します。ユーザがこのリンクをクリックすると、クライアント側 addToCart メソッドが呼び出されます。linkConfirm プロパティは、リンクを実行する前にユーザに対して表示する確認メッセージを指定します。
この <tablePane> の例で使用している 2 つの link 値は、Zen 式構文を使用して、リンク内に行固有のデータの値を取り込んでいます。"Zen アプリケーションの開発" の “Zen ページ” の章にある “Zen 実行時式” を参照してください。以下の式は、テーブルの現在行に含まれる ID 列を参照しています。
#(%query.ID)#
2 つの link の例のうち 2 番目のものが機能するためには、クライアント側の addToCart メソッドで、URI を構成し、新しいページを呼び出す必要があります。クエリによって返されるテキスト値に使用されている可能性のある特殊文字をエンコードする必要がある場合、以下の例のように、クライアント側のメソッドを使用することは重要です。
ClientMethod addToCart(identifier) [Language = javascript]
{
var page = "MyApp.AddToCart.cls?ID=" + encodeURIComponent(identifier);
this.gotoPage(page);
return;
}
ユーザ対話
Zen のテーブルには、ページの移動、列の並べ替え、テーブル内の行の選択など、基本的なユーザ対話をサポートするための組み込み機能が用意されています。
テーブルの並べ替え
<tablePane> は、ユーザがテーブル列を並べ替えできるようにするには、スナップショット・モードを使用する必要があります。ユーザが列ヘッダをクリックすることでテーブル列を並べ替えできるようにするには、<tablePane> の useSnapshot 属性を True に設定する必要があります。useSnapshot の既定値は False です。詳細および重要な制限事項については、“スナップショット・モード” セクションを参照してください。
useSnapshot が True の場合は、<column> の disableSort 属性を True に設定することで、任意の列の並べ替えを希望に応じて無効にできます。disableSort などの column の属性の詳細は、“テーブル列” セクションを参照してください。
スナップショットが有効になっている場合は、ユーザは列ヘッダをクリックするだけで、その列に基づいてテーブルを並べ替えることができます。1 度目のクリックでは昇順で、2 度目のクリックでは降順で並べ替えられ、3 度目のクリックでは並べ替えなしとなり、以降同様です。sortOrder の初期値は、次のテーブルで説明しているように <tablePane> をページに追加するときに設定できます。ただし、通常は sortOrder の値は、ユーザ・アクション (テーブルの列ヘッダのクリック) に基づいて取得されます。
プロパティ | 説明 |
---|---|
sortOrder |
ユーザが列ヘッダをクリックすると、その列にある値と sortOrder 値で指定された順序に基づいてテーブルが並べ替えられます。 ユーザがその列ヘッダをクリックするたびに、sortOrder の値は、"asc" (昇順で並べ替え) と "desc" (降順で並べ替え) の間で切り替わります。 sortOrder はクエリ自体には影響を与えません (クエリの ORDER BY 設定とは相互に関連がありません)。単に、クエリから返される結果セットが表示されるテーブルでの並び順を制御するにすぎません。 sortOrder 値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
日付データを含む列の場合、列ヘッダをクリックすると、日付の表示形式が現在のロケール設定によって指定された既定の形式または ODBC 形式のいずれかの場合のみ、日付が正しい年代順に並べ替えられます。その他の形式はアルファベット順で並べ替えられます。
日付形式の詳細は、"Caché ObjectScript リファレンス" の "$ZDATETIME" ("$ZDT") 関数の “パラメータ” セクションにある dformat の説明を参照してください。
行と列の選択
ユーザは、Zen のテーブルで行や列をクリックして選択することができます。Zen は現在の行を視覚的にわかるように示し、<tablePane> の onselectrow 属性から提供されるイベント・ハンドラをトリガして、イベントのアプリケーションに通知します。
%ZEN.Component.tablePaneOpens in a new tab は、行や列の選択に使用できる各種プロパティをサポートしています。これらのプロパティの多くは <tablePane> 属性として設定できますが、実行時にユーザのアクションに応じた値をとるだけのものもあります。
プロパティ | 説明 |
---|---|
currColumn | ユーザが最後に選択した列の colName。このプロパティの値は、ユーザ指定にできるほか、管理者が設定することもできます。currColumn 値には、リテラル文字列のほか、Zen #()# 実行時式を指定できます。 |
multiSelect | True の場合、ユーザはテーブルから複数の行を選択できます。選択した行を示すためのチェック・ボックスが表示された列が追加表示されます。既定値は False です。multiSelect と rowSelect は、互いの値にかかわらず、True または False に設定できます。 |
ondblclick |
このテーブルの行をユーザがダブルクリックしたときに生成されるイベントのイベント・ハンドラ。“Zen コンポーネントのイベント・ハンドラ” を参照してください。 |
onheaderClick | このテーブルにある列ヘッダをユーザがクリックしたときに実行されるクライアント側 JavaScript 式。この列の名前は、currColumn プロパティに格納されます。 |
onmultiselect | multiSelect が True の場合は、ユーザがこのテーブルで複数選択した行のセットを変更したときに実行されるクライアント側 JavaScript 式です。 |
onselectrow | rowSelect が True の場合は、ユーザがこのテーブルで新しい行を選択したときに実行されるクライアント側 JavaScript 式です。これは、showRowSelector が True の場合にのみ、実行されます。 |
rowSelect | True の場合、ユーザはこのテーブルにある行を一度に 1 行ずつ選択できます。既定値は True です。multiSelect と rowSelect は、互いの値にかかわらず、True または False に設定できます。 |
selectedIndex | 現在選択されている行のインデックス番号 (先頭番号は 0)。この値は、showRowSelector プロパティが True の場合にのみ意味を持ちます。スナップショット・テーブルの場合は、現在のページでの行番号です。 |
selectedRows |
読み取り専用。 <tablePane> の multiSelect が True に設定されており、valueColumn が定義されている場合は、その selectedRows の文字列は、テーブル内で現在選択されている行を示します。この文字列はこの目的のために、選択されている各行の valueColumn 値が列記されたコンマ区切りリストを提供します。この文字列内の連続しているコンマは、その位置の行は選択されていないことを示します。 selectedRows の文字列は次の例のようになります。この例では 14 行のうち 3 行が選択されています。 ",,,value,,,value,,,,,value,," <tablePane> の valueColumn は定義されていないが、multiSelect が True に設定されている場合は、selectedRows の文字列は、選択された行に関する情報は提供せずに、次のようになります。 ",,,,,,,,,,,,," |
showRowSelector | True の場合は、テーブルの左端に追加の列が表示されます。この列は、テーブルが初めて表示されたときは空です。この列の役割は、ユーザが行を選択する際に、どの行が選択されているのかを示すことです。showRowSelector の既定値は True です。テーブルでこの追加の列を非表示にするには、showRowSelector を False に設定します。 |
value |
これは、現在どの行が選択されているかを判断するために使用する論理値です。value は、valueColumn と関連して機能します。空の値 ("") を指定することもできます。 この値には直接アクセスせず、getProperty('value') を使用してください。 |
valueColumn |
<tablePane> では、value に論理値を定義できます。テーブルを更新するたびに、各行について、その行の valueColumn に表示される実際の値を基準にして、この value の論理値がテストされます。valueColumn に value を持つ行がすべて選択されます。これは、次のことを暗示しています。
|
テーブルの更新
テーブルを更新すると、そのテーブルのみ更新されます。テーブルを更新するために、Zen ページ全体を更新する必要はありません。
通常、Zen では、必要に応じて、テーブルに表示されている内容が自動的に更新されます。テーブルをプログラムで操作する場合は、明示的にテーブルのコンテンツを更新することもできます。その方法は以下のとおりです。
-
%ZEN.Component.tablePaneOpens in a new tab の %ResetQuery メソッドを、サーバ側メソッドから呼び出します。これにより、tablePane のクエリが強制的に再実行されます。
-
%ZEN.Component.tablePaneOpens in a new tab の executeQuery メソッドを呼び出します。これにより、データ・クエリが再実行され、tablePane プロパティの現在の値が反映されるように、テーブルに表示されている内容が更新されます。
スナップショット・モードの使用時には、%ResetQuery の呼び出しは何の効果もなくなることに注意してください。
テーブルの修正
XData Contents で <tablePane> の属性値を設定すると、tablePane オブジェクトの対応するプロパティに、その値が自動的に取得されます。目的によっては、このプログラミングのみで十分です。それでも、%ZEN.Component.tablePaneOpens in a new tab を使用すると、クライアント側またはサーバ側でプログラムによるさまざまな対話処理が可能になります。
データ値
テーブルに表示されるデータ値を修正するには、以下のような方法があります。
-
ページ・クラスの %OnAfterCreatePage コールバックで tablePane プロパティを設定して、XData Contents に設定した値を表示の前に修正します。
-
lastUpdate や rowCount など、%ZEN.Component.tablePaneOpens in a new tab の読み取り専用プロパティを調べ、テーブルの現在の状態を判断します。rowCount の値は、"" または "100+" になる可能性があるので、数値ではなく文字列です。行数が 100 行を超える場合、このプロパティの値は "100+" となります。
-
tablePane の所定のプロパティの値をリセットして、テーブルを更新します。
ヘッダと本文の配置
fixedHeaders を True に設定して <tablePane> ヘッダを Internet Explorer で表示すると、ヘッダと本文とで列の表示位置が揃わないことがあります。このため、%ZEN.Component.tablePaneOpens in a new tab クラスには、表示したテーブルの整列の問題を確認する resizeHeaders と呼ばれるクライアント側 JavaScript メソッドがあります。このメソッドでは、必要に応じ、テーブルの本文内の垂直スクロール・バーに占有された領域に合わせてパディングを追加し、ヘッダの書式を再設定します。
resizeHeaders では、表示されたページにあるスクロール・バーの実際のサイズに基づいてパディングのサイズを計算し、Internet Explorer 6 と 7 との相違や、Windows デスクトップ・テーマによってスクロール・バーの幅に発生するわずかな差異をすべて自動的に調整します。fixedHeaders を True に設定した <tablePane> コンポーネントを Internet Explorer で表示したとき、実際に問題が生じていない場合は、resizeHeaders を使用する必要はありません。この問題が生じる場合は、以下の手順で修正します。
-
<tablePane> を表示する Zen ページ・クラスに、クライアント側 JavaScript メソッド onresizeHandler を実装します。onresizeHandler はページ・クラスに実装する必要があります。その理由は、サイズ変更イベントは現在の zenPage オブジェクトのみでサポートされ、ページ上のどのコンポーネントにも反映されないからです。同様なクライアント側コールバック・メソッドのリストは、"Zen アプリケーションの開発" の “Zen ページ” の章にある “クライアント側ページのコールバック・メソッド” を参照してください。
-
onresizeHandler の実装が、tablePane オブジェクトの resizeHeaders メソッドを明示的に呼び出すことを確認します。