User Guide

Introduction

Assumed knowledge

To read this guide and get started with XBLUI you should have a basic understanding of HTML, XML and CSS.

For advanced usage you will need to know Javascript and the DOM.

Examples in this guide are for illustration only, and are not appropriate for the open web without validation. In particular, HTML examples do not include a DOCTYPE statement, and while they use some XHTML-compatible features - lower-case tags and " />" tag-endings on empty elements - they are not intended to be served as XHTML.

Additional Resources

The XML Binding Language (XBL) 2.0 specification and XBL 2.0 Primer give more details on XBL which is the base for XBLUI. Note that XBLUI doesn't provide all the features detailed in the XBL specification.

The Accessible Rich Internet Applications (WAI-ARIA) 1.0 specification and WAI-ARIA Primer introduce the concept of roles to add semantic value to HTML elements and improve accessibility. The nature of ARIA roles is similar to that of XBLUI bindings in that they apply to a single element and, in some cases, rely on interaction with roles / bindings applied to other elements.

ARIA roles and XBLUI bindings are also complementary since roles add semantic value but do not impact behavior whereas bindings handle behavior only. In fact, many XBLUI bindings match ARIA roles and XBLUI could frequently provide scripted behavior for an ARIA enhanced web-page without having to customise bindings.

The Web Forms 2.0 specification is a proposed extension to HTML Forms. Many of the HTML input element enhancements are available as XBLUI bindings.

Warnings

Work in progress

• Hasn't been rigorously tested
• Might not play nice - XBLUI hasn't been used with other Javascript libraries and may not work well or at all

TODO: What sort of libraries might complement XBLUI? Canvas? I/O? Math & String processing?

Doesn't cure CSS pain

• CSS bugs aren't fixed
• No built-in themes
• Some XBLUI enhancements are designed to interact with your CSS

Partial implementation of XBL

Besides the inherent limitations of current browsers, the major deficiencies of the XBL implementation are, in order of importance:

• XBL Templates and shadow content aren't implemented.
• Dynamic modification of HTML isn't fully supported. Specifically, XBL bindings aren't updated if attributes (including pseudo-attributes) change or if the position of the element in the document changes.
• xbl processing-instructions are only registered for XHTML documents, not for HTML documents
• loadBindingDocument() is not implemented
• XBL documents can't be modified
• Default action handlers aren't registered

XBLUI logs warning messages for XBL elements and attributes that it doesn't implement.

There are also some non-standard extensions provided by XBLUI:

• XBL binding documents may be included with <link> or <style> elements, similar to including CSS.
• cross-browser (but non-standard) logging

The alternate method for including XBL is essential, so some change to your web-page will be required when native XBL implementations become available (unless the extension is incorporated into the standard).

Principles of use

Progressive Enhancement

In general you should follow the philosophy of progressive enhancement when you create your pages.

1. Start with basic HTML markup and create pages that are semantically succinct and accessible even when no scripting (or even styling) is available.
2. Use CSS to enhance layout.
3. Use XBLUI to enhance behavior.

Basic Usage

Setup

Enable XBLUI in your web-page by sourcing the XBLUI.js file with a script element within the document's head element.

For example, to include the default version of XBLUI use the following line:

<script src="http://dist.meekostuff.net/XBLUI/default/XBLUI.js"></script>

You can also choose a specific branch, development snapshot or release of XBLUI. For details see the Distribution section of this document.

Binding documents

To apply enhancements or create your own custom enhancements requires a binding document. A binding document is an XML document in the namespace http://www.w3.org/ns/xbl. The root element is a xbl element which contains all the binding elements. An empty binding document will look like this:

<xbl xmlns="http://www.w3.org/ns/xbl">
</xbl>

Including binding documents

Binding documents are included into your web-page in much the same way as CSS documents are. You may reference the URL of the document with a link element, like this:

<link rel="bindings" type="application/xml" href="..." />

Or you can include the document inline by wrapping it inside a style element like this:

<style type="application/xml">
 <xbl xmlns="http://www.w3.org/ns/xbl">
 ...
 </xbl>
</style>

Note: This is the HTML document equivalent of an XBL tree in a XHTML document.

For both methods specifying the type attribute as "application/xml" is essential, and for the link element the rel attribute must be "bindings".

Applying enhancements

To apply enhancements to your web-page you add binding elements to the binding document. Each binding specifies:

• an element attribute which contains a CSS selector to identify targets for the enhancement
• an extends attribute which contains a URL identifying the enhancement to apply

For example, to specify that all elements of the form <input type="number"> should behave as in the Web Forms 2 specification, add a binding element like this:

<binding 
 element="input[type=text]"
 extends="http://dist.meekostuff.net/XBLUI/default/WF2.xml#WF2NumberInput"/>

The XBL specification also permits attaching bindings to elements with the addBinding() method and with the binding style property in CSS documents. This implementation doesn't support these techniques.

Advanced Topics

Custom enhancements

Distribution

The default version of XBLUI is always the most recent stable release. Generally this is what you want to use, but if you require more stability or would like to try features from the latest experimental snapshot then you can switch to a specific version simply by changing the path of the XBLUI.js file you include.

Firstly you need to understand how XBLUI branch, release and snapshot versions are identified.

XBLUI branches are represented by two numbers, e.g. 1.0, 1.1, 1.2. Even numbered branches are stable and odd numbered branches are experimental.

Stable releases are identified by three numbers, e.g. 1.0.1, 1.2.3 where the first two numbers represent the branch and the third number is the release number for that branch. Releases are always taken from stable branches and are located in the release tree of the XBLUI project.

Pre-release and experimental snapshots of the code are identified by a code of the form A.B.xD, where A and B are numbers represent the branch, x is a literal "x", and D is a build number. Snapshots are found in the snapshot tree.

As previously stated, the default version of XBLUI is the most recent stable release. Branches also have default releases, which are the same as the most recent stable release from the branch. They are identified by the the branch's two number representation, and are located in the release tree. Branches also have default snapshots, which are identified by a code of the form A.B.x and are located in the snapshot tree.

XBLUI releases are available from http://dist.meekostuff.net/XBLUI. The distribution tree looks like this:

• XBLUI
  • release
    • 1.2.0
    • 1.2.1
    • 1.2.0
    • 1.2.1
  • snapshots
    • 1.1.x.0
    • 1.1.x.1
    • 1.1-daily [ 1.1 branch default snapshot ]
    • 1.2.x.0
    • 1.2.x.1
    • 1.2-daily [ 1.2 branch default snapshot ]
  • default [ default release ]
  • 1.1-default [ 1.1 branch default snapshot ]
  • 1.2-default [ 1.2 branch default release ]

A XBLUI release directory has the following contents:

Filename	Description
libXBL.js	The XBL engine (requires a co-operating DOM library)
XBL.js	The XBL engine + SLAB library (works stand-alone)
UI.xml	XBL document with all UI enhancements
UI.js	Implementations for UI enhancements
WF2.xml	XBL document which attaches WebForms2 enhancements to elements as per the specification
libXBLUI.js	libXBL.js + prefetched UI.xml, UI.js, WF2.xml (requires a co-operating DOM library)
XBLUI.js	XBL.js + prefetched UI.xml, UI.js, WF2.xml (works stand-alone)

Typically you would include XBLUI.js which pre-caches the other resources. In this case the default location for XBL documents - e.g. http://dist.meekostuff.net/XBLUI/default/UI.xml - is redirected to a pre-cached copy of the file in the release directory.

This means that switching from the default XBLUI to a specific version only requires changing the script location while all XBL document references remain the same.