Orbeon Forms FAQ‎ > ‎

FAQ - 3. XForms

What is XForms?

W3C XForms is a standard, markup-based, declarative, XML- and HTML-friendly user interface technology particularly adapted to building complex forms. XForms makes it easy to build dynamic user interfaces able to talk to XML services.

XForms 1.0 is a W3C Recommendation since October 2003, and XForms 1.1 is a recommendation since October 2009. The XForms Working Group is already embarking on XForms 2.0! Please visit the Forms Working Group for more information about XForms right from W3C.

XForms aims at improve upon HTML forms, but it is not strictly tied to HTML. The main goal of XForms is to make forms design easier, allowing the developer to write less client-side scripting (or none at all), and less server-side code thanks to a feature-rich declarative approach.

Benefits of XForms include:

  • Clear separation between data captured and presentation (separation of concerns)
  • Flexible, structured XML-based data model: define your data model as an XML document, then create forms accessing the data
  • Built-in facilities for validation and data integrity based on XML Schema and/or assertions
  • Declarative approach requiring less / no scripting at all, in particular thanks to declarative events and actions
  • Ease of internationalization
  • Support for a variety of devices
  • W3C standard
  • Not tied to a particular platform or language such as Java or .NET

See also the Orbeon Forms XForms Introduction section.

How much of the XForms specification does Orbeon Forms support?

The Orbeon Forms implementation is based on the W3C XForms 1.1 Candidate Recommendation. The XForms engine in Orbeon Forms is close to supporting all of the XForms 1.1 specification. For more detailed information on what features are supported in the latest version of Orbeon Forms, see the XForms Compliance section of the documentation.

Orbeon Forms also supports a large number of extensions such as XPath 2.0 support, variables, XBL components, and much more.

I hear that XForms is not well supported in web browsers. This is a problem, right?

See also our February 2012 blog post Does XForms need to be implemented natively in browsers?.

No, this is not a problem at all, because XForms runs great on the server, in the same way that other web applications technologies like PHP, ASP, JavaServer Faces or Ruby run on the server.

You run XForms on the server by installing the Orbeon Forms XForms engine on your server. The XForms engine translates your XForms pages to HTML, CSS and JavaScript that your browser understands. Your web browser sees a regular Ajax application, but as a developer you write standard XForms instead of JavaScript!

Running XForms on the server has even several benefits over running it in the client:

  • Users don't have to upgrade their web browser or install plugins or extensions. You can use and develop with XForms today and target over 90% of the users on the web.

  • The data used by your XForms application remains safely on the server. With client-side implementations, on the other hand, you have to be very careful not to send confidential information to the XForms engine, as that information may be seen by the user.

  • You can upgrade your XForms implementation at a single location on your server instead of waiting for users to upgrade their browsers when bugs are fixed or new features are implemented.

What is a server-side, Ajax-based XForms implementation?

Historically, the XForms specification assumed that XForms was implemented on the client-side, natively within a web browser. But as discussed here, XForms-based applications can use server-side Ajax-based implementations that share XForms processing between server-side code and client-side code and rely on Ajax technology.

Orbeon Forms features such an Ajax-based implementation and implements the XForms specification partly on the server (in Java), partly on the client (in JavaScript). Client and server communicate through Ajax requests. The client is fairly "dumb" compared to the server, which implements most of the XForms intelligence.

The Orbeon Forms XForms processor translates your forms described in terms of the XForms specification into HTML, CSS and JavaScript code understood by your web browser. The following diagram shows a high-level overview of the architecture of an Ajax-based XForms implementation:

We believe that having an implementation of XForms with both a server-side and a client-side component, like Orbeon Forms, has a number of benefits, and in some situations, we think it is even essential.

The most important benefit is enhanced security. With Orbeon Forms, only the field values that need to be shown to users are sent to the browser, not your complete data model, as would be the case with a client-side implementation. If a field is readonly or has some other constraint placed on it, then that constraint is also checked on the server, not just on the client as would be the case with a client-side implementation. For selection fields, such as check boxes, radio buttons, and drop-downs, the server also checks that the selected value was indeed in the original list, and that it wasn't inserted in the list by a user trying to hack the system. If your form is calling REST or web services, those calls are made from the server. This prevents people from trying to hack the services by sending unexpected data, and your services can stay behind a firewall.

In some cases, Orbeon Forms, with its implementation split between the client and server, allows for better performance. For instance, this is the case when your form uses fairly large lookup tables, as any piece of data which supports the logic of your form but which isn't directly displayed to users doesn't need to be sent to the browser.

Do I need to use XForms to build forms?

It is not a requirement to use XForms with Orbeon Forms. It is possible to generate HTML form elements and to examine request parameters manually. We recommend however using XForms whenever possible, because it provides an elegant abstraction that greatly simplifies form handling, which is the point of Orbeon Forms.

How can I perform a file upload?

I get errors when I use the XPath if() function in Orbeon Forms. What's wrong?

This happens because Orbeon Forms uses XPath 2.0 expressions instead of XPath 1.0 expressions as mandated by XForms 1.0 and XForms 1.1. This allows much greater flexibility in the expressions you can use in Orbeon Forms (and once you have tasted XPath 2.0, you can't go back to XPath 1.0!). For more information, see Note About XPath 2.0 Expressions.

Can I mix and match XForms and JSP?

Yes, you can use JSP alongside XForms, in the same web application or in a separate web application.

You can use JSP to produce pages containing XForms or other content to be processed by Orbeon Forms. See Using the Orbeon Forms XForms Engine with Java Applications.

If you feel more advanced, you can also "call" JSP pages with HTML links, or by redirecting or forwarding using the Redirect processor. You can also use the Servlet Include generator to include the content produced by a JSP.

Can I mix and match XForms and JavaServer Faces?

It all depends on what you are trying to achieve with this integration. Technically, you can write a page in JSP + JSF that produces XForms, which can then be processed by the Orbeon Forms XForms engine using a Servlet filter approach. But mixing JSF components with XForms components can cause difficulties related to the way each component set handles form submissions and state. In particular:

  • If you use non-AJAX JSF components, the standard JSF components (buttons, etc.) will perform HTML form submissions to the server, which then reevaluates the JSF component tree to produce an updated page that is then sent back to the client. If you do this and your page contains XForms components as well, you will lose the state of your XForms controls when the page reloads.

  • If you use AJAX JSF components (we have no experience whatsoever with those), there could be conflicts due to the JavaScript libraries those components use vs. the ones we use in Orbeon Forms.

Feel free to experiment with JSF and XForms together, but at the moment we recommend using either JSF or XForms exclusively in a given page. However you can very well use JSF for some pages, and XForms for other pages within the same application.

Orbeon wrote an article on TheServerSide in 2003 on using XSLT to style JSF. This approach can still be pursued, but the XML renderkit has not been maintained and we no longer support it in Orbeon Forms.

Can I run XForms within JSR-168/JSR-286 portlets?

See: Deploying Orbeon Forms as a Portlet into a JSR-286 Portal and Form Runner Liferay Proxy Portlet Guide.

The great thing about Orbeon Forms and portlets is that there is very little difference if any between writing an application working in a portlet vs. a servlet. In fact, most of the Orbeon Forms XForms examples work unmodified as portlets. You can use some particularities of portlets, like preferences, and you have to be careful about paths to serve resources, but otherwise portlets are transparent to the developer. This contrasts with many other web platforms.

In other words, Orbeon Forms gives you the flexibility to write an application that works in standalone mode, and allows you to migrate to a portlet environment at minimal cost. This contrasts with many other web application technologies, which sometimes require you to rewrite your application entirely to fit within a portlet.

What web browsers does the XForms engine support?

See the latest release notes for Orbeon Forms: Orbeon Forms 3.9.

How do I design forms in Orbeon Forms?

Orbeon Form Builder is Orbeon Forms's visual form designer. You can also create forms by writing XHTML pages that contain embedded XForms markup.

Orbeon Forms comes with a tutorial which explains step by step how to create your first forms. We recommend you also look at the other sample Orbeon Forms applications that you find under your WAR file's WEB-INF/resources/apps directory.

Also note that Orbeon provides services around Orbeon Forms, including training. Please visit our support page for more information.

What visual tool / graphical designer do you recommend for XForms?

Orbeon Form Builder.

Can I use JavaScript to modify the page DOM and add or remove XForms controls?

No, because your JavaScript code will run within the web browser, which doesn't know anything about XForms controls. All the web browser sees is an HTML DOM (Document Object Model), which represents the HTML document produced by Orbeon Forms when it transforms XForms+XHTML into plain HTML. That DOM does not include in XForms elements.

Remember, the Orbeon XForms implementation works server-side in order to support currently deployed browsers. It achieves this by sending to web browsers not XForms (which they wouldn't understand), but HTML, JavaScript, and CSS (which they do understand).

If you just want to conditionally include XForms controls when the page is loaded, you can use an XSLT page view. If you want to control the showing or hiding of XForms controls after the page is loaded, you can use XForms relevance or switch/case. Currently, the only thing you can't do is dynamically add and remove trees of controls in a running XForms page.

I just want to use Orbeon Forms's XForms engine. Can I do that?

In addition to the XForms engine, Orbeon Forms comes with an XML pipeline engine and a Page Flow Controller (PFC). While these additional building blocks are often useful to put together your form-based applications, you may not have a need for them.

The good news is that Orbeon Forms is very configurable and you are not forced to use XML pipelines or the PFC. Users have been successfully using the Orbeon Forms XForms engine with JSP/Struts or PHP. Please visit Using the Orbeon Forms XForms Engine with Java Applications for more details. Post additional questions to the ops-users mailing-list.

What is the matter about this /xforms-server-submit I am seeing?


As of Orbeon Forms 3.7, this is partially addressed as the submissions are now done to the URL of the current page (see the RFE). This does not solve the issue entirely, but it makes the URLs look nicer to the user. In the future, we hope to improve on this (see the RFE).

Remember that the Orbeon Forms XForms engine runs for the most part on the server. This means that when you perform an XForms submission that uses HTTP, that submission usually originates from the server, not from the client. Consider the following submission:

<xforms:submission ref="instance('my-instance')" method="post" action="http://my.example.com/service" replace="all"/>

This is how this submission is processed.

  • The server part of Orbeon Forms tells the Orbeon Forms client (in your web browser) to perform a POST submission at the special Orbeon Forms URL /xforms-server-submit.

  • Orbeon Forms responds to that URL and issues an HTTP POST to http://my.example.com/service.

  • Orbeon Forms forwards the result of the HTTP request to your web browser.

This is why you see /xforms-server-submit in URL bar.

Ideally, you would like to see http://my.example.com/service appear in your URL bar, but technically this is hard to achieve for the following reasons:

  • The only way to POST XML documents from a browser is to use the XmlHttpRequest object, and if you do that, you cannot easily, if at all, implement the replace="all" functionality.

  • There are limitations as to what URLs your browser can talk to from a given page, for security reasons (this is known as cross-domain requests).

In short we don't believe we will solve this problem perfectly in the short-term, unless we get clever suggestions as to how this can be done.

Note that "nice" client-side URLs are already used in the following cases:

  • When using the method="get" method with replace="all":

    <xforms:submission ref="instance('my-instance')" method="get" action="http://my.example.com/service" replace="all"/>

    Note that this assumes the following property is set in properties.xml:

    <property as="xs:boolean" name="oxf.xforms.optimize-get-all" value="true"/>
  • When using xforms:load instead of xforms:submission:

    <xforms:load resource="http://my.example.com/service"/>

Finally, note that performing submission from the server offers certain advantages, including solving cross-domain access.

How does Web Forms 2.0 compare with XForms? Does Orbeon plan to implement it?

Web Forms 2.0 is a specification of WHATWG which describes a series of improvements over HTML forms. Since some key WHATWG members have joined the recently revamped HTML Working Group at W3C, there is a strong possibility that Web Forms 2.0 will be integrated (as is or with modifications) into the W3C's upcoming HTML 5 specification.

One of the main goals of Web Forms 2.0 is to be backward compatible with HTML forms. XForms on the other hand is a more radical departure from HTML forms due to its use of XML to store form data, a model-view architecture, and XML events and actions. Web Forms 2.0 does not support an XML data model, XPath, or XML schema validation. The closest Web Forms 2.0 comes to supporting XML is that it allows serializing form data into XML in a submission.

At Orbeon, we do not think that Web Forms 2.0 directly competes with XForms because it does not cover as much ground. We believe that for relatively large forms, an XML data model is absolutely necessary. We also believe that the declarative event and action model used by XForms is a huge benefit to form authors.

But Web Forms 2.0, or an evolution of it as part of HTML 5, could be leveraged by Orbeon Forms as it become supported by browsers.

How do I add my own rich controls to Orbeon Forms?

As of Orbeon Forms 3.7, a component system for Orbeon Forms, based on XBL 2, is in place. For more information, see the developer documentation:

Note that Orbeon Forms already features some rich components such as menus, trees, dialogs, and autocompletion fields, and we plan to add more. All these features were sponsored by customers, so if you have particular needs you may want to consider sponsoring as that may be the quickest way to get your widget in the Orbeon Forms code base.

I am not allowed to run JavaScript in the browser. Is Orbeon Forms a solution for me?

The short answer: yes. As of Orbeon Forms 3.7, the Orbeon Forms XForms engine has two modes:

  • In full mode, the Orbeon Forms XForms engine uses JavaScript on the client. Namely, it uses The Yahoo! User Interface Library (YUI) as a foundation to Orbeon-specific JavaScript code. This mode allows you to leverage the Orbeon Forms XForms engine to the maximum.

  • In noscript mode, the Orbeon Forms XForms engine works without any JavaScript. This allows running simple forms, in particular most forms created with Form Builder.

    This mode has some limitations: dynamic behavior in the user interface is reduced, and the user has to press a "refresh" buttons to perform udates, like with older-style web applications. Also, advanced widgets like dialogs, trees, and menus, are not yet implemented.

For more technical information, visit the Noscript Mode developer documentation.

Can I easily migrate from Orbeon Forms to a native XForms implementation?

We don't believe it is realistic in the short term to migrate entire applications from Orbeon Forms to client-side implementations. There are multiple reasons for this:

  • In our opinion, there is only little chance that all mainstream browsers will implement XForms natively in the short term. Certainly, we doubt that Microsoft will implement XForms. Other browsers require extensions (Firefox) or plugins (Internet Explorer).

    A more promising approach for pure client-side solutions are JavaScript-based implementations, like Ubiquity or XSLTForms.

  • Once JavaScript implementations become mature enough, it remains to be seen how many interoperability issues will arise, in particular related to the level of XForms support (XML Schema validation, for example, is hard to do in JavaScript), extensions available (for example: dialogs, variables, etc.), and styling (CSS).

  • There are big benefits to running XForms on the server. In Orbeon Forms, and in particular in Form Runner, we use XForms as a server-side technology. Applications written with XForms are able to manipulate data on the server that the client must never see, much like you would do in Java, Ruby, or any server-side language. Also, running XForms on the server allows you to produce applications that work with or without script (for accessibility purposes, or for supporting legacy browsers) based on a single definition written in XForms (more information about the noscript mode).

    XForms is only one of the technologies that enable Form Runner and Form Builder. Form Runner provides a full environment to manage forms, including persistence, PDF generation, etc.

This said, for simple XForms-based applications, you can certainly write interoperable XForms that will work both on Orbeon Forms and native or client-side JavaScript implementations. We are very interested in getting your feedback on your experience in this area.