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