mirror of
https://github.com/Oreolek/ifhub.club.git
synced 2024-07-08 09:24:25 +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.
|