1JsHttpRequest: JavaScript "AJAX" data loader 2 3@license LGPL 4@author Dmitry Koterov, http://en.dklab.ru/lib/JsHttpRequest/ 5@version 5.x $Id$ 6 7This document describes the protocol used by JsHttpRequest library. 8 9 10Backend -> Frontend 11------------------- 12 13JsHttpRequest library uses 3 slightly different version of output protocol 14depending on the loader used. 15 16- SCRIPT loader: 17 18 Content-type: text/javascript; charset=... 19 JsHttpRequest.dataReady({ id: ..., js: ..., text: ...}) 20 21 The charset is always set equal to the base backend charset. 22 23- XML loader: 24 25 Content-type: text/plain; charset=... 26 { id: ..., js: ..., text: ...} 27 28 The charset may be UTF-8 (of the backend supports JSON conversion 29 functions) or the base backend charset. We have to use text/plain 30 because of some Opera 8 bugs. 31 32- FORM loader: 33 34 Content-type: text/html; charset=... 35 <script type="text/javascript" language="JavaScript"><!-- 36 top && top.JsHttpRequestGlobal && 37 top.JsHttpRequestGlobal.dataReady({ id: ..., js: ..., text: ...}) 38 //--></script> 39 40 The charset is always set equal to the base backend charset. Note 41 that we use text/html Content-type, because the result is loaded 42 into dynamically created IFRAME and must be valid HTML. 43 44(Note that you may always use a fixed charset in your backends, 45e.g. UTF-8. The frontend is a fully Unicode supporting library.) 46 47The common part of all these constructions is always represented as 48a plain JavaScript object: 49 50{ 51 id: <loading ID>, 52 js: <JavaScript resulting object>, 53 text: <text data, e.g. - debug STDOUT content> 54} 55 56Meanings of object properties are: 57 58- id: ID of the loading passed by a frontend. This ID is used to 59 associate the resulting data with corresponding onreadystatechange 60 handler and generated automatically. 61- js: a JavaScript object representing multi-dimensional array 62 passed from the backend to a frontend. 63- text: other backend data (usually captured STDOUT). 64 65Note that for XML the loader ID is always equals to 0, because we 66do not need an explicit binding between a result data and a loader: 67binding is performed automatically by ActiveX or XMLHttpRequest. 68 69ATTENTION! If you want to create your own backend, you should guarantee 70that the following formats are satisfied, else you may get a JavaScript 71backend exception. E.g., if your script dies with some error, it should 72pass the message to the "text" property, not write it to the output 73directly. In PHP backend it is done via ob_start() handlers. 74 75 76 77Frontend -> Backend 78------------------- 79 80The protocol is very simple and fully compatible with standard PHP's features. 81Frontend passes to backend a list of key=value pairs using GET or POST method. 82 83 841. Auxiliary information 85 86Each loading process is supplied with a piece of information appended to the 87end of QUERY_STRING: 88 89 PHPSESSID=<sid>&JsHttpRequest=<id>-<loader> 90 91- PHPSESSID=<sid> is the session information. (Of course you may use another 92 name instead of PHPSESSID, it is tuned inside the JsHttpRequest object.) 93 Here <sid> is the session identifier extracted from document cookies or 94 from the current document URL. This method is fully comatible with PHP 95 sessions support. 96 97- <loader> is the name of a loader used. E.g.: "xml", "script", "form". 98 99- <id> is the loading ID. It is generated automatically and unique for 100 each of the loading process. (Exception is the XML loader: it always 101 uses zero ID.) This ID is passed back by a backend to determine which 102 result is binded to which callback action (see above). 103 104 1052. Character conversions 106 107Each character of a key/value is encoded by JavaScript standard escape() 108function (with exception for "+": it is converted to "%2B"). That means: 109 110- Unicode non-ASCII character (e.g. with code 0x1234) is encoded to e.g. %u1234. 111- Character "+" is converted to "%2B". 112- URL-allowed characters (e.g. letters, digits etc.) remain unchanged. 113- Other ASCII character (e.g. 0x15) is converted to e.g. %15. 114 115Samples: 116 117- "�����" -> "%u043F%u0440%u043E%u0431%u0430" 118- "abcde" -> "abcde" 119- "a[x]" -> "a%5Bx%5D" 120- "a+b" -> "a%2Bb" 121 122 1233. Array conversions 124 125JsHttpRequest supports multi-dimensional associative arrays created from 126standard JavaScript objects. Each key of the key=value pair is created 127based on all parents of the corresponding object property. PHP notation 128of multi-dimensional arrays is used. 129 130Samples: 131 132- JavaScript: { a: 123, b: { c: 456, d: 789 } } 133- GET/POST data: a=123&b[c]=456&b[d]=789 134- PHP's array: array('a' => 123, 'b' => array('c' => 456, 'd' => 789)) 135 136- JavaScript: { a: 123, b: [4, 5] } 137- GET/POST data: a=123&b[]=4&b[]=5 138- PHP's array: array('a' => 123, 'b' => arrat(4, 5)) 139 140You see that JavaScript objects are 1:1 converted to PHP's arrays, and 141an array encoding format is compatible with such behaviour. 142 143 1444. Content-type header 145 146Available Content-type headers generated by a frontend depend on a loader 147and a method used. 148 149Samples (format: <loader>.<method>): 150 151- application/x-www-form-urlencoded: script.*, xml.GET, form.GET 152- multipart/form-data: form.POST 153- application/octet-stream: xml.POST 154 155Please note that xml.POST generates application/octet-stream, but 156NOT application/x-www-form-urlencoded. It is needed to avoid the standard 157PHP behavior of POST data parsing, because we have to process the 158data encoding manually (PHP does not support JavaScript escape() encoding 159directly). 160 161Also note that multipart/form-data format used for FORM loader, because 162this is the only way to support file uploads. 163