--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
+<html>\r
+<head>\r
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8">\r
+<title>Rico LiveGrid AJAX</title>\r
+<link href="ricoDocs.css" rel="Stylesheet" type="text/css">\r
+\r
+<style type="text/css">\r
+.request, .response {\r
+ border: 1px solid black;\r
+ background-color: #FFF8DC;\r
+ padding: 4px;\r
+}\r
+dt span {\r
+ font-weight:normal;\r
+ font-style:italic;\r
+}\r
+</style>\r
+</head>\r
+\r
+<body>\r
+<h1>Rico LiveGrid AJAX</h1>\r
+\r
+<p>Rico LiveGrid の鍵となる特徴の一つは AJAX を通して動的にデータをロードするその能力です。\r
+このドキュメントは、LiveGrid AJAX のリクエストとレスポンスのフォーマットに焦点を合わせます。\r
+より明確には、LiveGrid <strong>バッファ</strong>オブジェクトがリクエストを生成し、レスポンスを処理します。\r
+それで、もし支配外のウェブサービスからデータが来る状況下にいるなら、ウェブサービスと LiveGrid \r
+の間のインタフェースとして用いられるカスタム LiveGrid バッファクラスを作成して下さい。\r
+しかし、このドキュメントでは Rico ディストリビューションに付属するバッファクラスのリクエストと\r
+レスポンスのフォーマットに焦点を合わせます。\r
+\r
+<p>Rico ディストリビューションは 4 つの異なるバッファクラスを含みます。\r
+<dl>\r
+<dt>Rico.Buffer.Base\r
+<dd>AJAX では無い（すなわち XMLHttpRequest の呼び出しの無い）静的なデータセットの利用。\r
+データは HTML テーブル又は javascript 配列からロードされる事が出来ます。\r
+このバッファは AJAX を利用しないので、このドキュメントでこれ以上議論されません。\r
+<dt><a href='#AjaxXML'>Rico.Buffer.AjaxXML</a>\r
+<dd>すべての LiveGrid データは一回の AJAX の呼び出しでロードされ、データは XML フォーマットで返されます\r
+<dt><a href='#AjaxSQL'>Rico.Buffer.AjaxSQL</a>\r
+<dd>LiveGrid のデータは、ユーザがグリッドを通してスクロールすることにより、塊でロードされます\r
+<dt><a href='#AjaxJSON'>Rico.Buffer.AjaxJSON</a>\r
+<dd>レスポンスが JSON フォーマットである事を除いては AjaxSQL と同じです\r
+</dl>\r
+\r
+<h2><a name='AjaxXML'>Rico.Buffer.AjaxXML</a></h2>\r
+\r
+<p>AjaxXML バッファは、LiveGrid でユーザが行うスクロールの量を考慮しないで、\r
+一回の XMLHttpRequest の実行だけを行います。\r
+AjaxXML バッファは以下の javascript を利用して生成されます。\r
+\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxXML(url,options,ajaxOptions)\r
+</pre>\r
+\r
+<dl>\r
+<dt>url\r
+<dd>データプロバイダへの url を含んでいる文字列。\r
+<dt>options\r
+<dd>以下のどれかを含む Rico バッファオプションオブジェクト。\r
+\r
+<dl>\r
+<dt>bufferTimeout\r
+<dd>タイムアウトを示す前に待ちメッセージをユーザに表示すべきミリ秒の数を指定する整数\r
+デフォルトは 20000 （20 秒）。\r
+\r
+<dt>requestParameters\r
+<dd>XMLHttpRequest の検索文字列に加えられる "parm=value" の形の文字列の配列。\r
+\r
+<dt>isEncoded\r
+<dd>レスポンスが HTML エンコードされるかどうかを指定します。デフォルトは true です。\r
+Rico と共に提供されるすべてのプラグインは、レスポンスをエンコードします。\r
+\r
+<dt>waitMsg\r
+<dd>XMLHttpRequest レスポンスを待つ間ユーザに表示されるメッセージ。\r
+デフォルトは RicoTranslate.getPhraseById("waitForData")。\r
+これがイメージタグである事が出来る点に注意して下さい、例えば。\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxXML(\r
+ url,\r
+ {waitMsg: "<img src='MySpinner.gif'>"},\r
+ ajaxOptions);\r
+</pre>\r
+\r
+<dt>canFilter\r
+<dd>バッファがフィルタリングをサポートするかどうかを示す真偽値。デフォルトは true です。\r
+</dl>\r
+\r
+<dt>ajaxOptions\r
+<dd>Prototype の Ajax.Request メソッドに渡す \r
+<a href='http://prototypejs.org/api/ajax/options'>Ajax オプションオブジェクト</a>。\r
+"parameters" と "onComplete" オプションが指定されるならば、Rico によって利用され、\r
+エフェクトを持ちません。\r
+"method" オプションはデフォルトで "get" ですが、オーバーライドされる事が出来ます。\r
+</dl>\r
+\r
+ここに ex3livegridxml.php から取った実例があります。\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxXML('ricoXMLquery.php');\r
+ex3=new Rico.LiveGrid ('ex3', buffer, grid_options);\r
+</pre>\r
+\r
+<h3>AjaxXML リクエスト</h3>\r
+\r
+<p>grid_options.prefetchBuffer が true （それはデフォルトです）なら、グリッドの初期化の間に、\r
+ricoXMLquery.php からデータをフェッチする、一つの XMLHttpRequest が生成されます。\r
+この URL は、以下のクエリーストリング（検索）パラメータを含みます。\r
+\r
+<dl>\r
+<dt>id\r
+<dd>以前の実例 "ex3" の Rico.LiveGrid() の呼び出しで、\r
+最初のパラメータとして指定されたグリッドの id。\r
+<dt>offset\r
+<dd>返さなければならないデータセットの最初のレコード。 AjaxXML では常に "0" です。\r
+<dt>page_size\r
+<dd>データセットで返されなければならないレコードの数。\r
+AjaxXML では常に "-1" で、すべてのレコードが返されなければならない事を意味します。\r
+</dl>\r
+\r
+<p>加えて、options.requestParameters が指定されるならば、それらもまた含まれる事になります。\r
+そして、ex3 のためのデータのフェッチに利用される完全な URL は、次の通りです。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex3&offset=0&page_size=-1\r
+</pre>\r
+\r
+<h3><a name='AjaxXMLresponse'>AjaxXML レスポンス</a></h3>\r
+\r
+<p>ここに ex3 の LiveGrid を実装するサンプルのレスポンスがあります。\r
+\r
+<pre class='response'>\r
+<?xml version="1.0" encoding="UTF-8"?>\r
+<ajax-response>\r
+ <response type='object' id='ex3_updater'>\r
+ <rows update_ui='true' offset='0'>\r
+ <tr><td>Data for row 1, cell 1</td><td>Data for row 1, cell 2</td></tr>\r
+ <tr><td>Data for row 2, cell 1</td><td>Data for row 2, cell 2</td></tr>\r
+ </rows>\r
+ <rowcount>2</rowcount>\r
+ <debug>Generated by test server</debug>\r
+ </response>\r
+</ajax-response>\r
+</pre>\r
+\r
+<p>リクエストハンドラでレスポンスを作成する時に、レスポンスヘッダの content-type に \r
+text/xml を設定しなければなりません。\r
+xml バージョンと<a href='http://www.opentag.com/xfaq_enc.htm'>文字エンコーディング</a>も指定する必要があります。\r
+エンコーディングの値は非常に重要で、環境に依存します。\r
+二つの一般的な値は "UTF-8" と "iso-8859-1" です。\r
+Java Server Pages (JSP) で、最初の 2、3 行がどのように見えるかは、ここにあります。\r
+<pre>\r
+<% response.setHeader(“Content-Type”, “text/xml”); %>\r
+<?xml version="1.0" encoding="UTF-8"?>\r
+</pre>\r
+\r
+そして、これは PHP ではそれらがどのように見えるかです。\r
+<pre>\r
+header("Content-type: text/xml");\r
+echo "<?xml version='1.0' encoding='UTF-8'?".">\n";\r
+</pre>\r
+\r
+<p>Ajax レスポンスについての、いくつかの重要なアイテムに注意して下さい。\r
+\r
+<p>最初に、レスポンスは <ajax-response></ajax-response> タグで囲まれます。\r
+すべての Rico Ajax レスポンスは、返す XML の root に、この要素を持たなければなりません。\r
+第二に、レスポンスは ajax-response の範囲内に含まれる事に注意して下さい。\r
+レスポンスタグ（<response></response>）はレスポンスの内容を囲みます。\r
+<response> タグの type と id 属性は、Rico 1.1 では必要とされていましたが、Rico 2.0 では無視されます。\r
+最後に、<rowcount> 要素に注意して下さい。\r
+これはデータセットの総行数を指定します。\r
+AjaxXML レスポンスにおいて、これは <tr> 要素の数と一致するはずです。\r
+\r
+<p>デバッグタグ（<debug></debug>）は任意です。\r
+レスポンスはそれらを 0、1、またはそれ以上含むかもしれません。\r
+それぞれのデバッグタグの内容は、Rico の<a href='LiveGrid.html#debug'>メッセージログ機能</a>へ送られます。\r
+Rico プラグインは、ricoXMLquery.php/asp/aspx で ricoXmlResponse.sendDebugMsgs を true に設定することにより、\r
+実行された実際の SQL クエリを返す事が出来ます。\r
+これは、開発の間はとても役に立ちますが、セキュリティーリスク（ユーザに実際のテーブルと列の名前を見せる）\r
+となるので、製品においては削除しなければなりません。\r
+\r
+<p>リクエストの進行中にサーバでエラーが発生するなら、サーバはエラーメッセージを <error></error> \r
+タグで囲んでユーザにエラー情報を返す事が出来ます。\r
+例えば。\r
+\r
+<pre class='response'>\r
+<?xml version="1.0" encoding="UTF-8"?>\r
+<ajax-response>\r
+ <response type='object' id='ex3_updater'>\r
+ <rows update_ui='true' offset='0'>\r
+ </rows>\r
+ <rowcount>0</rowcount>\r
+ <error>Unable to retrieve the data</error>\r
+ </response>\r
+</ajax-response>\r
+</pre>\r
+\r
+<p><error> タグが存在すると、いかなる行データや rowcount も無視されます。\r
+このように、エラーを返す時には <rows> と <rowcount> は含まれる事や省略される事が出来ます。\r
+エラーが発生する時、Rico プラグインはデータベース生成エラーを送ります。\r
+\r
+<h2><a name='AjaxSQL'>Rico.Buffer.AjaxSQL</a></h2>\r
+\r
+<p>AjaxSQL バッファは、AjaxXML バッファにより提供される能力を拡張します。\r
+コンセプトの多くは同じですが、AjaxSQL バッファはより複雑です。\r
+クエリ結果は、一回のレスポンスですべての行を返すのでは無く、塊でバッファに返されます。\r
+また、AjaxSQL バッファはサーバ上でフィルタとソートが発生すると考えられます。\r
+そして、フィルタとソートのパラメータはそれぞれのリクエストに送られなくてはならず、\r
+サーバはそれらのパラメータを正しく処理しなければなりません。\r
+幸いにも、Rico プラグインは、あなたのためにこの複雑さを解決します。\r
+\r
+<p>AjaxSQL バッファは以下の javascript を利用して作成されます。\r
+\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxSQL(url,options,ajaxOptions)\r
+</pre>\r
+\r
+ここに ex2simple.php から取った実例があります。\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxSQL(\r
+ 'ricoXMLquery.php', \r
+ {TimeOut:<? print array_shift(session_get_cookie_params())/60 ?>});\r
+orderGrid=new Rico.LiveGrid ('ex2', buffer, opts);\r
+</pre>\r
+\r
+<dl>\r
+<dt>url\r
+<dd>データプロバイダへの url を含んでいる文字列。\r
+<dt><a name='AjaxSQLoptions'>options</a>\r
+<dd>以下のどれかを含む Rico バッファオプションオブジェクト。\r
+\r
+<dl>\r
+<dt>bufferTimeout\r
+<dd>タイムアウトを示す前に待ちメッセージをユーザに表示すべきミリ秒の数を指定する整数。\r
+デフォルトは 20000 （20 秒）。\r
+\r
+<dt>requestParameters\r
+<dd>XMLHttpRequest の検索文字列に加えられる "parm=value" の形の文字列の配列。\r
+\r
+<dt>isEncoded\r
+<dd>レスポンスが HTML エンコードされるかどうかを指定します。デフォルトは true です。\r
+Rico と共に提供されるすべてのプラグインは、レスポンスをエンコードします。\r
+\r
+<dt>waitMsg\r
+<dd>XMLHttpRequest レスポンスを待つ間ユーザに表示されるメッセージ。\r
+デフォルトは RicoTranslate.getPhraseById("waitForData")。\r
+これがイメージタグである事が出来る点に注意して下さい、例えば。\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxXML(\r
+ url,\r
+ {waitMsg: "<img src='MySpinner.gif'>"},\r
+ ajaxOptions);\r
+</pre>\r
+\r
+<dt>canFilter\r
+<dd>バッファがフィルタリングをサポートするかどうかを示す真偽値。デフォルトは true です。\r
+\r
+<dt>largeBufferSize\r
+<dd>バッファのサイズを設定するために利用されます。デフォルトは 7 です。\r
+実際のバッファサイズは「（グリッドの表示行数）* largeBufferSize」に設定されますが、少なくとも 50 です。\r
+そして、4 行を表示するグリッドは 50 のサイズの最小のバッファを手にいれますが、\r
+一方 30 行を表示するグリッドは 210 のサイズを持ちます。\r
+\r
+<dt>nearLimitFactor\r
+<dd>ユーザがバッファの最後付近にスクロールした時、データの新しいリクエストのトリガーを決定するのに利用されます。\r
+デフォルトは 1 です。\r
+nearLimit の値は「（グリッドの表示行数）* nearLimitFactor」に設定されます。\r
+\r
+<dt>TimeOut\r
+<dd>Rico プラグインは SQL クエリを\r
+<a href='http://www.talkphp.com/general/1077-understanding-life-session.html'>セッション変数</a>に保管します。\r
+サーバはセッションが有効な間だけはデータのリクエストに返答する事が出来ます。\r
+TimeOut オプションはセッションが存続する時間を測るために利用されます。\r
+option.TimeOut が指定され、document に id が "MyGridId_timer" の html 要素があるなら、\r
+その要素の innerHTML はセッションが存続する時間で実装されます。\r
+TimeOut の値は分で指定され、デフォルトを持ちません。\r
+\r
+<dt><a name='sortParmFmt'>sortParmFmt</a>\r
+<dd>セットされるならば、sortParmFmt は Rico 列オブジェクトの属性の名前でなければなりません。\r
+Rico 1.1 互換のフォーマットでリクエストを生成するために、"displayName" を設定して下さい。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&sort_col=Column0&sort_dir=ASC\r
+</pre>\r
+リクエストをこのフォーマットで生成するために、"index" を設定して下さい。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&sort_col=0&sort_dir=ASC\r
+</pre>\r
+指定しない（デフォルト）時、ソートパラメータは、このフォーマットで送信されます（'s' に続く列番号）。\r
+これは、Rico プラグインが期待するものです。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&s0=ASC\r
+</pre>\r
+</dl>\r
+\r
+<dt>ajaxOptions\r
+<dd>Prototype の Ajax.Request メソッドへ渡される <a href='http://prototypejs.org/api/ajax/options'>Ajax オプションオブジェクト</a>。\r
+"parameters" と "onComplete" オプションは Rico によって利用され、指定されたとしても効果がありません。\r
+"method" オプションのデフォルトは "get" ですが、オーバーライドされる事が出来ます。\r
+</dl>\r
+\r
+\r
+\r
+<h3><a name='AjaxSQLrequests'>AjaxSQL リクエスト</a></h3>\r
+\r
+<p>AjaxSQL バッファがより多くのデータを必要とするたびに XMLHttpRequest は生成されます。\r
+offset と page_size パラメータによって指定されるように、データは塊でリクエストされます。\r
+これは、LiveGrid が効率的に何十万ものレコードを表示する事を可能にします。\r
+なぜなら、どんな時でもクライアントサイドバッファに、それらのレコードの小さな部分だけが記録されているからです。\r
+この URL は以下のクエリーストリング（検索）パラメータを含みます。\r
+\r
+<dl>\r
+<dt>id\r
+<dd>以前の実例 "ex2" の Rico.LiveGrid() の呼び出しで、最初のパラメータとして指定されたグリッドの id。\r
+\r
+<dt>offset\r
+<dd>返さなければならないデータセットの最初のレコード。 AjaxXML では常に "0" です。\r
+\r
+<dt>page_size\r
+<dd>データセットで返されなければならないレコードの数。\r
+AjaxXML では常に "-1" で、すべてのレコードが返されなければならない事を意味します。\r
+\r
+<dt>get_total\r
+<dd>true なら、そのレスポンスは、指定されたフィルタと共に（リクエストされた塊だけで無く）\r
+データセットの総行数を含む <rowcount> 要素を含むはずです。\r
+"get_total=true" は、どんな時にユーザがフィルタを変更しても、\r
+グリッドを実装するための最初のリクエストの間に送られます。\r
+\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&get_total=true\r
+</pre>\r
+\r
+<dt>sX <span>（ X は列の数です）</span>\r
+<dd>列 X によってソートされるべき結果を指定します。\r
+パラメータは ASC または DESC です。\r
+<a href='#sortParmFmt'>options.sortParmFmt</a> も見て下さい。\r
+たとえ、このパラメータのフォーマットが一度に複数列をソートする事を理論的に許すとしても、\r
+それは現在の LiveGrid UI では不可能です。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&s0=ASC\r
+</pre>\r
+\r
+<dt>f[X][op] <span>（ X は列の数です）</span>\r
+<dd>列 X に適応されているフィルタオペレータを指定します。\r
+パラメータは以下の内の一つです。EQ（等しい）、NE（等しく無い）、GE（以上）、LE（以下）、LIKE、NULL、NOTNULL\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&f[0][op]=EQ\r
+</pre>\r
+\r
+<dt>f[X][len] <span>（ X は列の数です）</span>\r
+<dd>供給されているフィルタの値の数を指定します。\r
+これは EQ、GE、LE、そして LIKE フィルタオペレータでは 1 です。\r
+これは NULL そして NOTNULL オペレータでは 0 です。\r
+これは NE では 1 またはそれ以上です。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&f[0][op]=EQ&f[0][len]=1\r
+</pre>\r
+\r
+<dt>f[X][Y] <span>（ X は列の数です）</span>\r
+<dd>EQ、NE、GE、LE、そして LIKE フィルタオペレータのフィルタの（複数の）値を指定します。\r
+Y は 0 から f[X][len]-1 の範囲です。\r
+LIKE オペレータでの '*' は ワイルドカードとして扱われ、\r
+それは Rico プラグインによって多くのデータベースのために '%' に変換されます。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&...&f[0][op]=EQ&f[0][len]=1&f[0][0]=Column0Value\r
+</pre>\r
+</dl>\r
+\r
+<p>加えて、options.requestParameters が指定されるならば、それらもまた含まれる事になります。\r
+そして、ex2 のためのデータのフェッチに利用される完全な URL は、次の通りでしょう。\r
+<pre class='request'>\r
+ricoXMLquery.php?id=ex2&offset=0&page_size=28\r
+</pre>\r
+\r
+\r
+<h3>AjaxSQL レスポンス</h3>\r
+\r
+<p>AjaxSQL レスポンスのフォーマットは、<a href='#AjaxXMLresponse'>AjaxXML レスポンス</a>と全く同じです。\r
+\r
+<h2><a name='AjaxJSON'>Rico.Buffer.AjaxJSON</a></h2>\r
+\r
+<p>AjaxJSON バッファは Jeremy Green により作成された AjaxSQL バッファの拡張です。\r
+AjaxJSON バッファは、以下の javascript を利用して作成されます。\r
+\r
+<pre>\r
+buffer=new Rico.Buffer.AjaxJSON(jsonUrl,options)\r
+</pre>\r
+\r
+<dl>\r
+<dt>url\r
+<dd>JSON データプロバイダへの url を含んでいる文字列。\r
+\r
+<dt>options\r
+<dd>Rico バッファオプションオブジェクト。\r
+AjaxJSON で利用出来る値は <a href='#AjaxSQLoptions'>AjaxSQL</a> のそれらと同じです。\r
+</dl>\r
+\r
+\r
+<h3>AjaxJSON リクエスト</h3>\r
+\r
+<p>AjaxJSON リクエストのフォーマットは、<a href='#AjaxSQLrequests'>AjaxSQL リクエスト</a>と全く同じです。\r
+\r
+\r
+<h3>AjaxJSON レスポンス</h3>\r
+\r
+<p>ここに JSON フォーマットによる LiveGrid レスポンスの実例があります。\r
+\r
+<pre class='response'>\r
+{\r
+ "update_ui":"true",\r
+ "offset":"0",\r
+ "rowCount":"20",\r
+ "rows":[\r
+ {"id":"1","name":"Bob"},\r
+ {"id":"2","name":"Bill"}\r
+ ]\r
+}\r
+</pre>\r
+\r
+<p>そのフォーマットは Rico.Buffer.AjaxSQL バッファによって消費される XML に基づくデータに密接に従い、\r
+そしてそれによってすべての値は返されるべきです。\r
+データオブジェクトの 'rows' の値オブジェクトは、行を表す JS ハッシュであるそれぞれの要素による通常の JS 配列です。\r
+ハッシュの key/value の組み合わせは colName/colValue であるべきです。\r
+\r
+\r
+</body>\r
+</html>\r
projects / infodrom / rico3 / blobdiff