UnJSq v0.2

Documentation for the latest UnJSq Node.js API.

Adding removeAttribute and focus.

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

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.

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

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.

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

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

event|action

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

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 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 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 (\(, \), \|).

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 (\(, \), \|)

listen(callback, rootDir, action)

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( tagsAndCallbacks )

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

{
	'tag1': callback1,
	'tag2': callback2,
	'tag3': callback3,
	...
}

tagx are the event tag as defined in data-xdh-onevent(s) HTML tags, and callbackx, 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.

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

It takes no parameter.

popTag()

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

pushTag( name );

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

putAttribute( name, value );

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

putValue( name );

Set the string value as value for the current tag.

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.

Takes no parameter.

alert(message[,callback])

Displays an alert box with the string message as message.

confirm(message[,callback])

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(id[,callback])

Gives the focus to element of id id (string).

getAttribute(id,name[,callback])

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(id,name[,callback])

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

setAttribute(id,name,value[,callback])

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

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 ids (the content of the id attribute from HTML tags).

idsAndClasses must have following form:

{
	'id1': 'class1',
	'id2': 'class2',
	'id3': 'class3',
	...
}

addClass(id,class[,callback])

addClasses(idsAndClasses[,callback])

removeClass(id,class[,callback])

removeClasses(idsAndClasses[,callback])

toggleClass(id,class[,callback])

toggleClasses(idsAndClasses[,callback])

getContent(id[,callback])

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

getContents(ids[,callback])

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(id,value[,callback])

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

setContents(idsAndValues[,callback])

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

idsAndValues must have following form:

{
	'id1': 'value1',
	'id2': 'value2',
	'id3': 'value3',
	...
}

idx is the id as set as value for the id attribute of the concerned HTML tag, and valuex the string corresponding to the content.

setLayout(id,tree,xslFilename[,callback])

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.

getProperty(id,name[,callback])

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(id,name,value[,callback])

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

dressWidgets(id[,callback])

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