====== UnJSq v0.2 ======

<note important>
//UnJSq// is now superseded by the //Atlas// toolkit : http://atlastk.org
</note>


Documentation for the latest //[[/UnJSq/]]// //Node.js// //API//.

===== Changes to previous version =====

==== v0.2.0 ====

Adding ''removeAttribute'' and ''focus''.


==== v0.1.0 ====
  * All the //cast// related methods were removed, hence also the related ''data-xdh-cast'' attribute; there are now (//CSS//) classes related methods (''add''|''remove''|''toggle'')''Class''(''es'')), and the (''en''|''dis'')''ableElement''(''s'') methods (which also applies to ''style'' tags) to achieve same goal,
  * the ''launch(...)'' function do no more require a ''rootDir'' parameter, the directory relative to which the file was served by the //httpd// server; it's assumed that this directory is the one which contains the main //JS// script (the one which is given as parameter to ''node'').


===== The files =====

//UnJSq// needs at least two files, and a third, named ''head.html'', is highly recommended.

Take a look to the provided examples to see how they work.

==== The '.js' file ====

This file is mandatory. It's the one you launch with the ''node'' command and which contains the handling of below functions, objects and their methods, through callbacks registered to respond on events from the user interface.


==== The '.xsl' file ====

The ''.xsl'' files are those which filenames are given to the below ''setLayout(...)'' methods of the ''DOM'' object. That must at least be one to display the initial layout of the application. There can be others to provide the layout of sub-elements of the global layout.

All the ''.xsl'' files must be stored into and are referenced relatively to the directory referenced by the ''rootDir'' parameter of the below ''listen(...)'' function.
==== The 'head.html' file ====
This file is not mandatory, but it contains the entries you usually put in the ''head'' section of an //HTML// page, such as style or script definitions, or the ''title'' tag. It has to be in the directory defined in the ''rootDir'' parameter of the below ''listen(...)'' function.
===== 'data-xdh-*' attributes =====

Through the //XSL// transformation, //DOM// elements can have special attributes which are handled by //UnJSq//.

==== The 'data-xdh-onevent(s)' attributes ====

An element can have a ''data-xdh-onevent'' attribute, which are of following form:

<code>
event|action
</code>

The value of ''event'' can be all the available //JS// event, without the ''on'' prefix. When the given event is launched on the concerned element, the callback registered with the below //register(...)// function and associate with the tag of value ''action'' will be called.

''action'' alone can be specified, without ''event'', then the action is associated with the default event for the given element. For example, setting ''data-xdh-onevent=%%"%%Submit%%"%%'' on a button element is the same as setting ''data-xdh-onevent=%%"%%click|Submit%%"%%'', that is, the callback associated to tag ''Submit'' with function //register(...)// will be called when an ''onclick'' event is detected on the given button.

With the ''data-xdh-onevents'' attribute (with a final ''s''), several actions on an element can be specified, by enclosing each ''event|action'' pair between paranthesis (''('''')'') and separating them with a pipe (''|'').


==== The 'data-xdh-widget' attribute ====

This attribute can be used to dress an element with a //jQuery// widget.

The form is:

''name|[parameters|[retrieving_function]]''.

The needed //CSS// and scripts must be put in the ''head.html'' file as indicated in the widget's documentation.

The activation of the widget is made by calling the ''dressWidgets(...)'' method of the ''DOM'' object. For some widgets, this have to be made __after__ an eventual call to ''setContent(s)'' to fill the widgets.

=== 'name' ===

''name'' is the name of the widget.

In the documentation of the widget, you often find a instruction such as ''$(...).//function//(...);''. ''name'' is simply ''//function//'' (without the parameters).

=== 'parameters' ===
 
''parameters'' are the parameters of the widget you usually given to the ''$(...).widget(...)'' instruction, with the enclosing parenthesis. If this parameters contains a parenthesis or a pipe, they must be escaped with the backslash character (''\('', ''\)'', ''\|'').

=== 'retrieving_function' ===

For some widget, to retrieve its content, you have to call a special function. In this case, put this function here, the parenthesis and pipes escaped with the backslash character (''\('', ''\)'', ''\|'')

===== Functions =====

==== 'listen' ====

<code javascript>
listen(callback, rootDir, action)
</code>

Launches the server, with ''callback'' being called for each new session. This callback must return an instantiation of the ''DOM'' class (see below), or a subclass of it.

''rootDir'' (string) will prefix all the filename parameters needed by the various methods described below (in other word, all the files must be stored in a directory with name the value of ''rootDir'').

''action'' (string) is one of the tag registered with below //register(...)// function, whose //callback// will be called for each new connection.

==== 'register' ====

<code javascript>
register( tagsAndCallbacks )
</code>

Register for each event tag (''data-xdh-onevent(s)'') the callback to be called. ''tagsAndCallbacks'' must have following form:

<code javascript>
{
	'tag1': callback1,
	'tag2': callback2,
	'tag3': callback3,
	...
}
</code>

''tag//x//'' are the event tag as defined in ''data-xdh-onevent(s)'' //HTML// tags, and ''callback//x//'', callbacks which receive as first parameter the object returned by the callback given to the  ''listen'' function, and, as second parameter, the id of the element which receives the event.

===== Objects =====

==== 'Tree' ====

A tree to which an //XSL// transformation is applied to obtain the //HTML// file to display.

=== constructor ===

It takes no parameter.

=== 'popTag' ===

<code javascript>
popTag()
</code>

Closes the tag previously opened by ''pushTag(...)'', and the parent one becomes the current one.

=== 'pushTag' ===

<code javascript>
pushTag( name );
</code>

Create a new tag of name ''name'' (a string) as child of the current one, and becomes the current one.

=== 'putAttribute' ===

<code javascript>
putAttribute( name, value );
</code>

Add attribute of name ''name'' and value ''value'' (both being strings) to the current tag. 

=== 'putValue' ===

<code javascript>
putValue( name );
</code>

Set the string ''value'' as value for the current tag.


==== 'DOM' ====

The object containing data for each users' session, and with method to manipulate the //DOM// displayed by the web browser.

All methods with a parameter ''callback'' are called asynchronously, and ''callback'' is called once the method is achieved, with no parameter unless specified otherwise.

=== Global ===

== constructor ==

Takes no parameter.

== 'alert' ==

<code javascript>
alert(message[,callback])
</code>

Displays an alert box with the string ''message'' as message.

== 'confirm' ==

<code javascript>
confirm(message[,callback])
</code>

Displays a confirmation box with the string ''message'' as message. Optional ''callback'' is called with a //boolean// parameter set to ''true'' when the user clicks the OK button, and ''false'' when the user clicks the cancel button.

== 'focus' ==

<code javascript>
focus(id[,callback])
</code>

Gives the focus to element of id ''id'' (string).
=== 'Attribute' ===

== 'getAttribute' ==

<code javascript>
getAttribute(id,name[,callback])
</code>

Calls optional callback ''callback'' with, as parameter, a string with the value of attribute named ''name'' (string) of the element of id ''id'' (string).

== 'removeAttribute' ==

<code javascript>
removeAttribute(id,name[,callback])
</code>

Removes attribute named ''name'' (string) from element of id ''id'' (string).

== 'setAttribute' ==

<code javascript>
setAttribute(id,name,value[,callback])
</code>

Set ''value'' as value (string) for the attribute named ''name'' (string) of the element of id ''id'' (string).


=== 'Class' ===

Following methods allows to handle classes (the //CSS// related ''class'' attributes of //HTML// tags), by respectively add, remove or toggle (i.e. adds if not present, otherwise removes) a class to elements identified by their **id**s (the content of the ''id'' attribute from //HTML// tags).

''idsAndClasses'' must have following form:

<code javascript>
{
	'id1': 'class1',
	'id2': 'class2',
	'id3': 'class3',
	...
}
</code>

== 'AddClass' ==

<code javascript>
addClass(id,class[,callback])
</code>

== 'AddClasses' ==

<code javascript>
addClasses(idsAndClasses[,callback])
</code>

== 'RemoveClass' ==

<code javascript>
removeClass(id,class[,callback])
</code>


== 'RemoveClasses' ==

<code javascript>
removeClasses(idsAndClasses[,callback])
</code>

== 'ToggleClass' ==

<code javascript>
toggleClass(id,class[,callback])
</code>


== 'ToggleClasses' ==

<code javascript>
toggleClasses(idsAndClasses[,callback])
</code>









=== 'Content' ===

== 'getContent' ==

<code javascript>
getContent(id[,callback])
</code>

Retrieve the content of the element of id ''id'' (string) and calls optional callback ''callback'' with, as parameter, the asked content(as string).

== 'getContents' ==

<code javascript>
getContents(ids[,callback])
</code>

Retrieves the content of the elements of ids ''ids'' (array of strings) and calls optional callback ''callback'' with, as parameter, an array of strings containing the asked contents, in the same order as ''ids''.


== 'setContent' ==

<code javascript>
setContent(id,value[,callback])
</code>

Set the content of element of id ''id'' (string) to ''value'' (string).

== 'setContents' ==

<code javascript>
setContents(idsAndValues[,callback])
</code>

Set the content all element which ''id'' are in ''idsAndValues'' to corresponding value.

''idsAndValues'' must have following form:

<code javascript>
{
	'id1': 'value1',
	'id2': 'value2',
	'id3': 'value3',
	...
}
</code>

''id//x//'' is the //id// as set as value for the ''id'' attribute of the concerned //HTML// tag, and ''value//x//'' the string corresponding to the content.



=== 'Layout' ===

== 'setLayout' ==

<code javascript>
setLayout(id,tree,xslFilename[,callback])
</code>

Replaces the content of element with string ''id'' as id with the result of the transformation of the //XSL// file with name ''xslFilename'' (string) applied to the ''tree'' instance of a ''Tree'' class (see above). The content of the ''rootDir'' parameter given to the above ''listen'' function will be added as prefix to the XSL file name.

If ''id'' is an empty string, the content of the entire document is replaced by the resulting transformation.

=== 'Property' ===

== 'getProperty' ==

<code javascript>
getProperty(id,name[,callback])
</code>

Calls optional callback ''callback'' with, as parameter, a string with the value of property named ''name'' (string) of the element of id ''id'' (string).

== 'setProperty' ==

<code javascript>
setProperty(id,name,value[,callback])
</code>

Set ''value'' as value (string) for the property named ''name'' (string) of the element of id ''id'' (string).


=== 'Widget' ===

== 'dressWidgets' ==

<code javascript>
dressWidgets(id[,callback])
</code>

Create the widget for each elements which are children of the element of id ''id'' (string) and which have a ''data-xdh-widget'' attribute.