====== UnJSq v0.1 ======

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



===== 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-cast' attribute ====

Through this attribute, an element can be hide, disabled or be displayed normally through the ''setCast(s)ByTag(s)'' methods of ''DOM'' object. See this methods for more details.

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

==== 'launch' ====

<code javascript>
launch(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( tag, callback )
register( tagsAndCallbacks )
</code>

Register for each event tag (''data-xdh-onevent(s)'') the callback to be called. ''Tag'' is a string containing the event tag, and ''callback'' the callback to call for this event. You can register one callback at once with first form, or register several callbacks at once with the second form. ''tagAndCallback'' must have following form:

<code javascript>
[
[tag1,callback1],
[tag2,callback2],
[tag3,callback3],
...
]
</code>

''tag//x//'' are strings, 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.

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

=== '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.
=== '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).

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

=== '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).

=== '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).

=== 'setCastById' ===

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

Set the cast of element of id ''id'' (string) for ''value'' as cast value.

''value'' can have following value:
  * ''Plain'': the element is displayed normally,
  * ''Disable'' or ''Disabled'': the element appears as disabled,
  * ''Hide'' or ''Hidden'': the element is hidden.



=== 'setCastsByIds' ===

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

Sets the value of the cast of all element of ''idsAndValues'' to the corresponding cast value.

''idsAndValues'' must have following form:
<code javascript>
[
[id1,value1],
[id2,value2],
[id3,value3],
...
]
</code>

''id//x//'' are strings, and ''value//x//'' are also strings, which value are the same as those indicated at //setCastById//.


=== 'setCastByTag' ===

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

Sets the cast of all element which are children of element of id ''id'' (string), and which have an attribute ''data-xdh-cast'' with value ''tag'' (string), the cast of value ''value'', which can take as value one of those indicated in //setCastById//.

if ''id'' is an empty string, all the //DOM// elements are searched for the appropriate attribute.

=== 'setCastsByTags' ===

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

Sets the value of the cast of all element which are children of the element of id ''id'' (string) and  which have for value of the attribute ''data-xdh-cast'' one of given tag in ''tagsAndValues'' to the corresponding cast value.

''tagsAndValues'' must have following form:
<code javascript>
[
[tag1,value1],
[tag2,value2],
[tag3,value3],
...
]
</code>

''tag//x//'' are strings, and ''value//x//'' are also strings, which value are the same as those indicated at //setCastById//.

If ''id'' is an empty string, all the //DOM// elements are searched for the appropriate attribute.

=== '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//'' and ''value//x//'' must all be strings.

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

=== '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).