Your IP : 172.28.240.42
JsHttpRequest: JavaScript "AJAX" data loader
@license LGPL
@author Dmitry Koterov, http://en.dklab.ru/lib/JsHttpRequest/
@version 5.x $Id$
This document describes the protocol used by JsHttpRequest library.
Backend -> Frontend
-------------------
JsHttpRequest library uses 3 slightly different version of output protocol
depending on the loader used.
- SCRIPT loader:
Content-type: text/javascript; charset=...
JsHttpRequest.dataReady({ id: ..., js: ..., text: ...})
The charset is always set equal to the base backend charset.
- XML loader:
Content-type: text/plain; charset=...
{ id: ..., js: ..., text: ...}
The charset may be UTF-8 (of the backend supports JSON conversion
functions) or the base backend charset. We have to use text/plain
because of some Opera 8 bugs.
- FORM loader:
Content-type: text/html; charset=...
<script type="text/javascript" language="JavaScript"><!--
top && top.JsHttpRequestGlobal &&
top.JsHttpRequestGlobal.dataReady({ id: ..., js: ..., text: ...})
//--></script>
The charset is always set equal to the base backend charset. Note
that we use text/html Content-type, because the result is loaded
into dynamically created IFRAME and must be valid HTML.
(Note that you may always use a fixed charset in your backends,
e.g. UTF-8. The frontend is a fully Unicode supporting library.)
The common part of all these constructions is always represented as
a plain JavaScript object:
{
id: <loading ID>,
js: <JavaScript resulting object>,
text: <text data, e.g. - debug STDOUT content>
}
Meanings of object properties are:
- id: ID of the loading passed by a frontend. This ID is used to
associate the resulting data with corresponding onreadystatechange
handler and generated automatically.
- js: a JavaScript object representing multi-dimensional array
passed from the backend to a frontend. If null is passed here,
we treat it as 500 Internal Server Error in the frontend.
- text: other backend data (usually captured STDOUT).
Note that for XML the loader ID is always equals to 0, because we
do not need an explicit binding between a result data and a loader:
binding is performed automatically by ActiveX or XMLHttpRequest.
ATTENTION! If you want to create your own backend, you should guarantee
that the following formats are satisfied, else you may get a JavaScript
backend exception. E.g., if your script dies with some error, it should
pass the message to the "text" property, not write it to the output
directly. In PHP backend it is done via ob_start() handlers.
Frontend -> Backend
-------------------
The protocol is very simple and fully compatible with standard PHP's features.
Frontend passes to backend a list of key=value pairs using GET or POST method.
1. Auxiliary information
Each loading process is supplied with a piece of information appended to the
end of QUERY_STRING:
PHPSESSID=<sid>&JsHttpRequest=<id>-<loader>
- PHPSESSID=<sid> is the session information. (Of course you may use another
name instead of PHPSESSID, it is tuned inside the JsHttpRequest object.)
Here <sid> is the session identifier extracted from document cookies or
from the current document URL. This method is fully comatible with PHP
sessions support.
- <loader> is the name of a loader used. E.g.: "xml", "script", "form".
- <id> is the loading ID. It is generated automatically and unique for
each of the loading process. (Exception is the XML loader: it always
uses zero ID.) This ID is passed back by a backend to determine which
result is binded to which callback action (see above).
2. Character conversions
Each character of a key/value is encoded by JavaScript standard escape()
function (with exception for "+": it is converted to "%2B"). That means:
- Unicode non-ASCII character (e.g. with code 0x1234) is encoded to e.g. %u1234.
- Character "+" is converted to "%2B".
- URL-allowed characters (e.g. letters, digits etc.) remain unchanged.
- Other ASCII character (e.g. 0x15) is converted to e.g. %15.
Samples:
- "ïðîáà" -> "%u043F%u0440%u043E%u0431%u0430"
- "abcde" -> "abcde"
- "a[x]" -> "a%5Bx%5D"
- "a+b" -> "a%2Bb"
3. Array conversions
JsHttpRequest supports multi-dimensional associative arrays created from
standard JavaScript objects. Each key of the key=value pair is created
based on all parents of the corresponding object property. PHP notation
of multi-dimensional arrays is used.
Samples:
- JavaScript: { a: 123, b: { c: 456, d: 789 } }
- GET/POST data: a=123&b[c]=456&b[d]=789
- PHP's array: array('a' => 123, 'b' => array('c' => 456, 'd' => 789))
- JavaScript: { a: 123, b: [4, 5] }
- GET/POST data: a=123&b[]=4&b[]=5
- PHP's array: array('a' => 123, 'b' => array(4, 5))
You see that JavaScript objects are 1:1 converted to PHP's arrays, and
an array encoding format is compatible with such behaviour.
4. Content-type header
Available Content-type headers generated by a frontend depend on a loader
and a method used.
Samples (format: <loader>.<method>):
- application/x-www-form-urlencoded: script.*, xml.GET, form.GET
- multipart/form-data: form.POST
- application/octet-stream: xml.POST
Please note that xml.POST generates application/octet-stream, but
NOT application/x-www-form-urlencoded. It is needed to avoid the standard
PHP behavior of POST data parsing, because we have to process the
data encoding manually (PHP does not support JavaScript escape() encoding
directly).
Also note that multipart/form-data format used for FORM loader, because
this is the only way to support file uploads.