_____________________________________________________________ (C) byteson, simple tiny Ajaj interaction library. _____________________________________________________________ ------------------------------------------------------------- Summary - 1 What does Ajaj mean ? - 2 What is byteson ? - 3 byteson API - 4 Extra byteson.convert method Informations - 5 Generic Object options Informations 1 - What does Ajaj mean ? _____________________________________________________________ ------------------------------------------------------------- Ajaj means Asynchronous JavaScript and JSON and is a fast, bandwidth safe and portable way to send or recieve JavaScript variables using JSON (JavaScript Object Notation) convertion. Ajaj is really a good Ajax alternative and is very simple to implement with every compatible server side language. To read more about JSON and its language compatibility list please visit this page: http://json.org/ 2 - What is byteson ? _____________________________________________________________ ------------------------------------------------------------- byteson is a lightweight low-level library that can send or recieve simple or complex variables using the powerful JSON protocol. byteson converts automatically variables using internal JSON convertion algorithm, based on original json.js file: http://www.json.org/json.js byteson is part of byte* family and is optimized to be compressed with common JavaScript compressors then has a clean and simple source code. byteson has a MIT style License: http://www.opensource.org/licenses/mit-license.php 3 - byteson API _____________________________________________________________ ------------------------------------------------------------- - convert public method byteson.convert(params:* [, result:Instance]):* @param * String or Object @param Instance optional new generic class instance if first parameter is an object. @return * new Date or new Instance with object parameters. NOTE: please read Extra byteson.convert method Informations to know more about this method (Index N# 4). - decode public method byteson.decode(params:String):* @param String valid JSON encoded string @return * converted variable or undefined is params is not a JSON compatible string. @example byteson.decode('{"param":"value"}'); // object byteson.decode('["one",two,true,false,null,{},[1,2]]'); // array NOTE: this method uses the same regular expression of original json.js code: http://www.json.org/json.js - encode public method byteson.encode(params:*):String @param * Array, Boolean, Date, Number, Object or String variable. @return String JSON genric object rappresentation or empty string if param is not compatible. @example byteson.encode(new Array(1,"two")); // '[1,"two"]' var obj = new Object(); obj.param = "value"; obj.param2 = "value2"; byteson.encode(obj); // '{"param":"value","param2":"value2"}' - request public method byteson.request(page:String [, params:* [, options:Object ]]):Boolean @param String valid server side url to call @param * every JSON compatible variable to send @param Object byteson dedicated generic options object. Please read Generic Object options Informations to know more (Index N# 5). @return Boolean true if request is possible, false if browser doesn't support Ajaj. NOTE: If You send params argument request will send JSON value using the POST method. You could get this JSON sent string using the "byteson" POST variable. This will be automatically encoded using encodeURIComponent function then You need to decode, if necessary, and then parse with your favourite JSON porting. - xhr public method byteson.xhr(void):* @return * new XMLHttpRequest (Xml H R => xhr) or null if browser is not compatible. 4 - Extra byteson.convert method Informations _____________________________________________________________ ------------------------------------------------------------- This method is used by byteson.encode method but should be used to do these convertions too: - JSON string to Date object: byteson.convert(decodedDate:String):Date If You recieve a date string rappresentation You could convert into a native Date object. Example: byteson.request(page, "givMeServerDate", {load:function(response){ // response is a json decoded string // i.e. 2006-11-09T14:42:30 var serverDate = byteson.convert(response); alert(serverDate); // Thu Nov 09 2006 14:42:30 GMT+0100 (Rome, Europe) }}); - object to generic class: byteson.convert({params:values}, new GenericClass):new Instance of GenericClass With a decoded JSON object You could convert them into a new instance of your Generic Class. Example: function MyClass(somevar){ this.getVar = function(){ return somevar; }; this.param = "somevalue"; }; var instance = new MyClass("example"); var encoded = byteson.encode(instance); // {"param":"somevalue"} var decoded = byteson.decode(encoded); // decoded instanceof Object => true // decoded instanceof MyClass => false decoded = byteson.convert(decoded, new MyClass("example")); // decoded instanceof Object => true // decoded instanceof MyClass => true decoded.getVar(); // example 5 - Generic Object options Informations _____________________________________________________________ ------------------------------------------------------------- ------------ | Parameters | ------------ async:Boolean asynchronous (true) or synchronous (false) interaction, true by default decode:Boolean uses decodeURIComponent before JSON to JS convertion timeout:Unsigned Integer (ms) uses timeout for the reuqest (calls error method, if present, with "timeout" String as first argument) pass:String optional password, null by default user:String optional user name, null by default -------------------- | Interaction Scheme | -------------------- options | ----- init ----- | | error send | ---- loading ---- | | error load init [readyState = 1] options.init(xhr, request) called before xhr.send(*) [xhr.open is just called] You can modify headers or everything else. send [readyState = 2] options.send(xhr, request) called when xhr has opened connection and is sending informations NOTE: Please remember that Opera browser, and maybe others, doesn't burn this event. loading [readystate = 3] options.loading(xhr, request) called when xhr is downloading the request. With some browser headers and responseText lenght are available, then You should implement a sort of preload. load [readyState = 4] options.load(*, xhr, request) [* is the JSON decoded variable or undefined] called on interaction complete if xhr.status is 200 or 304. error [readyState = 4] options.error(string, xhr, request) [string is 'Request failure\nStatus:' + xhr.status or string 'timeout'] called after init on request failure or called on intercation complete if status is different from 200 or 304. ---------------------- | The new request param | ---------------------- New request param is an object that contains request informations. It has 3 properties: page, params and options. These properties are the same used when byteson.request is called and should be useful to know wich request fails or is used expecially whhen You use the same function or the same options object to perform every request.