mirror of
https://github.com/Oreolek/ifhub.club.git
synced 2024-07-08 01:14:24 +03:00
164 lines
5.7 KiB
Plaintext
164 lines
5.7 KiB
Plaintext
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:
|
||
|
||
- "<22><><EFBFBD><EFBFBD><EFBFBD>" -> "%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.
|