Class CGIKit::DisplayGroup
In: docs/rdoc_ja.rb
Parent: Object

CGIKit::DisplayGroupはデータの表示を管理するクラスです。 次の機能があります。

  • ページ表示
  • データの取得、作成、削除
  • データ選択
  • フィルタリング
  • ソート

基本的な使い方

  1. インスタンスを生成する
  2. データを設定する
  3. 更新する
 group = CGIKit::DisplayGroup.new
 group.objects = data
 ...
 group.update

ページ表示

データを指定した件数ずつ表示します。

ページ情報

displays:表示中のオブジェクトの配列。
per_page:一度に表示するオブジェクトの数。
page_index:現在表示しているページ番号。
page_count:表示できるページ数。
multiple_pagees?:2ページ以上あれば真を返す。
first_display_index:最初に表示されているオブジェクトの位置。
last_display_index:最後に表示されているオブジェクトの位置。

前のページ、次のページを表示する

display_next, display_pre を実行します。

データの取得、作成、削除

新規データを設定する

data_class, default_values

データ選択

表示されているデータのうち、どのデータが選択されているかを管理します。

フィルタリング

表示するオブジェクトを条件で絞り込みます。 update()またはqualify()の実行時、保持するオブジェクト(object属性)に条件が適用され、表示するオブジェクトに反映されます。

条件に漏れたオブジェクトは管理するオブジェクトの配列から取り除かれ、update()してもフィルタリング前の状態には戻りません。 フィルタリング前の状態に戻すには、objects属性を設定し直すか、データソースからオブジェクトを再度フェッチします。

Procオブジェクトによるフィルタリング

フィルタリングはProcオブジェクトを使って行われます。 qualifier属性にProcオブジェクトを設定しておくと、update()を実行したときにフィルタリングが行われます。

例: フィルタリングに使うProcオブジェクトを設定する

 proc = proc {|obj| /Mark/ === obj.name}
 group.qualifier = proc
 group.update

Procオブジェクトの引数にはフィルタリングするオブジェクトが渡されます。 Proc#callの結果が偽であれば、引数のオブジェクトがDisplayGroupの保持するオブジェクトから取り除かれます。

クエリモード

query_modeに真を設定することでクエリモードになります。 クエリモードでは、キーと値の組み合わせを指定することでフィルタリングを行います。 フォームからクエリ(フィルタリング条件)を入力することができます。

クエリモードで設定した条件でフィルタリングするには、qualify()かqualify_data_source()を実行します。 実行後、クエリモードは終了します。

クエリには次のものがあります。 いずれもハッシュで、キーに属性(メソッド)名、値に条件を設定します。

query_max:最大値。
query_min:最小値。
query_match:比較する値。query_operatorと組み合わせて使う。
query_operator:比較に使うメソッド。

例えば、price属性値が 10 から 50 の間のオブジェクトをフィルタリングするには次のように設定します。

 group.query_mode = true
 group.query_min[:price] = 10
 group.query_max[:price] = 50
 group.qualify

ソート

ソート条件を設定し、update()を実行するとソートします。 表示中のオブジェクトだけでなく、すべてのオブジェクトの順序をソートします。

Procオブジェクトによるソート

フィルタリングと同じく、Procオブジェクトを使ってソートを行います。 引数を2つ受け取るProcオブジェクトをsorter属性に設定します。 Procオブジェクトの戻り値は 1, -1, 0 のいずれかを返す必要があります。

キーによるソート

ソートする属性(メソッド)名と比較に使うメソッドを指定してソートを行います。 update()の実行時、sorter属性がnilであればキーによってソートされます。

add_sort_key(key, method):ソートに使うキーとメソッドを追加する。
remove_sort_key(key):ソートに使うキーとメソッドを削除する。

例えばprice属性を昇順に並べるには、次のように設定します。

 group.add_sort_key(:price, :>)
 group.update

データソース

デフォルトではオブジェクトの配列を扱いますが、データソース(DataSource)を使うとデータベースなどからデータを取得して表示させることができます。 現在、MadeleineDataSourceのみ用意してあります。

Methods

Attributes

data_class  [RW]  create()で新しく生成されるオブジェクトのクラス。 デフォルト値は Hash です。

create()では引数なしのnew()でインスタンスを生成します。 data_classに指定するクラスのinitialize()を、引数を省略できるように調整してください。

data_source  [RW]  データソース(DataSourceオブジェクト)。
default_values  [RW]  create()で新しく生成されるオブジェクトの初期値のハッシュ。 キーに属性名、値に初期値を設定します。
 group.default_values = { :name => 'John Doe', :age => 35 }

 # data_class が Hash の場合
 group.create #=> { :name => 'John Doe', :age => 35 }

 # data_class がその他のクラスの場合
 group.data_class = Book
 group.create #=> #<Book:... @name="John Doe" @age=35>
first_display_index  [RW]  最初に表示されているオブジェクトの位置。
last_display_index  [RW]  最後に表示されているオブジェクトの位置。
objects  [RW]  管理しているオブジェクト。
page_index  [RW]  現在表示しているページ番号。
per_page  [RW]  一度に表示するオブジェクトの数。
qualifier  [RW]  update()の実行時、フィルタリングに使われるProcオブジェクト。 デフォルト値はnilです。
query_match  [RW]  フィルタリング時、オブジェクト同士を比較する値を指定するハッシュ。 キーに属性(メソッド)名、値に比較する値を設定します。

この属性はquery_operatorと組み合わせて使います。 同じキーに対し、query_matchに比較する値を、 query_operatorに比較するメソッドを指定します。 例えばname属性値が ‘A’ で始まるオブジェクトを絞り込む場合、次のように設定します。

 group.query_match[:name]    = /\AA/
 group.query_operator[:name] = :=~

qualify()を実行すると、各オブジェクトに対して次のような比較が行われます。

 object.name =~ /\AA/
query_max  [RW]  オブジェクトの最大値を指定するハッシュ。 キーに属性(メソッド)名、値に最大値を設定します。
query_min  [RW]  オブジェクトの最小値を指定するハッシュ。 キーに属性(メソッド)名、値に最小値を設定します。
query_mode  [RW]  クエリモードのときに真、そうでなければ偽を返します。
query_operator  [RW]  フィルタリング時、オブジェクト同士を比較するメソッドを指定するハッシュ。 キーに属性(メソッド)名、値に比較に使うメソッドを設定します。 この属性はquery_matchと組み合わせて使います。
selection  [RW]  表示されているオブジェクトのうち、選択されているオブジェクト。 selectionsの最初の要素です。
selection_indexes  [RW]  選択中のオブジェクトの位置の配列。
selections  [RW]  表示されているオブジェクトのうち、選択されているオブジェクトの配列。
sort_keys  [RW]  update()の実行時、ソートに使われるキーとメソッド(SortKeyオブジェクト)の配列。 ソートに使うキーとメソッドを追加するには add_sort_key() を、 削除するには remove_sort_key() を使います。
sorter  [RW]  update()の実行時、ソートに使われるProcオブジェクト。 sort_keysが指定されていなければこのオブジェクトが使われます。 デフォルト値はnilです。

Public Class methods

Public Instance methods

ソートに使うキーとメソッドを追加します。

すべてのクエリを空にします。

選択中のオブジェクトを解除します。

data_classで指定されたクラスのインスタンスを生成します。 インスタンスはdefault_valuesの値で初期化されます。

選択中のオブジェクトを削除します。

indexに対応するオブジェクトを削除します。

現在のページを表示します。

次のページを表示します。

前のページを表示します。

表示中のオブジェクトの配列を返します。

データソースからデータを取得します。

表示中のページが先頭のページであれば真を返します。

indexの位置にobjectを挿入します。 indexを省略すると、表示中のオブジェクトの配列の先頭の位置にobjectが挿入されます。 objectを省略すると、create()で生成したオブジェクトを挿入します。

表示中のページが最後のページであれば真を返します。

表示できるページが2ページ以上あれば真を返します。

表示するオブジェクトの配列を返します。

表示できる最大ページ数を返します。

次のデータからフィルタリングに使うProcオブジェクトを生成します。

  • query_max
  • query_min
  • query_match
  • query_operator

qualifier_from_query_valuesの値をqualifier属性に代入し、 保持するオブジェクトをフィルタリングします。 クエリモードは解除されます。

qualifier_from_query_valuesの値をqualifier属性に代入後、 データソースからデータを取得し、フィルタリングします。 クエリモードは解除されます。

keyに対応するソートに使われるメソッドを削除します。

選択中のオブジェクトの、次のオブジェクトを選択します。

選択中のオブジェクトの、前のオブジェクトを選択します。

表示するオブジェクトを更新します。 保持するオブジェクトをフィルタリング、 ソートしたオブジェクトの配列を表示するオブジェクトとして設定します。

[Validate]