Rico LiveGrid の鍵となる特徴の一つは AJAX を通して動的にデータをロードするその能力です。 このドキュメントは、LiveGrid AJAX のリクエストとレスポンスのフォーマットに焦点を合わせます。 より明確には、LiveGrid バッファオブジェクトがリクエストを生成し、レスポンスを処理します。 それで、もし支配外のウェブサービスからデータが来る状況下にいるなら、ウェブサービスと LiveGrid の間のインタフェースとして用いられるカスタム LiveGrid バッファクラスを作成して下さい。 しかし、このドキュメントでは Rico ディストリビューションに付属するバッファクラスのリクエストと レスポンスのフォーマットに焦点を合わせます。
Rico ディストリビューションは 4 つの異なるバッファクラスを含みます。
AjaxXML バッファは、LiveGrid でユーザが行うスクロールの量を考慮しないで、 一回の XMLHttpRequest の実行だけを行います。 AjaxXML バッファは以下の javascript を利用して生成されます。
buffer=new Rico.Buffer.AjaxXML(url,options,ajaxOptions)
buffer=new Rico.Buffer.AjaxXML(
url,
{waitMsg: "<img src='MySpinner.gif'>"},
ajaxOptions);
buffer=new Rico.Buffer.AjaxXML('ricoXMLquery.php');
ex3=new Rico.LiveGrid ('ex3', buffer, grid_options);
grid_options.prefetchBuffer が true （それはデフォルトです）なら、グリッドの初期化の間に、 ricoXMLquery.php からデータをフェッチする、一つの XMLHttpRequest が生成されます。 この URL は、以下のクエリーストリング（検索）パラメータを含みます。
加えて、options.requestParameters が指定されるならば、それらもまた含まれる事になります。 そして、ex3 のためのデータのフェッチに利用される完全な URL は、次の通りです。
ricoXMLquery.php?id=ex3&offset=0&page_size=-1
ここに ex3 の LiveGrid を実装するサンプルのレスポンスがあります。
<?xml version="1.0" encoding="UTF-8"?>
<ajax-response>
<response type='object' id='ex3_updater'>
<rows update_ui='true' offset='0'>
<tr><td>Data for row 1, cell 1</td><td>Data for row 1, cell 2</td></tr>
<tr><td>Data for row 2, cell 1</td><td>Data for row 2, cell 2</td></tr>
</rows>
<rowcount>2</rowcount>
<debug>Generated by test server</debug>
</response>
</ajax-response>
リクエストハンドラでレスポンスを作成する時に、レスポンスヘッダの content-type に text/xml を設定しなければなりません。 xml バージョンと文字エンコーディングも指定する必要があります。 エンコーディングの値は非常に重要で、環境に依存します。 二つの一般的な値は "UTF-8" と "iso-8859-1" です。 Java Server Pages (JSP) で、最初の 2、3 行がどのように見えるかは、ここにあります。
<% response.setHeader(“Content-Type”, “text/xml”); %> <?xml version="1.0" encoding="UTF-8"?>そして、これは PHP ではそれらがどのように見えるかです。
header("Content-type: text/xml");
echo "<?xml version='1.0' encoding='UTF-8'?".">\n";
Ajax レスポンスについての、いくつかの重要なアイテムに注意して下さい。
最初に、レスポンスは <ajax-response></ajax-response> タグで囲まれます。 すべての Rico Ajax レスポンスは、返す XML の root に、この要素を持たなければなりません。 第二に、レスポンスは ajax-response の範囲内に含まれる事に注意して下さい。 レスポンスタグ（<response></response>）はレスポンスの内容を囲みます。 <response> タグの type と id 属性は、Rico 1.1 では必要とされていましたが、Rico 2.0 では無視されます。 最後に、<rowcount> 要素に注意して下さい。 これはデータセットの総行数を指定します。 AjaxXML レスポンスにおいて、これは <tr> 要素の数と一致するはずです。
デバッグタグ（<debug></debug>）は任意です。 レスポンスはそれらを 0、1、またはそれ以上含むかもしれません。 それぞれのデバッグタグの内容は、Rico のメッセージログ機能へ送られます。 Rico プラグインは、ricoXMLquery.php/asp/aspx で ricoXmlResponse.sendDebugMsgs を true に設定することにより、 実行された実際の SQL クエリを返す事が出来ます。 これは、開発の間はとても役に立ちますが、セキュリティーリスク（ユーザに実際のテーブルと列の名前を見せる） となるので、製品においては削除しなければなりません。
リクエストの進行中にサーバでエラーが発生するなら、サーバはエラーメッセージを <error></error> タグで囲んでユーザにエラー情報を返す事が出来ます。 例えば。
<?xml version="1.0" encoding="UTF-8"?>
<ajax-response>
<response type='object' id='ex3_updater'>
<rows update_ui='true' offset='0'>
</rows>
<rowcount>0</rowcount>
<error>Unable to retrieve the data</error>
</response>
</ajax-response>
<error> タグが存在すると、いかなる行データや rowcount も無視されます。 このように、エラーを返す時には <rows> と <rowcount> は含まれる事や省略される事が出来ます。 エラーが発生する時、Rico プラグインはデータベース生成エラーを送ります。
AjaxSQL バッファは、AjaxXML バッファにより提供される能力を拡張します。 コンセプトの多くは同じですが、AjaxSQL バッファはより複雑です。 クエリ結果は、一回のレスポンスですべての行を返すのでは無く、塊でバッファに返されます。 また、AjaxSQL バッファはサーバ上でフィルタとソートが発生すると考えられます。 そして、フィルタとソートのパラメータはそれぞれのリクエストに送られなくてはならず、 サーバはそれらのパラメータを正しく処理しなければなりません。 幸いにも、Rico プラグインは、あなたのためにこの複雑さを解決します。
AjaxSQL バッファは以下の javascript を利用して作成されます。
buffer=new Rico.Buffer.AjaxSQL(url,options,ajaxOptions)ここに ex2simple.php から取った実例があります。
buffer=new Rico.Buffer.AjaxSQL(
'ricoXMLquery.php',
{TimeOut:<? print array_shift(session_get_cookie_params())/60 ?>});
orderGrid=new Rico.LiveGrid ('ex2', buffer, opts);
buffer=new Rico.Buffer.AjaxXML(
url,
{waitMsg: "<img src='MySpinner.gif'>"},
ajaxOptions);
ricoXMLquery.php?id=ex2&...&sort_col=Column0&sort_dir=ASCリクエストをこのフォーマットで生成するために、"index" を設定して下さい。
ricoXMLquery.php?id=ex2&...&sort_col=0&sort_dir=ASC指定しない（デフォルト）時、ソートパラメータは、このフォーマットで送信されます（'s' に続く列番号）。 これは、Rico プラグインが期待するものです。
ricoXMLquery.php?id=ex2&...&s0=ASC
AjaxSQL バッファがより多くのデータを必要とするたびに XMLHttpRequest は生成されます。 offset と page_size パラメータによって指定されるように、データは塊でリクエストされます。 これは、LiveGrid が効率的に何十万ものレコードを表示する事を可能にします。 なぜなら、どんな時でもクライアントサイドバッファに、それらのレコードの小さな部分だけが記録されているからです。 この URL は以下のクエリーストリング（検索）パラメータを含みます。
ricoXMLquery.php?id=ex2&...&get_total=true
ricoXMLquery.php?id=ex2&...&s0=ASC
ricoXMLquery.php?id=ex2&...&f[0][op]=EQ
ricoXMLquery.php?id=ex2&...&f[0][op]=EQ&f[0][len]=1
ricoXMLquery.php?id=ex2&...&f[0][op]=EQ&f[0][len]=1&f[0][0]=Column0Value
加えて、options.requestParameters が指定されるならば、それらもまた含まれる事になります。 そして、ex2 のためのデータのフェッチに利用される完全な URL は、次の通りでしょう。
ricoXMLquery.php?id=ex2&offset=0&page_size=28
AjaxSQL レスポンスのフォーマットは、AjaxXML レスポンスと全く同じです。
AjaxJSON バッファは Jeremy Green により作成された AjaxSQL バッファの拡張です。 AjaxJSON バッファは、以下の javascript を利用して作成されます。
buffer=new Rico.Buffer.AjaxJSON(jsonUrl,options)
AjaxJSON リクエストのフォーマットは、AjaxSQL リクエストと全く同じです。
ここに JSON フォーマットによる LiveGrid レスポンスの実例があります。
{
"update_ui":"true",
"offset":"0",
"rowCount":"20",
"rows":[
{"id":"1","name":"Bob"},
{"id":"2","name":"Bill"}
]
}
そのフォーマットは Rico.Buffer.AjaxSQL バッファによって消費される XML に基づくデータに密接に従い、 そしてそれによってすべての値は返されるべきです。 データオブジェクトの 'rows' の値オブジェクトは、行を表す JS ハッシュであるそれぞれの要素による通常の JS 配列です。 ハッシュの key/value の組み合わせは colName/colValue であるべきです。