About Orbeon Forms 4Orbeon Forms 4 is a major Orbeon Forms release which features many improvements since Orbeon Forms 3.9 and Orbeon Forms 3.9.1 PE. See Orbeon Forms release history for the list of all releases in the 4.x series and all release notes.
Downloading Orbeon Forms 4Orbeon Forms 4 is available in two separate editions. You can download the build using from the downloads page. The major new features are described in this blog post. Don't miss it, that's where the exciting stuff is! But in summary, Orbeon Forms 4.0 gets:
Other new Form Runner features
Other new XForms features
Other new features
Browser supportForm created with Orbeon Forms can be accessed by a wide range of browsers. However, Orbeon Forms web based tool to create form, Form Builder, is more sophisticated than most forms, and is used by a smaller number of people, i.e. those within your organisation who will be creating forms. Hence Orbeon Forms supports a different set of browsers depending on whether you are accessing forms or creating forms with Form Builder:
PlatformHTML pages now use the HTML 5 doctype by defaultThe doctype is the declaration at the top of HTML pages. HTML 5 requires the following:
In the past we used one of the HTML 4 doctypes:
You shouldn't need to switch the doctype, as it has been considered the best option for old and new browsers:
"all current browsers (IE, FF, Opera, Safari) will look at it and switch the content into standards mode – even though they don’t implement HTML5" But if you absolutely need to revert to an older doctype, you will have to make changes to the following files:
See the commit for reference.
Page Flow ControllerAuthorization of pages and servicesWith previous versions of Orbeon Forms, requests to pages and services were unrestricted. With this version:
This behavior makes pages and services more secure out of the box. This can be configured easily, see Authorization of pages and services.
Although we don't recommend it, if you want to, you can enable the old behavior with the following properties:
We also recommend that if you have services, they be configured with the new Regular expressionsThe Page Flow Controller used to support configurable matchers via the
matcher attribute. There are now only two choices:
The following syntax is deprecated:
The new syntax is simply:
The default remains glob expressions.
There can be minor differences between Java regular expression and the regular expression engine (Apache Jakarta ORO) used in previous versions of Orbeon Forms. Mostly, the expressions remain compatible.
New element and attribute namesThe Page Flow Controller introduces new element and attribute names:
The old names remain for backward compatibility but are deprecated.
The
params element under page , deprecated for a long time, has been removed. The setvalue element must be used instead.Behavior of not-found-handlerThe of
not-found-handler , used to specify a "not found" page, now also runs when a page throws an exception denoting that a resource has not been found.Form Builder and Form RunnerForm Runner persistence layer configurationIn 3.9, you had a direct mapping from app, form, form type to the URI implementing the REST persistence API. For instance, to map "everything" to the Oracle persistence layer, in 3.9 you would write:<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.*.*.*" value="/fr/service/oracle"/> Orbeon Forms 4.0 introduces a level of indirection: you map app, form, form type to a provider, and then map that provider to its REST persistence API. Since a provider named oracle is pre-defined, the configuration equivalent to the above 3.9 property is:<property as="xs:string" name="oxf.fr.persistence.provider.*.*.*" value="oracle"/> Amongst other things, this allows you to setup Orbeon Forms to use different schemas for different app, form, and form type combination. For instance you could store everything related to an
hr app in once schema and everything related to another finance app in another schema. For more on this, see how to setup the persistence layer for multiple schemas.Similarly, for eXist:
Here is the 3.8/3.9 way of configuring the URI to point to the eXist location:
And here is the 4.0 property:
For more, see Configuration Properties - Form Runner.
Security of the built-in eXist databaseBy default, the built-in eXist database used by Form Runner is now protected. This means the following:
In particular, this means that you can't access eXist's REST API from outside Orbeon Forms. If you need such access, we recommend that you setup a properly secured Form Runner eXist database. In general, we recommend using an external database for production anyway.
If you need, for development purposes, to disable this security check, you can comment out the filter mapping for
orbeon-exist-filter in web.xml . You can also setup an eXist username/password and configure Form Runner with that username password.Submitting initial data to Form RunnerForm Runner 3.9 has two properties which enable POSTing data to a form's
new or edit pages from an external application:
Form Runner 4.0 has a new and improved authorization mechanism for services (see Authorization of pages and services), and these properties no longer have any effect.
In order to implement the same behavior with 4.0, you use the new authorization mechanism:
Form Runner references to attachmentsUp to Orbeon Forms 3.9, form definitions and form data referenced attachments including the persistence implementation provider. For example, the path to an attached image would look like:
This caused issues if you need to change persistence providers but want to keep the same data.
Post-3.9, the specific persistence implementation name is replaced by a generic and local persistence path:
URLs to a specific provider still exist, but they now require specific configuration headers and typically will no longer work correctly to load attachments. This means that you may need to convert paths in your existing data to adapt to the new scheme.
Form Builder components configurationThe following property was deprecated and has been removed:
Instead, use
oxf.fb.toolbox.group . See also Configuration Properties - Form Builder.Form Builder publishing of attachmentsIn previous versions, form definition attachments were not published alongside the form definition. In this version, they are, and if you wrote your own persistence layer you might need to make changes to support PUT of attachments alongside the form definition.
Look and feel of Form Runner buttonsThe
fr:button component provides nice-looking cross-browser buttons by using the underlying YUI button widget. However with older browsers, the JavaScript involved can make page loading slower than desirable when a large DOM and/or large number of butons are present.In this version of Orbeon Forms, we have made the default button produced by
xf:trigger look nice out of the box, and without JavaScript. This means that you usually won't need fr:button at all.Form Funner and Form Builder have been updated to use xf:trigger instead of fr:button.
The CSS for the new buttons is available in
xforms.css .XPath type annotations enabled by default on new formsXPath expressions defined in Form Builder to specify validation constraints, visibility, read-only, and calculated values, now make use of type annotations by default on new forms. Existing forms are not affected.
For more information on XPath type annotations, see XForms - XPath 2.0 Support.
Twitter Bootstrap CSSForm Runner now uses Twitter Bootstrap. If you have custom CSS which works with Orbeon Forms 3.9, it is likely that you will have to update it to work with Orbeon Forms 4.0.
Strength of CSS rulesBootstrap, XForms engine, Form Runner and Form Builder rules are now contained within an enclosing
.orbeon CSS class. This ensures that the Orbeon CSS rules only apply within an element with that class. It also makes Orbeon CSS rules a bit stronger than before. You might have to update your custom CSS to take this into account.Adding your own CSSOrbeon Forms 4.0 has a new property to define your own CSS:
oxf.fr.css.custom.uri.*.* . For example:
With 3.9, you had to make sure you were first copying the exact value of the
oxf.fr.css.uri.*.* property, which was fragile and inconvenient. We recommend using the new property.XForms engineEncryption passwordWith Orbeon Forms 4.0, the
oxf.xforms.password property has been renamed oxf.crypto.password . For more information, see Configuration Properties - Base.oxf.xforms.password is still supported for backward compatibility.Encryption of item values of the clientIn previous versions, by default, item values sent to the client were encrypted. In this version, instead, item values received a simple number. This should not cause any particular compatibility problem.
Error handling during XForms processingError handing is more permissive, to allow users to recover from a crash in more cases. See XForms - XPath and Actions Error Handling for more information about the new behavior.
Flow of XForms events along XBL scopes and event retargetingWith 3.9, XForms events within XBL components had incorrect behavior with regard to crossing XBL boundaries, in particular:
This release fixes these issues and events now flow alongside XBL boundaries and are not incorrectly retargeted. XBL component which depended on this behavior might require changes.
Behavior of extension xxforms-valid and xxforms-invalid eventsWith Orbeon Forms 3.9, these two events were dispatched after every validation, and each instance would receive one of the two events. With Orbeon Forms 4.0, these events indicate a change in the validation state. So only the instances changing state (from valid to invalid or from invalid to valid) receive an event.
For more information, see XForms - Validation.
HTML layout switched to "span" modeThe default HTML Layout of XForms Controls is now the "span" mode for all XForms pages including Form Builder and Form Runner, and the "nospan" mode is removed (it was already considered legacy in 2009!).
In order to switch to the "span" mode, you might need:
Deprecation of YUI RTE and use of tinyMCEIn previous releases, we recommended using YUI RTE as the rich text editor component, enabled via
<xforms:textarea mediatype="text/html"> . In this release, the recommended rich text editor component is tinyMCE, available via the XBL component fr:tinymce .Model variable scopingShadowing of model variables in the view has been fixed.
With previous versions, other model variables could incorrectly be seen in transparence. Say you had switched between model1 and model2, in the view you would see the following variables:
Now, you see:
This fix could impact forms that incorrectly relied on the previously incorrect behavior.
xforms:group and xforms:switch no longer dispatch xforms-value-changedThese two controls are not meant to hold values. In version 3.9, however, they did hold a value to help with the implementation of XBL components. Other mechanisms are now available, including using
xforms-value-changed on variables, so this feature has been removed.If you implement XBL components or plain XForms code depending on this, you can easily update it. For example replace:
with:
Focus handlingFocus handling has been overhauled. See XForms - Focus for details about the new behavior.
Specifically, the following has changed:
These changes impact:
If you never rely on
DOMFocusIn and DOMFocusOut, this change probably doesn't impact existing code, although from the user perspective focus might still change in a different way.If you do rely on
DOMFocusIn and DOMFocusOut, it is advised to review listeners for these events.DOMActivate on <xforms:output>When a user clicked on an
<xforms:output> control, the XForms engine used to dispach a DOMActivate event to that control. This is no longer the case and no event is dispatched by default.You can enable that behavior by adding the
xforms-activable class:
Blanking of calculated and initial values upon errorWith Orbeon Forms 3.9, if a runtime exception occurred when evaluating a
calculate or xxforms:default expression on xforms:bind , the behavior was a if the evaluation did not take place at all.With Orbeon Forms 4.0, if such an error occurs, the calculation sets a blank result value instead. This avoids stale calculated values, which can be confusing.
Behavior of XPath annotationsWith 3.9, when using
xxforms:expose-xpath-types="true" , if an XPath expression was accessing a typed value with a value which didn't match the annotated type, an untyped atomic value was returned. With 4.0, the expression instead fails.NOTE: In Orbeon Forms 3.9, this feature was rarely used and not activated by default, so this change should have little practical impact.
Removal of xforms-widgets.xslThe
xforms-widgets.xsl transform was deprecated in Orbeon Forms 3.8 and has been removed.Follow the 3.8 release notes linked above for how to transition to using
<fr:tabview> instead.The preferred version of implementing new components is by using XBL.
Removal of widget:xforms-instance-inspectorThe component
<widget:xforms-instance-inspector> was deprecated in Orbeon Forms 3.8 and has been removed. Instead, use:
NOTE: You don't need the namespace mapping if you already have it in scope.
Use of xhtml:class on controlsThe attribute
xhtml:class on controls was undocumented and has been removed. Use plain class instead.XBL Componentsfr:tabviewThe
tab-changes-context property has been removed. fr:tab behave like xforms:group : if the element has a ref or bind , it binds to a node, otherwise it doesn't. This was the default behavior with the tab-changes-context property. Removing the property just no longer makes it possible to disable this behavior.OtherPipeline Engine attributesThe following two deprecated attributes on processors are removed:
Renaming of oxf:xhtml-rewrite and oxf:html-rewrite inputs and outputsThese processors' inputs and outputs are renamed as follows:
This is consistent with most processors.
NOTE: These processors are unlikely to be used outside of Orbeon Forms internals.
Removal of deprecated custom-processors.xml fileOrbeon Forms 3.9 deprecated the
custom-processors.xml file. This version removes support for this file entirely. Instead, use processors-local.xml under the config directory.Deprecation of oxf.prologue propertyUse instead
oxf.pipeline.processors . Note that this property is rarely used.4.0 Release Candidates
|