byteson :: simple tiny Ajaj interactions library

byteson converts automatically sent JSON string with encodeURIComponent function.

This function is the best to send unicode JS chars using utf-8 charset and every recent server-side language can manage or modifiy this kind of charset.

When your favourite server-side language recieves byteson post JSON string, it should deocode, if necessary, this one.

With php, for example, You could use utf8_decode function, just before JSON to PHP parsing (i.e. before json_decode or Pear $ServiceJSON->decode).

If You just use utf-8 as charset with your server-side you don't need to decode anything.

When You write a byteson dedicated response, than a JSON string, You should convert this one into utf-8 compatible string.

With PHP, for example, you could simply use utf8_encode over JSON encoded string (i.e. after json_encode or $ServiceJSON->encode)

Note that You don't need to use urlencode or rawurlencode functions but You could use that but you need to specify decode:true inside options generic object.

With this option, byteson will decode automatically recieved string with decodeURIComponent function, just one time and before JSON convertion.

This method is used by byteson.encode method but should be used to do these convertions too

• JSON string to Date object
• object to generic class

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 more about this special method inside byteson summary txt file (index number 4)

Returns a JavaScript variable from a valid JSON encoded string or returns undefined.

Returned variable types

• null
• Array
• Boolean
• Number
• Object
• String

byteson.decode(params:String):*

	@param	String		valid JSON encoded string
	@return	*		converted variable or undefined
				is params is not a JSON compatible string.

Note: JSON Date is encoded as a string and returned value is decoded as a String too. You could convert this kind of string using byteson.convert to get original Date object

Creates a valid JSON string rappresention of generic object.

Encoded variable types

• null
• Array
• Boolean
• Date
• Number
• Object
• String

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.

Note: doesn't accept undefined or unknown values

Creates and manage a JSON request, sending an encoded generic variable.

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.
	@return	Boolean		true if request is possible, false if browser doesn't support Ajaj.

Note 1: 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.

Note 2: Please read Generic Object options Informations inside byteson summary txt file (index number 5).

Creates an XMLHttpRequest object and returns them or null, if this is not available.

Parameters list

byteson.xhr(void):*

	@return	*		new XMLHttpRequest (Xml H R => xhr) or null if browser
				is not compatible.

 	 ------------
	| 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.

Note: You could read these informations inside byteson summary txt file.