1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
\r
4 <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
\r
5 <title>Rico LiveGrid AJAX</title>
\r
6 <link href="ricoDocs.css" rel="Stylesheet" type="text/css">
\r
8 <style type="text/css">
\r
9 .request, .response {
\r
10 border: 1px solid black;
\r
11 background-color: #FFF8DC;
\r
22 <h1>Rico LiveGrid AJAX</h1>
\r
24 <p>Rico LiveGrid の鍵となる特徴の一つは AJAX を通して動的にデータをロードするその能力です。
\r
25 このドキュメントは、LiveGrid AJAX のリクエストとレスポンスのフォーマットに焦点を合わせます。
\r
26 より明確には、LiveGrid <strong>バッファ</strong>オブジェクトがリクエストを生成し、レスポンスを処理します。
\r
27 それで、もし支配外のウェブサービスからデータが来る状況下にいるなら、ウェブサービスと LiveGrid
\r
28 の間のインタフェースとして用いられるカスタム LiveGrid バッファクラスを作成して下さい。
\r
29 しかし、このドキュメントでは Rico ディストリビューションに付属するバッファクラスのリクエストと
\r
30 レスポンスのフォーマットに焦点を合わせます。
\r
32 <p>Rico ディストリビューションは 4 つの異なるバッファクラスを含みます。
\r
34 <dt>Rico.Buffer.Base
\r
35 <dd>AJAX では無い(すなわち XMLHttpRequest の呼び出しの無い)静的なデータセットの利用。
\r
36 データは HTML テーブル又は javascript 配列からロードされる事が出来ます。
\r
37 このバッファは AJAX を利用しないので、このドキュメントでこれ以上議論されません。
\r
38 <dt><a href='#AjaxXML'>Rico.Buffer.AjaxXML</a>
\r
39 <dd>すべての LiveGrid データは一回の AJAX の呼び出しでロードされ、データは XML フォーマットで返されます
\r
40 <dt><a href='#AjaxSQL'>Rico.Buffer.AjaxSQL</a>
\r
41 <dd>LiveGrid のデータは、ユーザがグリッドを通してスクロールすることにより、塊でロードされます
\r
42 <dt><a href='#AjaxJSON'>Rico.Buffer.AjaxJSON</a>
\r
43 <dd>レスポンスが JSON フォーマットである事を除いては AjaxSQL と同じです
\r
46 <h2><a name='AjaxXML'>Rico.Buffer.AjaxXML</a></h2>
\r
48 <p>AjaxXML バッファは、LiveGrid でユーザが行うスクロールの量を考慮しないで、
\r
49 一回の XMLHttpRequest の実行だけを行います。
\r
50 AjaxXML バッファは以下の javascript を利用して生成されます。
\r
53 buffer=new Rico.Buffer.AjaxXML(url,options,ajaxOptions)
\r
58 <dd>データプロバイダへの url を含んでいる文字列。
\r
60 <dd>以下のどれかを含む Rico バッファオプションオブジェクト。
\r
64 <dd>タイムアウトを示す前に待ちメッセージをユーザに表示すべきミリ秒の数を指定する整数
\r
65 デフォルトは 20000 (20 秒)。
\r
67 <dt>requestParameters
\r
68 <dd>XMLHttpRequest の検索文字列に加えられる "parm=value" の形の文字列の配列。
\r
71 <dd>レスポンスが HTML エンコードされるかどうかを指定します。デフォルトは true です。
\r
72 Rico と共に提供されるすべてのプラグインは、レスポンスをエンコードします。
\r
75 <dd>XMLHttpRequest レスポンスを待つ間ユーザに表示されるメッセージ。
\r
76 デフォルトは RicoTranslate.getPhraseById("waitForData")。
\r
77 これがイメージタグである事が出来る点に注意して下さい、例えば。
\r
79 buffer=new Rico.Buffer.AjaxXML(
\r
81 {waitMsg: "<img src='MySpinner.gif'>"},
\r
86 <dd>バッファがフィルタリングをサポートするかどうかを示す真偽値。デフォルトは true です。
\r
90 <dd>Prototype の Ajax.Request メソッドに渡す
\r
91 <a href='http://prototypejs.org/api/ajax/options'>Ajax オプションオブジェクト</a>。
\r
92 "parameters" と "onComplete" オプションが指定されるならば、Rico によって利用され、
\r
94 "method" オプションはデフォルトで "get" ですが、オーバーライドされる事が出来ます。
\r
97 ここに ex3livegridxml.php から取った実例があります。
\r
99 buffer=new Rico.Buffer.AjaxXML('ricoXMLquery.php');
\r
100 ex3=new Rico.LiveGrid ('ex3', buffer, grid_options);
\r
103 <h3>AjaxXML リクエスト</h3>
\r
105 <p>grid_options.prefetchBuffer が true (それはデフォルトです)なら、グリッドの初期化の間に、
\r
106 ricoXMLquery.php からデータをフェッチする、一つの XMLHttpRequest が生成されます。
\r
107 この URL は、以下のクエリーストリング(検索)パラメータを含みます。
\r
111 <dd>以前の実例 "ex3" の Rico.LiveGrid() の呼び出しで、
\r
112 最初のパラメータとして指定されたグリッドの id。
\r
114 <dd>返さなければならないデータセットの最初のレコード。 AjaxXML では常に "0" です。
\r
116 <dd>データセットで返されなければならないレコードの数。
\r
117 AjaxXML では常に "-1" で、すべてのレコードが返されなければならない事を意味します。
\r
120 <p>加えて、options.requestParameters が指定されるならば、それらもまた含まれる事になります。
\r
121 そして、ex3 のためのデータのフェッチに利用される完全な URL は、次の通りです。
\r
122 <pre class='request'>
\r
123 ricoXMLquery.php?id=ex3&offset=0&page_size=-1
\r
126 <h3><a name='AjaxXMLresponse'>AjaxXML レスポンス</a></h3>
\r
128 <p>ここに ex3 の LiveGrid を実装するサンプルのレスポンスがあります。
\r
130 <pre class='response'>
\r
131 <?xml version="1.0" encoding="UTF-8"?>
\r
132 <ajax-response>
\r
133 <response type='object' id='ex3_updater'>
\r
134 <rows update_ui='true' offset='0'>
\r
135 <tr><td>Data for row 1, cell 1</td><td>Data for row 1, cell 2</td></tr>
\r
136 <tr><td>Data for row 2, cell 1</td><td>Data for row 2, cell 2</td></tr>
\r
138 <rowcount>2</rowcount>
\r
139 <debug>Generated by test server</debug>
\r
141 </ajax-response>
\r
144 <p>リクエストハンドラでレスポンスを作成する時に、レスポンスヘッダの content-type に
\r
145 text/xml を設定しなければなりません。
\r
146 xml バージョンと<a href='http://www.opentag.com/xfaq_enc.htm'>文字エンコーディング</a>も指定する必要があります。
\r
147 エンコーディングの値は非常に重要で、環境に依存します。
\r
148 二つの一般的な値は "UTF-8" と "iso-8859-1" です。
\r
149 Java Server Pages (JSP) で、最初の 2、3 行がどのように見えるかは、ここにあります。
\r
151 <% response.setHeader(“Content-Type”, “text/xml”); %>
\r
152 <?xml version="1.0" encoding="UTF-8"?>
\r
155 そして、これは PHP ではそれらがどのように見えるかです。
\r
157 header("Content-type: text/xml");
\r
158 echo "<?xml version='1.0' encoding='UTF-8'?".">\n";
\r
161 <p>Ajax レスポンスについての、いくつかの重要なアイテムに注意して下さい。
\r
163 <p>最初に、レスポンスは <ajax-response></ajax-response> タグで囲まれます。
\r
164 すべての Rico Ajax レスポンスは、返す XML の root に、この要素を持たなければなりません。
\r
165 第二に、レスポンスは ajax-response の範囲内に含まれる事に注意して下さい。
\r
166 レスポンスタグ(<response></response>)はレスポンスの内容を囲みます。
\r
167 <response> タグの type と id 属性は、Rico 1.1 では必要とされていましたが、Rico 2.0 では無視されます。
\r
168 最後に、<rowcount> 要素に注意して下さい。
\r
169 これはデータセットの総行数を指定します。
\r
170 AjaxXML レスポンスにおいて、これは <tr> 要素の数と一致するはずです。
\r
172 <p>デバッグタグ(<debug></debug>)は任意です。
\r
173 レスポンスはそれらを 0、1、またはそれ以上含むかもしれません。
\r
174 それぞれのデバッグタグの内容は、Rico の<a href='LiveGrid.html#debug'>メッセージログ機能</a>へ送られます。
\r
175 Rico プラグインは、ricoXMLquery.php/asp/aspx で ricoXmlResponse.sendDebugMsgs を true に設定することにより、
\r
176 実行された実際の SQL クエリを返す事が出来ます。
\r
177 これは、開発の間はとても役に立ちますが、セキュリティーリスク(ユーザに実際のテーブルと列の名前を見せる)
\r
178 となるので、製品においては削除しなければなりません。
\r
180 <p>リクエストの進行中にサーバでエラーが発生するなら、サーバはエラーメッセージを <error></error>
\r
181 タグで囲んでユーザにエラー情報を返す事が出来ます。
\r
184 <pre class='response'>
\r
185 <?xml version="1.0" encoding="UTF-8"?>
\r
186 <ajax-response>
\r
187 <response type='object' id='ex3_updater'>
\r
188 <rows update_ui='true' offset='0'>
\r
190 <rowcount>0</rowcount>
\r
191 <error>Unable to retrieve the data</error>
\r
193 </ajax-response>
\r
196 <p><error> タグが存在すると、いかなる行データや rowcount も無視されます。
\r
197 このように、エラーを返す時には <rows> と <rowcount> は含まれる事や省略される事が出来ます。
\r
198 エラーが発生する時、Rico プラグインはデータベース生成エラーを送ります。
\r
200 <h2><a name='AjaxSQL'>Rico.Buffer.AjaxSQL</a></h2>
\r
202 <p>AjaxSQL バッファは、AjaxXML バッファにより提供される能力を拡張します。
\r
203 コンセプトの多くは同じですが、AjaxSQL バッファはより複雑です。
\r
204 クエリ結果は、一回のレスポンスですべての行を返すのでは無く、塊でバッファに返されます。
\r
205 また、AjaxSQL バッファはサーバ上でフィルタとソートが発生すると考えられます。
\r
206 そして、フィルタとソートのパラメータはそれぞれのリクエストに送られなくてはならず、
\r
207 サーバはそれらのパラメータを正しく処理しなければなりません。
\r
208 幸いにも、Rico プラグインは、あなたのためにこの複雑さを解決します。
\r
210 <p>AjaxSQL バッファは以下の javascript を利用して作成されます。
\r
213 buffer=new Rico.Buffer.AjaxSQL(url,options,ajaxOptions)
\r
216 ここに ex2simple.php から取った実例があります。
\r
218 buffer=new Rico.Buffer.AjaxSQL(
\r
219 'ricoXMLquery.php',
\r
220 {TimeOut:<? print array_shift(session_get_cookie_params())/60 ?>});
\r
221 orderGrid=new Rico.LiveGrid ('ex2', buffer, opts);
\r
226 <dd>データプロバイダへの url を含んでいる文字列。
\r
227 <dt><a name='AjaxSQLoptions'>options</a>
\r
228 <dd>以下のどれかを含む Rico バッファオプションオブジェクト。
\r
232 <dd>タイムアウトを示す前に待ちメッセージをユーザに表示すべきミリ秒の数を指定する整数。
\r
233 デフォルトは 20000 (20 秒)。
\r
235 <dt>requestParameters
\r
236 <dd>XMLHttpRequest の検索文字列に加えられる "parm=value" の形の文字列の配列。
\r
239 <dd>レスポンスが HTML エンコードされるかどうかを指定します。デフォルトは true です。
\r
240 Rico と共に提供されるすべてのプラグインは、レスポンスをエンコードします。
\r
243 <dd>XMLHttpRequest レスポンスを待つ間ユーザに表示されるメッセージ。
\r
244 デフォルトは RicoTranslate.getPhraseById("waitForData")。
\r
245 これがイメージタグである事が出来る点に注意して下さい、例えば。
\r
247 buffer=new Rico.Buffer.AjaxXML(
\r
249 {waitMsg: "<img src='MySpinner.gif'>"},
\r
254 <dd>バッファがフィルタリングをサポートするかどうかを示す真偽値。デフォルトは true です。
\r
256 <dt>largeBufferSize
\r
257 <dd>バッファのサイズを設定するために利用されます。デフォルトは 7 です。
\r
258 実際のバッファサイズは「(グリッドの表示行数)* largeBufferSize」に設定されますが、少なくとも 50 です。
\r
259 そして、4 行を表示するグリッドは 50 のサイズの最小のバッファを手にいれますが、
\r
260 一方 30 行を表示するグリッドは 210 のサイズを持ちます。
\r
262 <dt>nearLimitFactor
\r
263 <dd>ユーザがバッファの最後付近にスクロールした時、データの新しいリクエストのトリガーを決定するのに利用されます。
\r
265 nearLimit の値は「(グリッドの表示行数)* nearLimitFactor」に設定されます。
\r
268 <dd>Rico プラグインは SQL クエリを
\r
269 <a href='http://www.talkphp.com/general/1077-understanding-life-session.html'>セッション変数</a>に保管します。
\r
270 サーバはセッションが有効な間だけはデータのリクエストに返答する事が出来ます。
\r
271 TimeOut オプションはセッションが存続する時間を測るために利用されます。
\r
272 option.TimeOut が指定され、document に id が "MyGridId_timer" の html 要素があるなら、
\r
273 その要素の innerHTML はセッションが存続する時間で実装されます。
\r
274 TimeOut の値は分で指定され、デフォルトを持ちません。
\r
276 <dt><a name='sortParmFmt'>sortParmFmt</a>
\r
277 <dd>セットされるならば、sortParmFmt は Rico 列オブジェクトの属性の名前でなければなりません。
\r
278 Rico 1.1 互換のフォーマットでリクエストを生成するために、"displayName" を設定して下さい。
\r
279 <pre class='request'>
\r
280 ricoXMLquery.php?id=ex2&...&sort_col=Column0&sort_dir=ASC
\r
282 リクエストをこのフォーマットで生成するために、"index" を設定して下さい。
\r
283 <pre class='request'>
\r
284 ricoXMLquery.php?id=ex2&...&sort_col=0&sort_dir=ASC
\r
286 指定しない(デフォルト)時、ソートパラメータは、このフォーマットで送信されます('s' に続く列番号)。
\r
287 これは、Rico プラグインが期待するものです。
\r
288 <pre class='request'>
\r
289 ricoXMLquery.php?id=ex2&...&s0=ASC
\r
294 <dd>Prototype の Ajax.Request メソッドへ渡される <a href='http://prototypejs.org/api/ajax/options'>Ajax オプションオブジェクト</a>。
\r
295 "parameters" と "onComplete" オプションは Rico によって利用され、指定されたとしても効果がありません。
\r
296 "method" オプションのデフォルトは "get" ですが、オーバーライドされる事が出来ます。
\r
301 <h3><a name='AjaxSQLrequests'>AjaxSQL リクエスト</a></h3>
\r
303 <p>AjaxSQL バッファがより多くのデータを必要とするたびに XMLHttpRequest は生成されます。
\r
304 offset と page_size パラメータによって指定されるように、データは塊でリクエストされます。
\r
305 これは、LiveGrid が効率的に何十万ものレコードを表示する事を可能にします。
\r
306 なぜなら、どんな時でもクライアントサイドバッファに、それらのレコードの小さな部分だけが記録されているからです。
\r
307 この URL は以下のクエリーストリング(検索)パラメータを含みます。
\r
311 <dd>以前の実例 "ex2" の Rico.LiveGrid() の呼び出しで、最初のパラメータとして指定されたグリッドの id。
\r
314 <dd>返さなければならないデータセットの最初のレコード。 AjaxXML では常に "0" です。
\r
317 <dd>データセットで返されなければならないレコードの数。
\r
318 AjaxXML では常に "-1" で、すべてのレコードが返されなければならない事を意味します。
\r
321 <dd>true なら、そのレスポンスは、指定されたフィルタと共に(リクエストされた塊だけで無く)
\r
322 データセットの総行数を含む <rowcount> 要素を含むはずです。
\r
323 "get_total=true" は、どんな時にユーザがフィルタを変更しても、
\r
324 グリッドを実装するための最初のリクエストの間に送られます。
\r
326 <pre class='request'>
\r
327 ricoXMLquery.php?id=ex2&...&get_total=true
\r
330 <dt>sX <span>( X は列の数です)</span>
\r
331 <dd>列 X によってソートされるべき結果を指定します。
\r
332 パラメータは ASC または DESC です。
\r
333 <a href='#sortParmFmt'>options.sortParmFmt</a> も見て下さい。
\r
334 たとえ、このパラメータのフォーマットが一度に複数列をソートする事を理論的に許すとしても、
\r
335 それは現在の LiveGrid UI では不可能です。
\r
336 <pre class='request'>
\r
337 ricoXMLquery.php?id=ex2&...&s0=ASC
\r
340 <dt>f[X][op] <span>( X は列の数です)</span>
\r
341 <dd>列 X に適応されているフィルタオペレータを指定します。
\r
342 パラメータは以下の内の一つです。EQ(等しい)、NE(等しく無い)、GE(以上)、LE(以下)、LIKE、NULL、NOTNULL
\r
343 <pre class='request'>
\r
344 ricoXMLquery.php?id=ex2&...&f[0][op]=EQ
\r
347 <dt>f[X][len] <span>( X は列の数です)</span>
\r
348 <dd>供給されているフィルタの値の数を指定します。
\r
349 これは EQ、GE、LE、そして LIKE フィルタオペレータでは 1 です。
\r
350 これは NULL そして NOTNULL オペレータでは 0 です。
\r
351 これは NE では 1 またはそれ以上です。
\r
352 <pre class='request'>
\r
353 ricoXMLquery.php?id=ex2&...&f[0][op]=EQ&f[0][len]=1
\r
356 <dt>f[X][Y] <span>( X は列の数です)</span>
\r
357 <dd>EQ、NE、GE、LE、そして LIKE フィルタオペレータのフィルタの(複数の)値を指定します。
\r
358 Y は 0 から f[X][len]-1 の範囲です。
\r
359 LIKE オペレータでの '*' は ワイルドカードとして扱われ、
\r
360 それは Rico プラグインによって多くのデータベースのために '%' に変換されます。
\r
361 <pre class='request'>
\r
362 ricoXMLquery.php?id=ex2&...&f[0][op]=EQ&f[0][len]=1&f[0][0]=Column0Value
\r
366 <p>加えて、options.requestParameters が指定されるならば、それらもまた含まれる事になります。
\r
367 そして、ex2 のためのデータのフェッチに利用される完全な URL は、次の通りでしょう。
\r
368 <pre class='request'>
\r
369 ricoXMLquery.php?id=ex2&offset=0&page_size=28
\r
373 <h3>AjaxSQL レスポンス</h3>
\r
375 <p>AjaxSQL レスポンスのフォーマットは、<a href='#AjaxXMLresponse'>AjaxXML レスポンス</a>と全く同じです。
\r
377 <h2><a name='AjaxJSON'>Rico.Buffer.AjaxJSON</a></h2>
\r
379 <p>AjaxJSON バッファは Jeremy Green により作成された AjaxSQL バッファの拡張です。
\r
380 AjaxJSON バッファは、以下の javascript を利用して作成されます。
\r
383 buffer=new Rico.Buffer.AjaxJSON(jsonUrl,options)
\r
388 <dd>JSON データプロバイダへの url を含んでいる文字列。
\r
391 <dd>Rico バッファオプションオブジェクト。
\r
392 AjaxJSON で利用出来る値は <a href='#AjaxSQLoptions'>AjaxSQL</a> のそれらと同じです。
\r
396 <h3>AjaxJSON リクエスト</h3>
\r
398 <p>AjaxJSON リクエストのフォーマットは、<a href='#AjaxSQLrequests'>AjaxSQL リクエスト</a>と全く同じです。
\r
401 <h3>AjaxJSON レスポンス</h3>
\r
403 <p>ここに JSON フォーマットによる LiveGrid レスポンスの実例があります。
\r
405 <pre class='response'>
\r
407 "update_ui":"true",
\r
411 {"id":"1","name":"Bob"},
\r
412 {"id":"2","name":"Bill"}
\r
417 <p>そのフォーマットは Rico.Buffer.AjaxSQL バッファによって消費される XML に基づくデータに密接に従い、
\r
418 そしてそれによってすべての値は返されるべきです。
\r
419 データオブジェクトの 'rows' の値オブジェクトは、行を表す JS ハッシュであるそれぞれの要素による通常の JS 配列です。
\r
420 ハッシュの key/value の組み合わせは colName/colValue であるべきです。
\r