Wednesday, May 30, 2012

What happens after users fill out a form?

Orbeon Forms focuses on making it easy for form authors to create and deploy forms, and for end users to fill out those forms. When you create and deploy a form with Form Builder, you get the URL of a new page for that form. You can point users to that page, so they can fill out the form.
But what happens when users are done filling out the form? There are several ways to setup Orbeon Forms, but we’ll cover here the common use case where you want to have a Submit button that:
  1. Saves the data in a database, per your configuration. (For more details, see which databases Orbeon Forms supports out of the box.)
  2. Takes users to another page.
You can do this by setting the following 3 properties. If you haven’t setup properties before, you might find this overview of properties useful.
<property as="xs:string"  name="oxf.fr.detail.buttons.*.*" value="submit"/>
<property as="xs:string"  name="oxf.fr.detail.submit.buttons.*.*" value="go"/>
<property as="xs:string"  name="oxf.fr.detail.submit.go.uri-xpath.*.*"
                          value="'http://www.your-site.com/form-submitted'"/>
Let’s go through those 3 properties:
  1. The first property defines which buttons are shown on the form; here we only include the Submit button, as this is the one we’re interested in, but you might want to include additional buttons.
  2. The second property configures the dialog that shows upon submission, which you can see in the screenshot below. Here include one button, taking users to a page of your choosing.
  3. The third property defines the page users are taken to. To put a static value, add single quote inside the double quotes as done here. (The value can also be dynamic: you can provide an XPath expression returning a URL, which runs on the data entered by users.)

Dialog upon submission
Dialog upon submission

What if this form is part of a workflow, and that depending on the data users entered, you want to take them to a different page? Then the workflow send button is what you are looking for. To end users, the workflow send button looks like a regular Submit button. But it is one that you can configure to do much more; for instance, it can:
  • Optionally, generate a PDF of the form, with the data entered by users.
  • Optionally, send out an email, with the XML data and/or the PDF.
  • Optionally, store the XML data and/or the PDF in Alfresco.
  • Take the user to a page, either sending the XML data or the PDF to that page.
The page mentioned in this last step is one you provide. That page receives an HTTP POST with the data entered by users, so you can implement it outside of Orbeon Forms using the technology of your choice (servlet, PHP…). Maybe based on the information entered by users, you can implement it to direct users to the next step in their workflow, which may involve filling out another form. For more details, see the documentation for the workflow send button.

Wednesday, May 23, 2012

Orbeon Forms 4.0 M1

Today we released Orbeon Forms 4.0 M1 (Milestone 1). As the name implies, this is not a final release, but a release aimed at people who want to have a preview of what's going to be in the upcoming 4.0 release and, hopefully, send us some feedback.

Most features planned for 4.0 are in, including:
  • Form Builder
    • repeats
    • nested sections
    • live XBL components
    • improved and more responsive editor
    • custom XML (PE only)
  • Form Runner
    • improved Liferay support (PE only)
  • Tons of bug-fixes and improvements!
What's not in it?
You can download the builds using these links:
Don't forget to grab a trial license for the PE version.

Also check the release notes for 4.0, which are a work in progress.

Please send feedback preferably to the ops-users list or via twitter (if short!), or feel free to comment on this blog entry if appropriate.

Tuesday, May 22, 2012

Run modes

Recently, we implemented support for run modes in Orbeon Forms.

The idea is not new and it comes down to this: sometimes you want to run Orbeon Forms with development settings, and sometimes with production settings.

So far, to achieve this, you had to play with your properties-local.xml file, either commenting and uncommenting properties, or maybe switching between property files.

Now, you can simply change your run mode in web.xml. You can still use the good old properties-local.xml, which impacts all modes, but you can also use the new properties-local-prod.xml and properties-local-dev.xml, which are used depending on the mode.

Orbeon Forms also comes out of the box with slightly different settings depending on the run mode, including:

  • whether exceptions are shown to the user
  • whether JavaScript and CSS resources are combined and minimized

Oh, and the feature is implemented in a simple and beautiful way by selecting different internal property files, which in turn include different secondary files. That's just a few lines of code, the rest being toying with property files.

We hope you find this useful! For the specifics, see the documentation.

Thursday, May 17, 2012

Forms access control with Form Builder

Who can do what with Form Builder? You guessed it: in this post, we’ll discuss access control, as it relates to Form Builder. More specifically, that question has two facets:
  1. When it comes to people using Form Builder to create or edit forms, often referred to as form authors, who can create or edit which form?
  2. When it comes to the end-users of the forms created with Form Builder, who can access which form?
In both cases:
  • Permissions are role-based: access isn’t given based on usernames, but on roles. For instance, for Form Builder permissions (the first case above), you could be defining that only users with the role finance can access forms in the app payroll.
  • Users and roles are not defined in Form Builder or Orbeon Forms. Instead, you configure the container (say, Tomcat), in which you’re running Orbeon to leverage your existing authentication system, say users and roles defined in LDAP. And if you don’t already have users and roles defined somewhere, Tomcat lets you define them is a simple XML file (tomcat-users.xml).
Let’s get back to the two types of access control mentioned earlier:
  1. Access control to Form Builder itself is done through a property file: form-builder-permissions.xml. There, you can define which roles have access to which apps, and which forms. This is most often used to partition your forms into group, and give people access to a specific group. For instance, a local government might have different departments, say police, social services, parks, housing… and would like to keep the forms for each department separate. So they will create an app and a role for each department, and will define in form-builder-permissions.xml that form authors can only access forms of a given app of they have the corresponding role; say, they can only access forms in the social-services app if they have the social-services role. For more on this, see how to define access control to specific apps/forms in Form Builder.
  2. Access control to published forms is a new feature of the upcoming Orbeon Forms 4.0, but you can already give it a try today using a nightly build. With this new feature, you can, as a form author, define who can access the form you’re editing right from Form Builder. You do so through a dialog, as shown in the screenshot below. For more on this, see how to define access control for deployed forms with Orbeon Forms 4.0.



Tuesday, May 8, 2012

More XForms bindings

Photo by preservationgal
In a previous post, we covered the basics of controls bindings, where XPath expressions are used to bind a control to XML elements. But it's not always that simple, is it? So now is the time to cover all the cases you can encounter with binding expressions.

First, there is another difference with HTML worth pointing to: if the XML node does not exist, the control becomes non-functional (non-relevant), and appears hidden (or in some implementations grayed out). So it's important to create an instance (XML document) which contains all the elements and attributes your controls are pointing to, unless you want to hide them on purpose.

So now we have covered binding expressions pointing to a single element, or pointing to nothing. Are there other possibilities? Well yes!

1. Attributes

Obviously, a control can bind to an XML attribute too:
<xforms:input ref="@tag">
Here the input field reads and writes to a "tag" attribute:

2. Multiple nodes

What if the XPath expression returns more than one node? For example, assuming the document from the previous post, the following would return two elements:
<xforms:input ref="instance('zoo')/animal/nickname">
XForms solves this by saying that you just take the first node returned. Except, that is, for bindings that support multiple nodes. The only control which supports this is <xforms:repeat> (but other XForms constructs support multiple nodes: <xforms:itemset><xforms:bind><xforms:header>, and the <xforms:insert> and<xforms:delete> actions.

3. Atomic values

What if the binding expression returns something other than a node, like a number? In XForms 1.1, this was disallowed and the binding would throw an error. XForms 2 changes this because XPath 2 deals more generally with items, which can be nodes but also atomic values. Also, and maybe more importantly, there are some interesting use cases to bind to atomic values, in particular with <xforms:repeat> and <xforms:itemset>.

So XForms 2 says that it's ok to bind to atomic values. For example this will work:
<xforms:input ref="42">
However, the input control appears read-only, because in XPath it doesn't make sense to write to an atomic value.

In general, it's not very useful to bind controls such as <xforms:input> to atomic values. It's ok for <xforms:output>, although that control already had a value attribute for that purpose. Where this really shines is for repeats or itemsets:
<xforms:repeat ref="1 to 10">
  <xforms:output value="."/><hr/>
</forms:repeat>
Then there are a couple of  things you probably shouldn't do:

1. Binding to text nodes
<xforms:input ref="instance('zoo')/animal/nickname/text()">
This is allowed but discouraged. Why? First, there might not be a text node, and then the control won't show. Second, if there is one, and the user enters a blank string, the text node will go away (because XForms and other specifications like the XPath data model say you can't have empty text nodes), and the control will hide. Not very useful!


2. Comment nodes and processing instruction nodes
<xforms:input ref="comment()">
<xforms:input ref="processing-instruction()">
XForms doesn't prevent you from doing this, but not all implementations might support it, and XForms doesn't say what must happen. Since recently, Orbeon Forms allows you do do that, and the control will read and write the comment text or the processing instruction value. It's unlikely you will need that, and it's not guaranteed to be portable between implementations, but at least XForms allows it and if you need it you'll be a happy camper!

Finally, there are things that are outright prohibited:


1. Binding to elements that contain other elements
<xforms:input ref="instance('zoo')/animal">
This is not allowed. Why? Probably because there are a few ways this could be understood. For example, the control could read and write text at the beginning of the element, or at the end. Or, it could read the XPath string value, but overwrite everything when writing back! Also, XML Schema doesn't validate values in such elements with so-called complex content. To make things clearer, XForms says there that if you do that, the binding will throw an error.

2. Binding to a document node
<xforms:input ref="instance('zoo')/..">
<xforms:input ref="instance('zoo')/root()">
This is not allowed. Why? Because in XML it's not possible to have non-blank character data at the top of an XML document, so the control wouldn't be able to write data there. Here again, the binding will throw an error.

In both these prohibited cases, Orbeon Forms now uses its new error handling behavior.

Please let us know if we missed any aspects of control bindings!

Wednesday, May 2, 2012

How XForms controls bind to data

Photo by Philippa Willitts
Take the most basic HTML input field:
<input name="nickname">
Then, compare to the equivalent XForms:
<xforms:input ref="nickname">
Both look pretty much the same, right? Well yes, but only on the surface!

In HTML, you just specify a name, which is later used by form submission (or to query form fields). In XForms, on the other hand, the ref attribute holds an XPath expression pointing to zero, one or more XML element or attribute nodes.

Often, XPath binding expressions are very simple and look just like a plain name, like above, where the expression in fact says "under the curent XPath context, point to the XML element called nickname".

Where are those XML elements defined? In XML documents (called instances in XForms) defined in the XForms model. For example:
<xforms:model>
    <xforms:instance>
        <animal>
            <nickname>Batman</nickname>
        </animal>
    </xforms:instance>
</xforms:model>
Because the expressions are XPath, they can be more fancy when needed. In fact they allow you to point to any node in an instance. Consider the more complex:
<xforms:instance id="zoo">
    <zoo>
        <animal tag="42">
            <nickname>Thika</nickname>
        </animal >
        <animal tag="43">
            <nickname>Iringa</nickname>
        </animal >
    </zoo>
</xforms:instance>
Here we point to a very specific nickname element:
<xforms:input ref="instance('zoo')/animal[@tag = '42']/nickname">
Now once your control points to a node, what does it do? It is pretty simple:
  1. When the user enters data into the field, the data is written to the XML document.
  2. If the data changes in the XML document, the control is updated with that data.
It's a nice example of the MVC pattern, where the model is made of hierarchical XML documents, the view is made of controls, and where data flows in both directions between model and view.

In a subsequent post we cover in more details what kind of things you can bind controls to!