Rico LiveGrid の作成

Rico LiveGrid は 2 次元の JavaScript 配列でデータをバッファリングして、スクロールするテーブルにデータを表示します。 ユーザがグリッドを垂直にスクロールする事によって、データは配列からグリッド上へ動的にコピーされます。 バッファは次の項目からロードされる事が出来ます。

  1. javascript 配列
  2. HTML テーブル
  3. XML ファイル
  4. SQL データベースクエリ
  5. カスタム javascript コールバック関数

利用モデル 1: javascript 配列からのデータのロード

利用モデル 2: HTML テーブルからのデータのロード

利用モデル 3: XML ファイルからのデータのロード

利用モデル 4: SQL データベースクエリからデータをロードする

下記の説明は、Rico LiveGrid プラグインにおける ASP と PHP の実装に直接当てはまります。 概念は .net の同じですが、実装方法は全く異なります (これがどのように .net で実装されるかについては、"ex2simple.aspx" を調べて下さい)。

利用モデル 5: カスタムコールバック関数を利用してデータをロードする

このモデルは、 xmlHTTPrequest を利用してデータをフェッチするのでは無く、 javascript コールバック関数を 利用してデータをフェッチする事以外はモデル 3 や 4 と同じ方法で動作します。 これにより、コールバック関数で Google Gears を呼ぶような創造的な事をすることが出来ます。 コールバックをセットアップする事は、非常に簡単です。 データプロバイダの URL の文字列を含むデータを AjaxXML または AjaxSQL コンストラクタに渡すのでは無く、 その代りにコールバック関数を渡すだけです。

以下の AjaxXML バッファを利用するコードは examples/client/gridJSbuffer.html から取得出来ます。 "jsfetch" コールバック関数は 100 行の長さで 5 列の幅の二次元配列を返します。 AjaxXML は、そのバッファを(グリッドのスタートアップで)一度だけロードするので、 jsfetch は一度だけ呼ばれます。 このオプションのハッシュは、Prototype の Ajax.Request メソッドで利用されるオプションのハッシュと構造が同じです。

buffer=new Rico.Buffer.AjaxXML(jsfetch);

function jsfetch(options) {
  Rico.writeDebugMsg("jsfetch");
  var newRows=[], offset=options.parameters.offset;
  for (var r=0; r<100; r++) {
    var row=[];
    row.push(offset.toString());
    row.push(new Date().toString());
    for (var c=2; c<5; c++) row.push('cell '+r+':'+c);
    newRows.push(row);
  }
  options.onComplete(newRows);
}

以下の AjaxSQL バッファを利用するコードは examples/client/gridJSbuffer2.html から取得出来ます。 "jsfetch" コールバック関数は、500 行の長さで 5 列の幅の二次元配列をシミュレーションします。 しかし、どんなコールバック中でも、その配列の options.parameters.offset 行から options.parameters.offset + options.parameters.page_size 行までのセクションが返されます。

buffer=new Rico.Buffer.AjaxSQL(jsfetch);

function jsfetch(options) {
  var newRows=[], totrows=500;
  var offset=options.parameters.offset;
  var limit=Math.min(totrows-offset,options.parameters.page_size)
  for (var r=0; r<limit; r++) {
    var row=[];
    row.push(new Date().toString());
    row.push(offset.toString());
    for (var c=2; c<5; c++) row.push('cell '+(r+offset)+':'+c);
    newRows.push(row);
  }
  options.onComplete(newRows,false,totrows);
}

options.onComplete は、次のパラメータをとります。

デバッグ

Rico 2.0 はメッセージログにタイムスタンプデバッグメッセージを配達する能力を持っています。 そのログは、HTML のテキストエリアか、ブラウザの javascript コンソールに表示されるでしょう。

グリッドメニュー

Rico LiveGrid は、多くの機能的なビルトインが付属します その機能にアクセスするために、Rico はメニューのデフォルトの設定を含みます -- ricoLiveGridMenu.js で定義されています。 デフォルトメニューを使うために、単に 'LiveGridMenu' モジュールをロードして、 そのグリッドメニュープロパティを Rico.GridMenu クラスのインスタンスに割り当てて下さい。

  Rico.loadModule('LiveGridMenu');
  ...
  var ex1=new Rico.LiveGrid ('ex1', buffer, grid_options);
  ex1.menu=new Rico.GridMenu();

デフォルトでは、ユーザがグリッドセルをダブルクリックする時メニューが開きます。 メニューを開くイベントを変更するために、グリッドの menuEvent オプションに値を割り当てて下さい。 以下のコードは、右クリックでメニューを開きます。

  Rico.loadModule('LiveGridMenu');
  ...
  var grid_options = {
    menuEvent: 'contextmenu'
  }
  var ex1=new Rico.LiveGrid ('ex1', buffer, grid_options);
  ex1.menu=new Rico.GridMenu();

Rico.GridMenu は、更なるメニューアイテムを追加するために、コールバック(dataMenuHandler)を提供します。 グリッドメニューは常に動的に構築されます -- ユーザーがクリックした行と列のためにカスタマイズされます。 コールバック関数が毎回呼ばれるように、メニューは起動されて、 それぞれの起動で要求されるメニューアイテムを加えなければなりません。

  Rico.loadModule('LiveGridMenu');
  ...
  var ex1=new Rico.LiveGrid ('ex1', buffer, grid_options);
  ex1.menu=new Rico.GridMenu();
  ex1.menu.options.dataMenuHandler=myCustomMenuItems;
  ...
function myCustomMenuItems(grid,r,c,onBlankRow) {
  if (buffer.getWindowValue(r,c)=='Special Value')
    grid.menu.addMenuItem("Special menu item", specialAction);
}
function specialAction() {
  ...
}

完全なカスタムメニューを作成する事も可能です。 例えば、ex5.php/asp/aspx を見て下さい。

注意

リファレンス

コンストラクタ


  var grid = new Rico.LiveGrid (table_id, rico_buffer, grid_options);

オプション

グリッドサイズ

visibleRows (.net の行)
グリッドに何行表示しますか? 正の整数は、グリッドが正確に多くの行を常に含まなければならないことを示しています。 負の値は、以下の意味を持ちます。
minPageRows
表示される行数の最小値。visibleRows が 0 以下の時のみ利用される。(Rico 2b3 からはデフォルトが 2 で、Rico 2b3 までは 1)
maxPageRows
表示される行数の最大値。visibleRows が 0 以下の時のみ利用される。(デフォルトは 50)
defaultWidth
列の初期幅を設定する際に使われる整数。 説明については 列幅オプション を見て下さい。 (デフォルトは 100)
useUnformattedColWidth
列の初期幅を設定する際に使われる真偽値。 説明については 列幅オプション を見て下さい。 (デフォルトは true)
scrollBarWidth
いくらかの計算のために、LiveGrid はページ上のスクロールバーの幅を知っている必要があります。(デフォルトは 19)
minScrollWidth
固定された列の幅がウィンドウ幅を上回る時の、スクロールエリアのピクセル幅の最小値。(デフォルトは 100)

グリッドデータ

offset
表示されるデータの最初の行(デフォルトは 0)
prefetchBuffer
ページのロード時にバッファの(そして、その結果グリッドの)ロードを行いますか?
sortCol
初期ソートのための、列の名前かインデックス
sortDir
初期ソートの方向
取り得る値は 'ASC'、'DESC'
getQueryParms
もし true なら、フィルタパラメータのための、そのウェブページのクエリ文字列をチェックし、そして見つかるどんなフィルタでも適用します。 フィルタパラメータは "f[x]=" の形でなければならず、"x" は列のインデックスです。(デフォルトは false )

ヘッダ構成

frozenColumns
グリッドの左側の固定された列の数(Excel のように)
headingSort
ソートを容易にするために、どのように見出しが表示されるかを定義する文字列。
hdrIconsFirst
見出しの前後に、ソートとフィルタのアイコンを置きます(デフォルトは true)
allowColResize
ユーザによる列のリサイズを許しますか? true なら、個々の列のリサイズを利用不能にするために columnSpecs の noResize を利用します。
panels
第二の見出しとして用いる事が出来る文字列の配列です。 LiveGrid Forms で、入力フォーム上のタブを付けられたパネルのための見出しを提供します。
PanelNamesOnTabHdr
panels[] の文字列を第二の見出しとして利用するために 'true' を設定します。 LiveGrid Forms では、 panels[] は入力フォームとしてのみ利用されるので、'false' が設定されるでしょう。
FilterLocation
フィルタを設置する見出しの行を指定します。 -1 は、新しい行をヘッダに追加し、新しい行がフィルタリングのために利用されるようにします。 filterUI のオプションも見て下さい。
FilterAllToken
選択フィルタで "show all values" を示すトークン(デフォルトは "___ALL___")。

画像

resizeBackground
列のリサイズハンドルに利用される画像(デフォルトは 'resize.gif')
sortAscendImg
列を昇順でソートする事を示すために使われる画像(デフォルトは 'sort_asc.gif')
sortDescendImg
列を降順でソートする事を示すために使われる画像(デフォルトは 'sort_desc.gif')
filterImg
列に対し現在利用中のフィルタを示すために使われる画像(デフォルトは 'filtercol.gif')

クッキーオプション

saveColumnInfo
グリッドのクッキーに、どの詳細設定を保存するかを指定します。 一つのクッキーだけが、それぞれのグリッドのために利用されます。 幅の設定が、列の非表示/表示の状態を含む事に注意して下さい。 (デフォルトは {width:true, filter:false, sort:false})
.netプラグインでは、このオプションは、3 つの別々のプロパティによって表現されます。 saveColumnWidth、saveColumnFilter、saveColumnSort。
cookiePrefix
クッキー名の先頭に付け加えられる文字列(デフォルトは 'RicoGrid.')
cookieDays
数字の日数前のクッキーは期限切れになります。 指定しなければ、クッキーは現在のセッションの間だけ維持されます。(デフォルトは null)
cookiePath
グリッドのクッキーを読む事が出来るトップレベルディレクトリを設定します。 指定しなければ、それはクッキーを設定するページのパスになります。(デフォルトは null)
cookieDomain
クッキーがどのドメインに送られなければならないかについて、ブラウザに知らせます。 指定しなければ、それはクッキーを設定するページのドメインになります。(デフォルトは null)

ハイライティングとセレクション

highlightElem
何がハイライトまたは選択されるかについて指定する文字列。
highlightSection
テーブルのどのセレクションがハイライトされるかについて指定する整数
highlightMethod
セルや行がハイライトされる方法。取り得る値は
highlightClass
クラスによってハイライトされる時、クラス名として利用されます(デフォルトは 'ricoLG_selection')

エクスポートと印刷

maxPrint
ユーザに 印刷/エクスポート を許す最大行数。 印刷/エクスポート を利用不能にするには 0 を設定します。(デフォルトは 1000)
exportWindow
エクスポートウィンドウが生成される時に、 window.open() に渡されるオプション文字列。 (デフォルトは "height=400,width=500,scrollbars=1,menubar=1,resizable=1")

イベントコントロール

menuEvent
グリッドメニューがいつ呼び出されるべきかを指定する文字列
windowResize
window.resize イベントの間にグリッドの大きさを変更するかどうかを指定する真偽値? グリッドがアコーディオンに組み込まれる時に、これに false が設定されなくてはなりません。(デフォルトは true)

イベントハンドル

コンストラクタにオプションでイベントハンドラを渡す事は出来ませんが、LiveGrid が生成された後なら、設定されるかも知れません。

sortHandler
(デフォルトは Rico.LiveGridMethods.sortHandler -- バインドされた)
filterHandler
(デフォルトは Rico.LiveGridMethods.filterHandler -- バインドされた)
onRefreshComplete
(デフォルトは Rico.LiveGridMethods.bookmarkHandler -- バインドされた)
rowOverHandler
(デフォルトは Rico.LiveGridMethods.rowMouseOver -- イベントリスナーとしてバインドされた)
mouseDownHandler
(デフォルトは Rico.LiveGridMethods.selectMouseDown -- イベントリスナーとしてバインドされた)
mouseOverHandler
(デフォルトは Rico.LiveGridMethods.selectMouseOver -- イベントリスナーとしてバインドされた)
mouseUpHandler
(デフォルトは Rico.LiveGridMethods.selectMouseUp -- イベントリスナーとしてバインドされた)
onscroll
グリッドが垂直にスクロールされる時は、いつでも呼ばれます。(デフォルトは null)
onscrollidle
グリッドが垂直にスクロールされた 1、2 秒後に呼ばれます。(デフォルトは null)
click
グリッドセルがクリックされた時に呼ばれます。(デフォルトは menuEvent='click' で無ければ null)
dblclick
グリッドセルがダブルクリックされた時に呼ばれます。(デフォルトは menuEvent='dblclick' で無ければ null)
contextmenu
グリッドセルが右クリックされた時に呼ばれます。(デフォルトは menuEvent='contextmenu' で無ければ null)

列ごとの構成

各々の列のためのオプションは、columnSpecs オプションに含まれます。 columnSpecs は、各々の列のためのエントリに関する配列です。 各々の列のエントリは、以下のいずれかで行う事が出来ます。

Hdg
列の見出しテキストを指定する代わりの方法。 グリッド ID が、html テーブルの代わりに <div> を参照するなら、LiveGrid によってのみ利用されます。
canSort
列をソートする事が出来ます。(デフォルトは grid.options.canSortDefault)
canFilter
列をフィルタする事が出来ます。(デフォルトは grid.options.canFilterDefault)
canDrag
列のセルは、ドラッグアンドドロップオペレーションのソースとして用いられる事が出来ます。 "DragAndDrop" モジュールはロードされなければなりません。 一時的なドラッグオブジェクトは "LiveGridDraggable" クラスが持ちます。 実例として、drag_and_drop_grid.html を見て下さい。(デフォルトは false)
canHide
列を 表示/非表示 する事が出来ます。(デフォルトは grid.options.canHideDefault)
visible
列は、初めは隠されていません。 grid.options.saveColumnInfo.width が true で、列のためのクッキーに値があるなら、クッキーの値が優先されます。 (デフォルトは true)
width
列の初期幅(ピクセルで)を指定する整数。 ここに、それぞれの列の初期幅を設定するために LiveGrid が利用するアルゴリズムがあります。
  1. options.saveColumnInfo.width が true で、列情報がグリッドのクッキーに存在する場合は (以前にグリッドの列の上でリサイズを実行したユーザのために) クッキーのその幅が利用されます。 そうでない場合は、、、
  2. options.columnSpecs に列の幅仕様があれば、その幅仕様が利用されます。一例として、 ex3.php/asp/aspx を見て下さい。そうでない場合は、、、
  3. options.useUnformattedColWidth が true で(デフォルト)、グリッドヘッダが html テーブルから初期化されるならば、htmlテーブルの列の幅が利用されます。 通常 col タグを用いて初期テーブルの列幅をコントロールする事が出来ます。(例えば <col style='width:40px;' >)。 テーブル幅全体がブラウザー幅より小さいならば、これは動作します。 しかし、それがより大きいならば、ブラウザはしばしば "col width" を無視して、全ての列を利用できるウインドウ幅の中に押し込もうとします。 このように、列幅を設定するためにこの方法を使用することは信頼出来ません。 そうでない場合は、、、
  4. options.useUnformattedColWidth が false ならば、列の幅は options.defaultWidth により設定されます。(デフォルトは 100)
したがって、列幅を LiveGrid と SimpleGrid で設定する最も信頼できる方法は、options.columnSpecs[] ですべての列に幅を指定することになります。 多くの列が共通の幅を共有するならば、options.useUnformattedColWidth=false を設定して、options.defaultWidth を共通の幅に設定する事によって、 いくらかの近道をする事が出来ます。
noResize
列のリサイズを許しますか?(デフォルトは grid.options.allowColResize
ClassName
デフォルトでは、LiveGrid はユニークな CSS クラス名を、table_id + '_col' + column_index の命名規約に従い、それぞれの列に割り当てます。 例えば、グリッド 'mygrid' の第 4 列は、クラス名 'mygrid_col3' を持ちます。 ClassName オプションの値は、このデフォルト名をオーバーライドします。 ClassName オプションは、Rico が提供する 'alignright' と 'aligncenter' クラスによって列の整列を指定するために、最も一般的に用いられます。 なので、グリッドの最初の 3 つの列が赤い背景色に白いテキストで表示されることを望むならば、あなたは以下のどちらでもすることが出来ます。
In CSS:
.mygrid_col0 div.ricoLG_cell, 
.mygrid_col1 div.ricoLG_cell, 
.mygrid_col2 div.ricoLG_cell {
  color: white;
  background-color: red;
}
または
In CSS:
.WhiteOnRed div.ricoLG_cell {
  color: white;
  background-color: red;
}

In javascript:
columnSpecs : [{ClassName:'WhiteOnRed'},
               {ClassName:'WhiteOnRed'},
               {ClassName:'WhiteOnRed'},
               ...
最後に、この ClassName がグリッドの見出しに適用されない点に注意してください - ヘッダの整列を達成するためには、<th> タグで align="right" を利用して下さい。
type
これらの値の内の一つを含む文字列。
コントロール
特別なフォーマットを列に提供するのに用いられるオブジェクト。 いくつかの列コントロールは LiveGrid により提供されます。 それらのためのコードは、 ricoLiveGridControls.js にあります。 ここに、提供されるコントロールの簡潔な記述があります。
Rico.TableColumn.checkboxKey(showKey)
<checkbox> <key value> として列のユニークキーを表示し、どのキーがユーザによって選択されているかを見逃しません。 キーの値は <、 >、 または & を含むべきではありません。
Rico.TableColumn.checkbox(checkedValue, uncheckedValue, defaultValue, readOnly)
チェックボックスとして列を表示します。データベースの列は、二つの値のみを含まなければなりません(例えば yes/no)。 以下のコードは、ex7 から取得されます(列の値は 1 と 0)。
columnSpecs: [{canHide:false,
               control:new Rico.TableColumn.checkbox('1','0'),
               ClassName:'aligncenter'},
              'specQty'],
Rico.TableColumn.textbox(boxSize, boxMaxLen, readOnly)
テキストボックス内に列の値を表示します。
Rico.TableColumn.HighlightCell(chkcol,chkval,highlightColor,highlightBackground)
特定の値が指定された列に存在する時、グリッドのセルをハイライトします。 以下のコードは ex2highlight から取得され、列 1 が "HANAR" を含む時、行全体をハイライトします。
var CustId='HANAR';
var CustIdCol=1;
var highlight=Rico.TableColumn.HighlightCell;
...
columnSpecs: [
{ control:new highlight(CustIdCol,CustId,'red','yellow') },
{ control:new highlight(CustIdCol,CustId,'red','yellow') },
{ control:new highlight(CustIdCol,CustId,'red','yellow') },
{ control:new highlight(CustIdCol,CustId,'red','yellow') },
{ control:new highlight(CustIdCol,CustId,'red','yellow') },
{ type:'date', control:new highlight(CustIdCol,CustId,'red','yellow') },
{ type:'date', control:new highlight(CustIdCol,CustId,'red','yellow') }]
Rico.TableColumn.bgColor()
データベースの値が css カラーの名前や値を含みます。
Rico.TableColumn.link(href,target)
データベースの値が、他のページへの URL を含みます。 href パラメータは、文字列に "{x}" を含む事により、グリッドの値への参照を含むかもしれません。 x は列の番号です。 以下のコードは ex6 から取得されます。
columnSpecs: [,
{control:new Rico.TableColumn.link('ex2.asp?id={0}','_blank'),
 width:250},
,'specQty']
Rico.TableColumn.image()
データベースの値が画像への url を含みます。 以下のコードは photos.php から取得されます。
imgctl=new Rico.TableColumn.image();
...
columnSpecs: [
{control:imgctl,width:90},,,
{type:'datetime'},{width:200}]
Rico.TableColumn.lookup(map, defaultCode, defaultDesc)
データベースの値を表示される値にマップします。

アプリケーション特有のロジックを実装する、独自の列コントロールを書く事も可能です。 ここに例があります。
// Display values white on black if
//   first column contains the value "reverse"
// Usage: { control:new MyCustomColumn() }
MyCustomColumn = Class.create();

MyCustomColumn.prototype = {
  initialize: function() {},

  _clear: function(gridCell,windowRow) {
    gridCell.style.color='';
    gridCell.style.backgroundColor='';
    gridCell.innerHTML='&nbsp;';
  },

  _display: function(v,gridCell,windowRow) {
    var col0=this.liveGrid.buffer.getWindowValue(windowRow,0);
    if (col0=="reverse") {
      gridCell.style.color='white';
      gridCell.style.backgroundColor='black';
    } else {
      gridCell.style.color='';
      gridCell.style.backgroundColor='';
    }
    gridCell.innerHTML=this._format(v);
  }
}
filterUI
FilterLocation オプションがグリッドに指定されるならば、filterUI はそれぞれの列がどのようにフィルタされるかについてコントロールします。 もし filterUI が、

数値フォーマット:

multiplier
表示される前に、その値はこの数値によって乗算されます。(デフォルトは 1)
decPlaces
小数点より右側の桁数(デフォルトは 0)
decPoint
小数点のシンボル(翻訳ファイルでオーバーライドされなければ、デフォルトは '.')
thouSep
千桁区切りのためのシンボル。(翻訳ファイルでオーバーライドされなければ、デフォルトは ',')
negSign
負数がどのように表示されるべきかを指定します。取り得る値は
prefix
数に始まりの文字列を付加します。一般的に通貨シンボルです。
suffix
数値の終わりに付加される文字列。例えば、 "%" シンボル。

日付フォーマット:

dateFmt
date または datetime をどのように表示するのかを指定する文字列。 デフォルトは "translateDate" であり、RicoTranslate オブジェクトで利用される dateFmt と timeFmt 文字列を意味します。 (各種言語の翻訳ファイルでオーバーライドされなければ、、date のデフォルトは "mm/dd/yyyy" であり、datetime は "mm/dd/yyyy hh:mm:ss a/pm" です。) dateFmt="localeDate" ならば、その値は javascript のビルトイン関数である toLocaleDateString() を利用してフォーマットされる。 dateFmt="localeDateTime" ならば、その値は javascript のビルトイン関数である toLocaleString() を利用してフォーマットされる。 dateFmt 文字列は、以下の特殊文字シーケンスを含むでしょう。
// display first column as "month year"
columnSpecs : [{type:date, dateFmt:'mmm yyyy'}]
prefix
日付の先頭に付け加えられる文字列
suffix
日付の終わりに付加される文字列。例えば、タイムゾーンを含めるために利用出来ます。
// indicate that times are GMT/UTC
columnSpecs : [{type:datetime, suffix:' UTC'}]