Introduction

---

Getting started

Copying an existing component

The best thing to do is to start looking at existing components:

• If you are working with the Orbeon Forms sources, they are located under:
  
• src/resources-packaged/xbl
• If you are working with a binary distribution:
• unzip orbeon-resources-private.jar
• the components are under the xbl directory
  

The "meat" of most components is in files ending with the .xbl extension.

To create your own component:

• create a new xbl directory under your RESOURCES directory
• create a directory with your company or project name (e.g. acme; Orbeon uses orbeon)
  
• create directory with your new component name (e.g. cool-stuff)
• create a new XBL file with the same name in that directory, e.g. cool-stuff.xbl
• so you should have: xbl/acme/cool-stuff/cool-stuff.xbl

Then:

• copy into your XBL file the content of a simple existing component, like xbl/orbeon/tutorial-simple/tutorial-simple.xbl
• modify the binding rule ("fr|tutorial-simple") into something that matches your component name ("fr|cool-stuff")
• within an XForms page
• declare xmlns:fr="http://orbeon.org/oxf/xml/form-runner"
• use the control with something like: <fr:cool-stuff ref="my-node"/>
• when running your XForms page, you should see an upload field appear!

NOTE: In your own components, you should not use the "fr:" namespace, but instead you should use your own namespace to avoid naming conflicts.

---

Mini-tutorial

Encapsulation

The component system favors a strong encapsulation so that components can be:

• developed in isolation, without knowing the details of the application using them
• used without knowing the details of how they are implemented
  
• in short: reused as much as possible!

The goal is first eased of use and transparency for the form author. This means that sometimes the component author must do a little bit more work!

The default: strong encapsulation

By default, within an <xbl:binding> element, encapsulation is strong: this means that XForms controls, models, and event handlers cannot:

• see ids of the XForms document using the component
• have access to the XPath context outside the component
  

In other words, things behave as if you were working in a new, completely separate XForms document!

If you place models within <xbl:implementation> or <xbl:template>, the same rule that applies in a top-level XForms document apply:

• The default XPath context starts with the root element of the first instance of the first model.
• However, if your component doesn't have a model, then the XPath context is set to an empty document node.
• NOTE: In the future, this might change to being an empty sequence. For implementation-dependent reasons, for now an empty document node had to be used.
  

Why and how to break the encapsulation?

There are cases where a component can live in its own little world. For example, consider a component such as the Twitter Timeline component included with Orbeon Forms: it obtains its data through the Twitter API, and simply displays it. It doesn't need to access data or interact with the XForms document in which it is used (although you could imagine such interactions).

But in other cases, components need access to the outside world! For example, XPath expressions to evaluate within the XPath context in scope where the component is used.

Creating a single-node binding

Here is how you create a single-node binding in an XBL template:


This is what the code does:

• It creates an XForms group within the XBL template.
• It copies, with xbl:attr="..." all the single-node binding attributes present on the tag written by the component user (e.g. <fr:cool-stuff>) : model, context, ref and bind.
• In the case of <fr:cool-stuff ref="my-node, you end up with <xforms:group ref="my-node">.
• If any attribute is not present, it is simply not copied.
• It adds a special attribute, xxbl:scope="outer", to indicate that the evaluation scope for the XPath expressions and ids on that element is the scope outside the component.
  

So what does this get us? A group, within the component, which is bound to an instance data node as indicated by the user of the component.

Now within that group, you might want to access resources, such as controls, instances, etc., which are local to the component again. To achieve this, you use xxbl:scope="innner":


Now one issue with this is: how do you get, from an inner scope, access to something in the outer scope? Typically, you do this with variables:


The variable named binding above:

• Is defined within the inner scope.
• Is evaluated in the outer scope.
  

Presto, this gives you access, within the component's private universe, to the external single-node binding specified by the component user.

NOTE: You notice, based on the example above, that XBL itself doesn't know anything about single-node bindings: instead, you create such bindings using a group, XForms constructs, and XBL extensions.

Adding LHHA elements

Typical XForms controls feature <xforms:label>, <xforms:help>, (shortened to LHHA for "label", "help", "hint", and "alert") etc. You can easily copy the ones specified by the user within the XBL component:


What this does is place the elements within the group. If the user writes:


The result, within the XBL component, will be:


NOTE: <xbl:content> uses a CSS selector notation instead of XPath.

A basic component

You can find the component discussed in this section in the Orbeon Forms distribution:

• XBL: xbl/orbeon/tutorial-input/tutorial-input.xbl
• Example: apps/xforms-sandbox/samples/xbl-tutorial-input.xhtml

A super-simple component template with just one <xforms:input> will look like this:


To complete that component, you must place it within an XBL file, complete with namespace declarations:


In the above:

• <xbl:xbl> is the root element of any XBL file.
• <xbl:binding> determines what kind of elements will trigger the component. Here, we settle on <fr:tutorial-input>.
• Note again the CSS selector notation in the elements attribute, instead of the XPath notation.
  

The Orbeon XBL files are placed undeer the xbl/orbeon directory and in the "fr:" namespace and are automatically included.

However your own XBL files need to be included explicitly in your page, e.g.:

Using local state

You can find the component discussed in this section in the Orbeon Forms distribution:

• XBL: xbl/orbeon/tutorial-davinci/tutorial-davinci.xbl
• Example: apps/xforms-sandbox/samples/xbl-tutorial-davinci.xhtml

Now assume you would like to write a component which stores the string of characters entered by the user but back to front, i.e. reversed. If the user types "Amelia", the string stored in the instance will be "ailemA".

How would you go about this? The binding between an XForms control and instance data is direct: the value entered by the user is stored into the instance as soon as the user moves out of the field, and you can't just write a transformation inbetween. So we need some intermediate state to store the value entered by the user.

To do so, we create a local instance. You can put it under the <xbl:implementation> or <xbl:template> elements in your XBL file:


Here we store a single value, so we just use a single root element in the instance: <value/>.

The local input field just points to the instance within the inner group, instead of pointing to the external single-node binding:


So here, the input field points to the <value> element.

NOTE: You could also write ref=".", which would work because, like at the top-level of an XForms document, the default XPath context is the root element of the first instance in the first model. Using instance() is a bit more explicit.

What is needed now is, when the local value changes, to copy it to the external single-node binding. You do so with an event handler:


What's missing now is to reverse the value:


Finally, the opposite operation is needed: when the component first comes to life, and when the external value changes, the internal value must update:


We use here another nested group bound to the external binding:

• We need to detect not only that the control becomes relevant, but that its value changes. Listening on the group bound to a node achieves this.
• Doing so makes sure that the event handler only listens to change on that particular group, and does not catch events dispatch e.g. to <xforms:input> or other groups.

So here you go: you have a fully working non-trivial component:

Components which copy large amounts of user markup

[TODO: e.g. tabview, which copies data]

[TODO: more tutorial-like content

• XPath resolution
• events used for communication
• model resolution, including xxf:instance()
• template copying elements and attributes
  

]

xxbl:scope in more details

[TODO:

• what are scopes?
  
• xbl:contents
• xxbl:scope=outer, how to override
  
• using XSLT
• id scoping
• XPath scoping
• all models are in inner scope
• except for actions
  
• might be extended in future: http://wiki.orbeon.com/forms/projects/xforms-model-scoping-rules
  
• tip: do not put @id on outer xxforms:group
• xxbl:scope only on XForms elements!
  
• AVTs work based on ancestor scope
  

]

---

XForms models

Placement of local models

A component can have its own set of XForms models, called local models. For each instance of the component, a new copy of the models is made, so that component instances behave completely independently from each other.

With XForms 1.1, the standard convention is to place your models under the <xhtml:head> element (even though some new model scoping rules are being developed for Orbeon Forms). An XBL component does not have an <xhtml:head> element, so Orbeon Forms supports placing models in two places:

• Under the <xbl:implementation> element. In this case, models are identical for all instances of a particular component.
  
• Under the <xbl:template> element. In this case, models can be different depending on the component instance, since the XBL template can parametrize its elements and attributes.

NOTE: In XBL, the purpose of <xbl:implementation> is to place new methods and properties. Orbeon Forms uses XForms as the implementation or "scripting" language of XBL components, so it does not have methods and properties. But models, through events, can implement behavior, so allowing model placement under <xbl:implementation>seems to fit the intent of XBL.

Local model-related events

---

Event handling

---

CSS selectors

The xbl:includes element allows copying elements which are descendant elements from the bound node. The selectors work as if applied to an XML document rooted at the bound node.

Say you have this markup:

The implementation of the fr:inline-input component can copy the nested xforms:label element under a group as follows:



The CSS selection expression above is exactly equivalent to writing in XPath:


Note the difference of notation in XML/XPath and in CSS to refer to qualified element names:

• XML/XPath uses a "colon" character: foo:bar
• CSS uses a "pipe" character: foo|bar
  

Both XPath and CSS are expression languages allowing selecting nodes from XML documents, but they have a quite different syntax!

Now here is a more complex scenario:

You would think that the implementation of the fr:link-select1 component could simply copy the nested xforms:label element as follows:

But this doesn't work properly because the CSS selector xforms|label actually returns all descendant label elements, including the xforms:label element under xforms:itemset.

In this case, you need to use the ">" combinator, which "describes a childhood relationship between two elements". In this case, the left element must represent the bound element:

The CSS selection expression above is exactly equivalent to writing in XPath: