Orbeon Forms (formerly Orbeon PresentationServer (OPS)) is an open source forms solution that handles the complexity of forms typical of the enterprise or government. It is delivered to standard web browsers (including Internet Explorer, Firefox, Safari and Opera) thanks to XForms and Ajax technology, with no need for client-side software or plugins. Orbeon Forms allows you to build fully interactive forms with features that include as-you-type validation, optional and repeated sections, always up-to-date error summaries, PDF output, full internationalization, and controls like auto-completion, tabs, dialogs, trees and menus. Orbeon Forms already supports parts of the XForms 1.1 specification.

Unlike other web application platforms based on Java objects or scripting languages, Orbeon Forms is based on XML documents and XForms. This leads to an architecture perfectly suited for the tasks of capturing, processing, and presenting XML data (in particular form data), and does not require writing any Java, JavaScript or other scripting code at all.

Orbeon Forms is built around a user-friendly Ajax-based XForms engine, which brings W3C XForms to standard browsers, and the XPL engine, a mature, high-performance XML pipeline engine for processing XML data.

Orbeon Forms does contain an XForms engine (also known as an XForms processor), which we refer to as the Orbeon Forms XForms engine. It also contains an XML pipeline engine running the XPL pipeline language, an application controller (the Page Flow Controller or PFC), and built-in components to perform XSLT transformations, database access, and more. Needless to say, Orbeon Forms ships with examples and documentation.

You are free to use Orbeon Forms only for its XForms functionality, but you can also leverage more of Orbeon Forms to build your forms-based application.

No, Orbeon Forms is truly open source and free or charge whether your use it to build open source or commercial applications.

You are free to extend the platform, and you are free to build applications on top of the platform as you please. Note however that if you make changes to the existing Orbeon Forms code, you are bound by the terms of the LGPL license, which requires you to redistribute changes to the open source community when you distribute your application.

Orbeon does offer commercial support for Orbeon Forms. See the information about our support plans.

Renaming a product is not something to be taken lightly. However we feel that:

• Orbeon Forms better reflects the fact that forms have been the main focus of our development efforts since 2004.

• This new face will help potential users understand more easily what the platform can do for them.

• Orbeon Forms is just an easier name to remember!

We are encouraged in this decision by the fact that almost all current users build complex web forms using our Ajax-based XForms engine. The name change also conveys that we plan to keep focusing on form-related capabilities in the future like we have done in the last two years.

It is important to precise the following:

• We are not creating a separate product: Orbeon Forms is simply the new name of Orbeon PresentationServer.

• Other XML technologies like XSLT and XML pipelines remain an important part of the platform.

• And of course, Orbeon Forms remains an open source solution!

In the ObjectWeb CVS repository. This page provides the instructions to retrieve it. You can also browse the repository with your web browser.

Use the orbeon CVS module for Orbeon Forms proper, and the saxon CVS module for the Saxon source code (which sometimes contains fixes against the latest released Saxon).

Yes. You find it on the ObjectWeb site as well, here ordered by descending priority.

Note that we put bugs and requests for enhancement (RFEs) in the same tracker category, and just prefix RFE descriptions with the string "RFE:".

In general, we recommend you do not add bugs or RFEs in the tracker yourself, as we may miss them, and you may introduce duplicates. Please discuss bugs or issues on the Orbeon Forms mailing-list first.

Usually a feature gets implemented in Orbeon Forms when:

• It is very easy to implement, so we just implement it along the way to make everybody happy.

• We need it for a project we are currently working on.

• We have put it on our roadmap and scheduled it because we think it is a crucial feature for Orbeon Forms.

• Somebody sponsors it.

• Somebody sends a patch for it.

We need help on Orbeon Forms by the way, and we definitely appreciate outside contributions. So check out the source code and start hacking away. You can ask your questions on the mailing-list.

OXF was the name of Orbeon Forms before it was open sourced in 2004. For backward compatibility, the string "oxf" still persists in a few places, including:

• As XML namespace prefix for built-in XPL processors.

• As part of built-in XML namespace URIs.

• As a URL scheme for accessing Orbeon Forms resources.

• As a prefix for property names in properties.xml.

• As a prefix for parameter names in web.xml.

• As a package name in the Java source code.

See also I am confused by all those oxf: prefixes. What do they mean?.

OPS stands for Orbeon PresentationServer and was the name of the platform before it was renamed to Orbeon Forms in November 2006. The string "ops" still persists in a few places, including some resource paths, and the name of the Orbeon Forms mailing-list.

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 is a W3C Recommendation since October 2003, with a second edition of the 1.0 published in March 2006. The XForms Working Group is, as of August 2006, working on XForms 1.1, due in late 2006 or 2007, before embarking on XForms 1.2 or XForms 2.0! Please visit XForms - The Next Generation of Web Forms for more information about XForms direct from W3C.

XForms aims at replacing HTML forms, but it is not strictly tied to HTML. The main goal of XForms is to make web 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.

The Orbeon Forms implementation is based on the W3C XForms 1.0 (Second Edition) Recommendation (14 March 2006). The XForms NG engine in Orbeon Forms 3.5 is close to supporting all of the XForms 1.0 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 several features from XForms 1.1 (in draft as of August 2006), as well as extensions such as new widgets (autocomplete, tree, menu, dialog, etc.).

No, this is not a problem at all, because XForms can run 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 ot upgrade their browsers when bugs are fixed or new features are implemented.

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 or hybrid 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.

A server-side implementation of XForms 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:

For more information, we refer you to these articles we presented at the XTech 2005 and XTech 2006 conferences:

• XForms: an alternative to Ajax? (XTech 2006)

• Are Server-Side XForms Engines the Future of XForms? (XTech 2005) (see also the pre-conference proceedings, which contain an out of date version of the article)

Up to version 2.8, Orbeon Forms featured a pure server-side XForms engine with limited XForms functionality. With version 3.0, Orbeon Forms features a much enhanced XForms engine, with support for almost the entire XForms specification, with the intent to completely support XForms 1.0 and XForms 1.1 in the future. The older XForms engine has been informally dubbed "XForms Classic", and the new XForms engine "XForms NG".

For backward compatibility reasons, the XForms Classic engine is still present in Orbeon Forms 3.5. We plan over time to allow XForms NG to support non-JavaScript, non-Ajax browsers as well, therefore making XForms Classic obsolete in Orbeon Forms.

If you are using Orbeon Forms 2.8 or earlier, you are using XForms Classic. If you are using Orbeon Forms 3.0 or later, then you may be using XForms Classic or XForms NG, but there is an easy way to tell: if a <page> entry in your page flow features an xforms attribute, then and only then that page is using XForms Classic. Otherwise, if the page view contains at least one XForms model under its xhtml:head element, then it is using XForms NG.

The XForms Classic engine is available only for backward compatibility. It is deprecated and may be removed in the future. If you are starting an application from scratch with Orbeon Forms 3.5, we strongly advise against using XForms Classic. If you are migrating to Orbeon Forms 3.5, we advise starting migrating XForms NG. You can keep your existing pages working with XForms Classic, and write new pages with XForms NG. Over time, you can migrate existing XForms Classic pages to XForms NG, making for a smooth transition.

As of Orbeon Forms 3.5, only one feature of XForms Classic have not yet made it into XForms NG: support for browsers with very limited JavaScript functionality (non-Ajax mode). In time, we hope to bring these features to XForms NG as well, therefore completely deprecating XForms Classic.

Please visit Migrating from XForms Classic to XForms NG.

It is not a requirement to use XForms. 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.

Check the XForms upload control and the XForms upload example

With Orbeon Forms 2.8 or earlier, or if you are using XForms Classic with Orbeon Forms 3.0 or later, make sure that you have the correct submission method and encoding in your XForms model:

With Orbeon Forms 3.0 and XForms NG, uploaded files can only be retrieved with a submission with replace="all".

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.

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.

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.

As of Orbeon Forms 3.5, it is possible to use the Orbeon Forms XForms engine within the Java Portlet (JSR-168) compliant Liferay portal, thanks to kind sponsoring by Atkins Transport Systems.

It is expected that Orbeon Forms will work within other JSR-168 portals, or that only minor adjustments will be needed in such cases. Please report your experience to the ops-users mailing-list!

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.

HISTORICAL NOTE: There has been a lot of code in Orbeon Forms to support JSR-168 since late 2003 already. When this code was written, the JSR-168 specification was not final and no JSR-168 container was available. So Orbeon developped a container based on draft specifications for testing. This code was used until recently to run the Orbeon Forms examples portal: examples were actually using the portlet code and running as portlets, and the examples portal is an early JSR-168 portal. Note that this is no longer the case with Orbeon Forms 3.5, where the example applications portal does not use JSR-168 for performance and simplicity reasons.

Orbeon Forms 3.5's XForms engine supports Firefox (1.0.7 and later), IE 6, Safari (1.3 and later), and Opera (8.5 and later).

In the future we hope to also add support in XForms NG for non-JavaScript (and non-Ajax) browsers.

Orbeon Forms does not come with a visual forms designer. You create forms by writing XHTML pages that contain embedded XForms markup.

Orbeon Forms 3.5 comes with a new tutorial that 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.

In the future, we hope to be able to provide a web-based tool to help build forms.

At Orbeon we develop all our applications and forms using an XML editor. This is the only way you can leverage all the features of XForms today, especially the more complex ones like events and actions. This means that we do not have a visual tool to recommend officially. You may however try the Intalio designer. Trial versions are available from their web site once you register.

This said, one of our top priorities at the moment is to make it much easier to build forms with Orbeon Forms. We realize that there is a need for a visual form builder, and we would like to offer one in the short-term future. It will be web-based and itself implemented with XForms. In fact, we already have a prototype, so the only thing we can say is: stay tuned!

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.

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 successfuylly 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.

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:

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. However, "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.

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.

We do not guarantee that Orbeon Forms supports DDA, but it seems that the first step of DDA is to comply with WCAG 1.0 priority 1 and 2 (or AA).

With Orbeon Forms, many points in WCAG 1.0 relate to HTML written by the page author. For those, Orbeon Forms is of course in theory compliant since this depends on how the page authors creates the HTML. Regarding the markup that Orbeon Forms generate automatically, we are doing everything we can to produce clean HTML, which helps a lot with making pages accessible. For example we generate HTML labels for all form controls.

It seems that the most problematic point is point 6.3 of WCAG 1.0, which states that pages should be functional even if script is disabled. At the moment Orbeon Forms requires JavaScript and Ajax for its XForms pages to be functional. However:

• Based on feedback from people in the accessibility field, it seems that the requirement is being relaxed as JavaScript and Ajax take more importance, and as assistive technologies improve. For example, WCAG 2.0 (still a working draft at W3C), is quite reasonably going in the direction of not preventing script. For example it states:

  In choosing Web technologies (HTML, scripting, etc.) that will be used when creating content that will meet the WCAG 2.0 success criteria, authors must use technologies that are supported by users' assistive technologies as well as the accessibility features in browsers and other user agents. Such technologies are referred to as "accessibility supported."

• We think that it is possible to improve the XForms engine to support a JavaScript-less option, which would be less functional but which could use the same XForms source. Please let us know if you are interested in sponsoring this feature.

Orbeon is interested in getting your input on accessibility issues. Please contact us or post to the mailing-list if you have any feedback on this topic.

We hope to add a good configurable component system to Orbeon Forms in the future, but at the moment Orbeon Forms unfortunately does not feature an easy way of adding custom controls.

At this point, adding your own control involves either:

• Digging into the Orbeon Forms code, in particular the org.orbeon.oxf.xforms.processor.handlers package, xforms.js, and classes derived from XFormsControl.

• Implementing everything with CSS and JavaScript. In some cases, if your control is simple enough and a variation on an existing control, you may be able to implement the added behavior with JavaScript and CSS.

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.

Currently, the Orbeon Forms XForms engine uses JavaScript on the client. In particular, it uses The Yahoo! User Interface Library (YUI) as a foundation to Orbeon-specific JavaScript code. This is at the moment a required component of Orbeon Forms when you use the XForms functionality.

So at the moment, Orbeon Forms does not support JavaScript-less operation with XForms. However, it would be possible to support much of the XForms functionality without JavaScript, and even to automatically fallback to this mode if the client does not support JavaScript.

This would have some limitations, of course. Dynamic behavior in the user interface would be reduced, and the user might have to press buttons to perform udates, like with older-style web applications. Also, advanced widgets like dialogs, trees, and menus, might not be implemented.

If you are interested in this feature, please consider sponsoring it.

XML pipelining is an approach to processing XML where the inputs and outputs of multiple processing steps (e.g., XSLT transformations) are connected together using a pipeline metaphor. Orbeon has implemented an XML pipeline engine in Java that executes a declarative XML pipelining language called XPL.

"Programming" pipelines using declarative XML instead of writing procedural code results in a significant increase in productivity for tasks that require high volume or complex XML processing. XML documents enter a pipeline, are efficiently processed by one or more processors as specified by XPL instructions, and are then output for further processing, display, or storage. XPL features advanced capabilities such as document aggregation, conditionals ("if" conditions), loops, schema validation, caching, and sub-pipelines.

XML pipelines are built up from smaller components called XML processors. An XML processor is a software component which consumes and produces XML documents. New XML processors are most often written in Java, but most often developers do not need to write their own processors because the engine provides a comprehensive library. Example processors include an XSLT processor, database processors that interface with both SQL and native XML databases, and a serializer processor that writes XML documents to disk. XPL orchestrates these to create business logic, similar to the way Java code "orchestrates" Java object method calls.

At the core of Orbeon Forms lies a powerful XML processing engine that natively speaks the XML Pipeline Language (XPL). XPL is a declarative language for processing XML using a pipeline metaphor. XML documents enter a pipeline, are efficiently processed by one or more processors as specified by XPL instructions, and are then output for further processing, display, or storage. XPL features advanced capabilities such as document aggregation, conditionals ("if" conditions), loops, schema validation, and sub-pipelines.

The Orbeon XPL pipeline engine used in Orbeon Forms is designed for low-memory consumption and supports transparent caching.

The term XML processor is commonly used to refer to XML parsers. In the context of Orbeon Forms, the term XML processor is used to refer to any software component consuming and/or producing XML documents. An XML processor can also simply be called an XML component.

This particular example illustrates a simple 2-stage XPL pipeline that performs an XSLT transformation on an XML document that is located on disk, and then writes the result back to a another file on disk. For more details about XPL, please see the XPL and Pipelines reference documentation.

As of February 2005, a draft specification has been completed amd submitted to W3C. It serves as a basis of discussion for an XPL 1.0 specification.

As of December 2005, XML Processing Model Working Group meetings have started at W3C. This working group, of which Orbeon is a member, is in charge of working on a standard XML processing language. While the deliverable of the working group will certainly not be exactly XPL, we do hope that in its first version it will cover a significant number of use cases currently covered by the XPL implementation found in Orbeon Forms.

As of September 2006, the XML Processing Model Working Group (of which Orbeon is a member) has released a first public draft of the XProc XML Pipeline Language.

Yes.

Orbeon Forms supports a subset of XPointer. You can use the XPointer document#xpointer(/xpath/expression) syntax to extract a nodeset from a document.

It is possible by importing the stylesheet within another stylesheet, as follows:

Caching mechanisms should have no impact on the behavior of a system, except for a gain in performance. This is also the principle followed by the Orbeon Forms cache: when you develop an application with Orbeon Forms, you should be able to ignore that caching takes place. This may be all you want to know about caching in Orbeon Forms!

To get a better understanding of the underlying mechanism, consider the example below:

Let's assume the following:

• The XSLT processor's config input is an XSLT stylesheet on disk
• The XSLT processor's data input is an XML file on disk
• The XSLT stylesheet does not contain imports, includes, the document() function, or calls to Java code.

Under those assumptions, the XSLT transformation does not have side effects, which means that if neither the XSLT stylesheet ( config input) nor the input XML document ( data input) change, the output of the transformation will be the same.

If you were to keep the result of the transformation, knowing that both inputs have not changed since the last time you generated that output, you wouldn't have to actually run the transformation again: you could just reuse the result you already have. This is the basic of caching in Orbeon Forms.

In this example, the result of the XSLT transformation is used to create an XUpdate processor configuration, which is an XUpdate program that will be interpreted or compiled by the XUpdate processor. Instead of keeping the result of the XSLT transformation as an XML document, the XUpdate processor can cache the compiled XUpdate program. Compared to a solution where the XML document is cached, this technique saves memory by not keeping the XML document in cache, and saves processing power by preventing the XUpdate processor to recompile its program.

Therefore, if neither the XSLT transformer's config nor data input has changed, the XUpdate processor can keep the same program in the Orbeon Forms object cache, saving an XSLT stylesheet compilation, an XSLT transformation, and an XUpdate program compilation.

The same mechanism applies to the XSLT transformer configuration: the compiled XSLT stylesheet can be kept in the Orbeon Forms object cache. And if the output of the XUpdate transformation is sent to an HTML serializer, the HTML output could be cached as well.

In general, Orbeon Forms does not unnecessarily cache the XML documents passed between processors. Instead, it caches the result of time-consuming operations, as illustrated above.

Some cases are more complex than the example shown here. For example in the case of XSLT 1.0, Orbeon Forms handles caching and dependencies related to imports, includes as well as the XPath document() function when the URL passed to the function is static. Some processors, like the SQL processors, never allow their output to be cached.

The Orbeon Forms cache avoids executing the parts of a pipeline that do not need to be re-evaluated. However when the a debug attribute is set, the point where the attribute is set needs to be evaluated so that meaningful data can be displayed. This can cause the performance to degrade. Debug attributes should be removed in production.

Not at this time.

Processors can be compared to functions in traditional programming languages. Processors (just like functions) have inputs (arguments) and outputs (return values). Each input and output has a name. The name is part of the processor's interface. For instance, using an informal function-like notation, the XSLT processor interface is:

(data) = xslt(data, config)

since the XSLT processor has 2 inputs named data and config, and one output named data.

The interface to a processor is the contract that defines what inputs and outputs do. If you are using an existing processor, for example the XSLT transformer, you have to use the names declared by that processor. To know what names you must use, you have to consult the documentation for each processor. We have tried to be consistent and to use "config" and "data" as often as possible. You can for example call the XSLT transformer like this:

A pipeline can also be viewed as a processor. If that pipeline decides to export inputs and outputs, it must do so using the <p:param name="..."/> syntax. This defines its interface. You can compare this to writing your own method in Java, as opposed to using an existing method. The difference is that in Java, you address method parameters by position when you call a method. In XPL, you always address them by name. Therefore it is important to use the right name when you call a processor (or a pipeline).

This also applies to the cases where the Web Application Controller calls your own pipelines: the PFC has to know the names of the inputs and outputs to connect to. Therefore, you have to use the names ( data and instance) documented.

If you implement a pipeline or write a new processor in Java, and you don't have any external naming constraints (such as the ones defined by the PFC, or if somebody expects to call your pipeline using names defined in advance), you are free to use any name.

In XPL an id can be assigned to an output when invoking a processor. This id can then be used latter on in the same pipeline to refer to that specific output, and for instance connect it to the input of another processor. Ids are similar to variable names in most programming languages.

By default Orbeon Forms makes two uses of the string oxf::

• As an XML namespace prefix in XPL. The XML namespace prefix oxf is typically mapped to the XML namespace URI http://www.orbeon.com/oxf/processors. This namespace is used to resolve XML qualified names (also referred to as "QNames") that identify the built-in XML processors in XPL, such as oxf:xslt. These are constructs specific to XML.

• As a URL scheme. The oxf URL scheme is used to address Orbeon Forms resources through the Orbeon Forms Resource Manager. They are part of URLs such as oxf:/config/properties.xml. Such URLs are supported throughout the Orbeon XForms XPL engine and XForms engine.

Having both uses in the same file may be confusing. But while you have to use the oxf scheme to access Orbeon Forms resources, you don't have to use the oxf prefix in XPL: you can use any prefix you like, for example:

You created your own application based on the Orbeon Forms examples, and now you would like to get rid of the left navigation bar with that list of examples, as well as any other examples-specific look and feel.

The left navigation bar and other "decorations" are added to all the examples in what is called a theme. The theme is implemented in an XSLT stylesheet, and that stylesheet is applied to all the pages generated by your application. This is setup in config/epilogue-servlet.xpl. In that file, look for the comment "Apply theme". Below that comment, you will see some code in XPL which depending on the path applies either the theme theme-plain.xsl (no decoration) or theme-examples.xsl (examples portal decoration). Most likely you want to use theme-plain.xsl for all the page of your application. You can do so by replacing the whole <p:choose> with the first <p:processor> inside the <p:choose>, the one that applies the theme-plain.xsl theme. After this modification, the relevant section of your epilogue-servlet.xpl will read:

If you wish to add some specific look and feel to all your pages, you might want to create your own theme stylesheet, say my-theme.xsl and reference that stylesheet instead of theme-plain.xsl from epilogue-servlet.xpl.

If you get the white IE error page with the message "Cannot find server or DNS server error" when navigating to another page, it most likely means that the length of the URL for that page exceeds the limit imposed by IE. This can happen if you are passing an XForms instance from one page to another with a redirect. The solution often involves changing in your properties.xml the value of the instance-passing property for the processor oxf:page-flow from redirect to forward.

The instance-passing can be defined at application level in properties.xml, the page flow level, or the <result> element level. See the changes in version 2.5 for more information about instance-passing.

The exception typically looks like:

org.orbeon.saxon.trans.DynamicError: Illegal HTML character: decimal 150
at org.orbeon.saxon.event.HTMLEmitter.writeEscape(HTMLEmitter.java:321)

In general, you get this error when the encoding on your XML file missing or is incorrect. In the example above, we had specified the encoding to be ISO-8859-1, while editing the file on a Windows machine. The file contained a dash encoded as the character 150 in decimal, 96 in hexadecimal, which is not a valid character for the ISO-8859-1 encoding. In this case changing the encoding to windows-1252 solves the problem.

Specifying ISO-8859-1 instead of windows-1252 on files that contain characters invalid in ISO-8859-1 does sometimes work, but not always. In particular, more recent versions of Saxon became stricter checking for invalid characters. So we recommend you use windows-1252 instead of ISO-8859-1 when appropriate. You specify the windows-1252 encoding by starting your XML file with the following XML declaration:

For more information, see this discussion on the difference between ISO-8859-1 and Windows-1252.

We provide recommendations on how to tune Orbeon Forms applications in the Performance and Tuning section. Orbeon does not provide performance figures at this point, due to the number of different possible scenarios, the differences between hardware platforms, and the different expectations of users. We believe that the best way to tackle performance questions is to go beyond theory and work on a small but representative prototype. Orbeon can help you build that prototype, a task often done in just a few days. Upon completion of the prototype, you can evaluate whether the performance of the prototype is satisfying or not, and if not, Orbeon can help you determine whether and how performance can be improved. The final appreciation belongs to you.

Saxon 8 is used by default within Orbeon Forms. It has proven reliable, and supports the latest XSLT 2.0 and XPath 2.0 drafts from the W3C.

Orbeon Forms also ships with Saxon 6, Xalan 2.5 and XSLTC 2.5.

The full message looks like:

org.dom4j.IllegalAddException: The node "org.dom4j.util.UserDataElement@c11567 [Element: <gaga attributes: []/>] userData: null, line 0, column 0" could not be added to the branch "null" because: Cannot add another element to this Document as it already has a root element of: gaga

You get this error when you have a stylesheet that generate two or more root elements. This tends to happen if your stylesheet does not match on "/". For instance, say you have this stylesheet:

And this input document:

The XSLT output will be <x/><x/>, which is a not legal XML document (of course, you can only have one root element in an XML document).

Use the XSLT transformer and the saxon:parse function. This function parses an XML document supplied as a string and returns a document node. To copy the resulting document to the output of your XSLT transformation, use xsl:copy. For example, assuming your input document is as follows:

Consider also the following XSLT transformation:

Running this transformation on the input document above generates the following output:

This tip is particularly useful for parsing XML strings returned by EJBs, Web Services, or entered by a user in XForms textarea controls.

• If your JVM is running but is not responding to HTTP requests, you might first want to see where in the Java code threads are blocked. To do so, on Windows hit ctrl-break in the command prompt window where your application server is running; on Linux identify the process id of the JVM running your application server and issue a kill -3 pid.

  If you are using Tomcat and the threads are blocked in database code (e.g. SQLProcessor, PoolingDataSource) open your server.xml, locate the element configuring the Coyote HTTP 1.1 Connector. Make sure that the maxProcessors attribute on Tomcat 4.1 or the maxThreads attribute on Tomcat 5 is set to a value that is much lower than the value of the acceptCount attribute. Typically values for maxProcessor or maxThreads are 3 for a single-CPU server or 4 for a dual-CPU server, while the value of acceptCount can be much higher, typically between 50 and 100.

  For more information on those and other attributes configuring the Coyote HTTP 1.1 Connector in general, see the Tomcat 4.1 or Tomcat 5 documentation.

• Some versions of Chainsaw have a bug where Chainsaw stops responding in certain situations, which blocks the application server. If you are using Chainsaw, this might be the problem: use the FileAppender instead, or use Orbeon Studio instead of Chainsaw to view log messages.

• If you are running RedHat 9, set the environment variable LD_ASSUME_KERNEL=2.4.1 and restart the application server.

This is a Saxon issue. It might happen when in the input document of a stylesheet or in the output of the stylesheet you have an element declared with no prefix as the child of an element with a prefix. One way to get around this is to add a prefix to all the element having a parent declared with a prefix.

Efforts around the XUpdate language appear to be stalled. XML databases now tend to bid on proprietary extensions to the standard XQuery language (e.g. see what Tamino does, and there are talks about implementing something similar in the open source eXist database). In the future, XQuery will support standard update features.

We do recognize that XUpdate has definite advantages over XSLT in certain use cases (which is why we implemented it in the first place), but it seems that the market is currently not supporting what is considered "yet another XML transformation language".

For use as a general-purpose XML update language with Orbeon Presentation Server, we now recommend using XSLT. Use either XSLT 1.0 or XSLT 2.0 (12 November 2003 Draft as implemented by Saxon) instead of using the XUpdate processor. The only place where XUpdate is not deprecated is within Page Flow, but only a subset of XUpdate is required and you can simply consider that it is part of the Page Flow syntax.

This being said, our XUpdate implementation is functional and of course anybody is free to use it or contribute to it. Like the rest of Orbeon Forms, it is available under the LGPL license.

Insert at the very beginning of the in the XUpdate code those 3 lines to log the instance being modified (instance of target page), the current instance, and the output of the action pipeline:

Then as the very last instruction in the XUpdate code, add:

If this exception is thrown from the class TransformerImpl class in a Xalan package (orbeon.apache.xalan.transformer), a bug in Xalan is at the source of the problem. Xalan calls the SAX startElement() method with an attribute that has an empty local name.

Switching to Saxon solves the problem. Saxon is now the default XSLT 1.0 and XSLT 2.0 processor in Orbeon Forms, and will get used when using oxf:xslt. See the XSLT documentation for more information.

This usually happens when you use XInclude. As per the XInclude specification, such attributes are added upon inclusion. You can get rid of them by using XSLT:

This used to happen with JBoss 3.2.1 and OXF 2.2. The work around a the time was to add -Dorg.jboss.logging.Log4jService.catchSystemOut=false to the end of the JAVA_OPTS line in JBOSS_HOME/bin/run.bat. (run.sh on UNIX)

Often, this is due to too many threads doing processing within Orbeon Forms at the same time. There is just a lot going on in Orbeon Forms when a request is processed, including typically several XSLT transformations. Please see Reduce the number of concurrent processing threads.

Java stack traces are indeed very long in Orbeon Forms. This is due mainly to the nature of XPL pipelines, which are implemented on top of the event-based SAX API.

In reality you cannot make any reasonable conclusion about performance just by looking at the length of a typical stack trace: you would have in addition to that to look at the pattern of execution of those methods. For example, if every top-level method call was going through, say, 300 levels of method calls, this would likely be an issue, but it is not the case in Orbeon Forms. The bottom line is that no, the length of a stack trace does not directly correlate with poor performance.

To reach valid conclusions about performance, run a tool like Apache JMeter on your application.

Yes, the Scope serializer and Scope generator simply use the Servlet (or Portlet) session to store and retrieve information.

• You can get support from the Orbeon Forms community on the ops-users mailing list. The ops-users mailing list is the hub of the Orbeon Forms community, and this is the best place to ask questions, share you experience, or post issues and requests for enhancements. Also see:

  • How can I subscribe to the Orbeon Forms mailing list?

  • How to report issue in the Orbeon Forms mailing list?

  • Where are the Orbeon Forms mailing list have archives?

• Orbeon can provide professional support for your company. Orbeon has two types of plans: Product Support plans are the most appropriate when your application is in production, while Proactive Support plans also covers issues during development, feature enhancements, and training. For more information contact Orbeon at info@orbeon.com.

1. To subscribe, send an email to: ops-users-subscribe@objectweb.org. You can leave the subject and body of your email empty.

2. You will receive a message from sympa@objectweb.org, asking you to confirm that you want to subscribe to the list. Confirm by following the instructions in that message. If you don't receive this message in an hour or so, you might want to check if it went to your spam folder.

3. You should then start receiving messages from the list in the next few hours. You might receive 10 to 30 messages a day, so you might want to setup your mail client to automatically move those messages in a particular folder, so they don't all show up in your inbox.

If you are having any problem subscribing to the list, please contact at info@orbeon.com.

The key to effectively reporting an issue is to post in the ops-users mailing list a message with:

• A reproducible test case, attached to your message

• How to run this test case

• What is the behavior you observe when you run the test case

• What is the behavior you expect

But why a reproducible test case? The alternative is to describe the issue in plain English with maybe the help of code snippets. The problem with this approach is that it requires of people who will be helping you on the mailing list to understand the context of your problem, which might be trivial to you, but can be hard to grasp quickly for someone else.

You can provide two types of test cases:

• An XHTML+XForms file that runs in the XForms sandbox - This is by far the preferred way of submitting a test case. Most problems with XForms can be shown in one single XHTML+XForms file. If you need the XForms to call a service with an <xforms:submission>, you can simulate this by placing an XML file that contains the response from that service on a public web site, and changing the <xforms:submission> to point to that file. If you don't have a server of your own that you can use for this, a free hosting service like GeoCities will work.

• An application - An Orbeon Forms application is stored under resources/apps. Assuming you have your application under resources/apps/foo, it can be accessed by going to http://localhost:8080/ops/foo/. If you can't create a test case that runs in the XForms sandbox, create a simple standalone application under directory foo, zip the content of that directory, and attach it to your email in the mailing list as foo.zip.

In both cases:

• Make your test case as simple as possible. Remember that people who will be helping you on the list often don't have much time, and you are more likely to receive feedback that is useful if your test case only contains the minimum amount of code required to reproduce the issue.

• Keep your post focused on a single issue. If there are more issues you would like to report, post them in separate threads, or post the first one and wait to get that one resolved before you post the next one in another thread.

At least in two places:

• At OW2. This is the primary archive.

• At Nabble. This is an external archive powered by excellent software.

You can help by:

• Subscribing to the ops-users mailing list, and helping other people in community.

• Contributing to the open source effort. If you have a feature in mind and think it would benefit Orbeon Forms, you can implement it and contribute it. The best place to get started is to discuss your idea on the ops-users mailing list.

• Get a Support Plan with Orbeon. If Orbeon Forms is what it is today, it is in great part thanks to companies who have financially supported Orbeon, allowing Orbeon developers to be paid to work on Orbeon Forms and make it a better product. For more information, see Support and Service or contact Orbeon at info@orbeon.com.

Your support is greatly appreciated!

The XPL Trace facility provides information for a given page served by Orbeon Forms. For that page, it shows a tree of processor calls and indicates on that tree how much time has been spent on each node. This information collected by XPL Trace can be either sent to the standard output, or to Studio. When sent to Studio, it will be shown in the XPL Trace Table and XPL Trace Tree views. For this to work as expected:

• You need to setup the port Studio listens to, from Preferences / Orbeon. That port must match the one you have setup in Orbeon Forms properties.
• After changing the port number in Studio, you might have to restart Eclipse.
• For Studio to listen on the specified port, you need to have two views (XPL Trace Table and XPL Trace Tree) open. You might also need to at least make one of the views active before Studio starts listening on the specified port. On Windows, you can check if Studio is listening on the port you specified using TCPView.

• For version 1.0.3 or higher :
  1. Select the menu item Run | Run...
  2. Either create a new J2EE Container Container for Orbeon Forms launch configuration or select an existing one.
  3. Select the Argguments tab.
  4. In the VM arguments field add your VM arguments.
  5. Click the Apply button to save the change.
• For versions lower than 1.0.3 :
  1. Open the Window | Preferences dialog.
  2. Under Java | Installed JRE, select the "Standard VM".
  3. Click on the Edit button.
  4. Enter your own VM arguments in the Default VM Arguments text field.

  Note that this sets the VM arguments for all the applications you run from Eclipse. At this point there is no way to set VM arguments that are only used when starting the J2EE container.

Check the following:

1. Make you don't have any "Address already in use" error in the Console view when you start the application server. If you do, it means that you already have another application (other program, or other Orbeon Forms application maybe deployed in the same application server) using the same port. On Windows, you can use TCPView to determine what application is using the port you mention in the log4j.xml.

2. Make sure you don't have any filter setup in Logging Events view by right-clicking on the "down arrow" icon and selecting "Filters".

3. To populate the Logging Events view, Studio connects to log4j, and log4j listens on the port specified in the log4j.xml file.

   There is nothing in the Studio preferences to tell Studio to which port it should connect. Instead, Studio finds the port by looking at all the log4j.xml files you have in all the open projects. It will then try to connect to all the ports specified those files.

   If log4j was able to listen on the port specified in your log4j.xml (see point 1 above) and still no messages appear in the Logging Events view, that might be because Studio cannot find your log4j.xml. So make sure that this file is in an open project defined in the Studio. Also note that if you modify this file outside of Eclipse with an external program, Studio won't pick up that modification. In that case, in the Navigator view, right click on the project that contains your log4j.xml and choose Refresh. Right after this, events should start to appear in the Logging Event view as you load pages in the browser.