JSignage:JQuery port to the uDom
From SpinetiX Support Wiki
Introduction
The jSignage library includes a port of the popular jQuery, thus making jSignage compatible with HTML5 browsers, as well as embedded and mobile SVG players. jQuery is a JavaScript library used for HTML documents and because not everything that works for HTML also apply to SVG, only some parts of it were adapted and ported on the SVG Tiny 1.2 uDOM within jSignage, more specifically those parts referring to:
- DOM manipulation
- Interactive events
- AJAX
At the time of writing, jQuery v1.5.1 and v1.11.0 libraries were used as base for the port to uDOM. Some of the differences between jSignage and jQuery are listed below; the list is not exhaustive and things might be missing.
DOM manipulation
The basic programming pattern in jSignage is the same as in jQuery:
- Select some elements from the SVG document and wrap them in a jSignage object
- Call jSignage methods on this object to apply some changes to the elements you just selected.
Most of the time, only one element is selected.
Example 1: Select the element whose xml id is 'swan' using the jSignage constructor with a filter expression, then change its fill paint attribute to black:
var swan = jSignage('#swan');
swan.attr( 'fill', 'black' );
Example 2: This can be rewritten using '$' sign in place of 'jSignage' which is defined as a handy shortcut:
var swan = $('#swan');
swan.attr( 'fill', 'black' );
Example 3: This example can be made more compact by using the $ object directly without first assigning it to a variable:
$('#swan').attr( 'fill', 'black' );
Selectors
The different types of selectors supported are:
-
$('svg')
selects the top level svg element in the SVG document. -
$('#id')
is used to select an element by its id in the SVG document. -
$('name')
is used to select all elements with the given name in the SVG documents. -
$('#id', context)
is used to select an element by its id in the context subtree (which is equivalent to$(context).find('#id');
). -
$('name', context)
selects all elements with the given name inside a subtree. -
$('<...>')
creates a wrapper for a fragment given by its svg code in a string.
Examples
To hide all the images in the document:
$('image').attr( 'display', 'none' );
To create a rectangle element, set some attributes for it and append it to the document:
var r = $('<rect/>');
r.attr( { x: 0, y: 0, width: 1280, height: 720, fill: '#ffbbbb' } );
$('svg').append(r);
Note that the $.createElement()
would be the preferred way do this as it combines both operations:
var r = $.createElement( 'rect', { x: 0, y: 0, width: 1280, height: 720, fill: '#ffbbbb' } );
Accessing raw XML elements
Content generation is typically done at the layer level using layer methods and constructors. To work with raw XML data, the jSignage library provides the following raw XML editing methods:
-
.attr(attributeName)
- Returns the value of an attribute on the first selected element. If the element does not have an attribute with such name,
undefined
is returned. -
$('#radius').text( "Current radius: " + $('#circle').attr( 'r' ) );
- Returns the value of an attribute on the first selected element. If the element does not have an attribute with such name,
-
.attr(attributeName, value)
- Set the value of an attribute on every selected element.
-
$('#circle').attr( 'r', 50 );
-
.attr({ ... })
- Set the values of multiple attributes given by a map with key/value pairs on every selected element.
-
$('#ellipse').attr( { rx: 10, ry: 20 } );
-
.text()
- Returns the combined (unformatted) text content of the selected elements.
-
alert( 'Title: ' + $('#title').text() );
-
.text(val)
- Sets the text content of every selected element, erasing any other text content and child elements. If the target element is a
<text>
or a<textArea>
, it is possible to use text with formatting, created by$.tspan()
or$.tbreak()
. -
$('#title').text( "Breaking News" );
- Sets the text content of every selected element, erasing any other text content and child elements. If the target element is a
Note: The attribute names must be provided as lowercase since they are case-sensitive.
Traversing the tree
$('#id')
is the preferred way to locate an element in the SVG tree as it is the quickest. Use the following methods to work over the children of an element and to navigate the XML tree.
-
.children()
- Get the children of the selected element(s).
-
.each( function(index) )
- Iterate over the selected elements executing a funtion of each one. The keyword
this
inside the function refers to the element.
- Iterate over the selected elements executing a funtion of each one. The keyword
-
.next()
- Get the next sibling of each selected element.
-
.parent()
- Get the parent of each selected element.
-
.prev()
- Get the immediately preceding sibling of each selected element.
For example, this will display the text of each child elements in a table with the row number.
$('#table').children().each( function(index) {
alert( index + ':' + $(this).text() );
} );
Working with fragments
-
.append(content)
- Add content as a new child element after all exisiting children. If content is a layer, it will be displayed on top of the other layers.
-
.after(content)
- Insert content after each selected element. Content is inserted at the same level, whereas
append
insert content as a child.
- Insert content after each selected element. Content is inserted at the same level, whereas
-
.appendTo(selector)
- Add elements to targets matching the selector.
-
.before(content)
- Insert content before each selected element.
-
.clone()
- Returns a deep copy of the selection.
-
$.createElement(name, { ... })
- Creates an element with the specified attributes. Returns a jSignage object.
-
var r = $.createElement( 'rect', { x: 0, y: 0, width: 1280, height: 720, fill: '#ffbbbb' } );
-
.insertAfter(selector)
- Insert elements after each target matching the selector.
-
.insertBefore(selector)
- Insert elements before each target matching the selector.
-
.remove()
- Remove the selected elements.
-
.replaceWith(content)
- Replace every selected element with the same content.
-
.prepend(content)
- Add content as a new child before all existing children. If content is a layer, it will be displayed below the other layers.
-
.prependTo(selector)
- Add elements to targets matching the selector.
-
.wrap(svg)
- Wrap elements inside a new element.
Interactive events
The jSignage library provides both high-level interactive layers (multi-page, carousel, pop-up, etc.) and low-level interactive event functions (click, keydown, textInput, etc.) to make it easy to build interactive applications in SVG.
AJAX
The following Ajax methods are implemented in jSignage:
-
$.ajax( url, [settings] )
- Low-level interface with full control over HTTP operations. Note that only the GET and POST HTTP methods are supported by the SVG Tiny 1.2 µDOM.
-
$.get( url, [data], success( data,textStatus ), [dataType] )
- Load data from the server using an HTTP GET request.
-
$.getJSON( url,[data], success( data, textStatus ) )
- Load JSON-encoded data from the server using an HTTP GET request.
-
$.getAndParseFeed( dataSourceObject, callback, useGetURL )
- Load data from the server using an HTTP GET request and then parse the feed data.
-
$.post( url, [data], success( data, textStatus ), [dataType] )
- Load data from the server using an HTTP POST request.
-
$.setGetURLFlags( flags )
Examples
Request an RSS feed
Request an RSS feed and parse it using parseRSS:
$.get(
'http://rss.news.yahoo.com/rss/world',
function( data ) {
var news = $.parseRSS( data );
...
},
'text'
);
Notice that you must use set the dataType
parameter to 'text'
in order to prevent the feed from being parsed to XML as a result of auto-detection.
Query a database
Query a database via a PHP script located on the server and returning the data as JSON:
$.getJSON(
'http://Path_to_File_Location/db.php',
{ table: 'prices', type: 'coffee', subtype: 'latte' },
function( response ) {
$('#price').clearText().tspan( response.price );
}
}
To set / update a Shared Variable via RPC, an AJAX POST call to http://HMP_address/rpc/
can be used:
$.ajax( {
type: "POST", url: "http://HMP_address/rpc", contentType: 'application/json',
data: JSON.stringify( {
method: "webstorage_set", params: [[ { name: "var1", value: "Hello" } ]], id: 1
} )
});
Differences from jQuery
Equivalent methods
- The equivalent of the jQuery
add()
function is the jSignagemerge()
function, because the jSignageadd()
function is used to add a sub-layer to the selected jSignage layer. - The equivalent of the jQuery
end()
function is the jSignagepop()
function, because the jSignageend()
function is used to end a jSignage layer.
Not supported methods
- The jQuery methods that get and set CSS-related properties of elements. See how to create layers with jSignage.
- The jQuery methods for adding animation to a web page. See how to add animation events with jSignage.
- The jQuery methods that handle forms. See how to create interactive content with jSignage.
- The jQuery methods that handle arbitrary data of DOM elements.
- The jQuery .prop() method.