OPS User Guide

Changes in Version 3.0 BETA

1. Introduction

Welcome to OPS 3.0 BETA!

OPS 3.0 features an XForms engine much improved over OPS 2.8's, significant improvements in the Page Flow Controller, and much more!

The purpose of the OPS 3.0 BETA is to provide you with a first glimpse of the OPS 3.0 functionality, while OPS developers keep ironing out the last bugs and finishing up the documentation! During the beta period, we are looking for as much feedback as possible related to all the aspects of the OPS 3.0 BETA release.

Please use the ops-users mailing-list for feedback about OPS 3.0 BETA.

2. Known Limitations of OPS 3.0 BETA

The following limitations are known:

  • Initial generation of an XForms page may have poor performance.

  • xforms:upload is not yet implemented in the OPS 3.0 XForms engine. xforms:upload remains implemented when the legacy OPS 2.8 compatibility mode is enabled.

  • Image and link appearances are not supported for the xforms:submit and xforms:trigger controls.

  • The xforms:message action is not implemented.

  • Not all the OPS examples have been updated to reflect the new XForms engine capabilities.

  • The OPS reference XForms documentation has not yet been updated to reflect all the changes in OPS 3.0. Please refer to the "XForms NG" examples for details.

  • The OPS reference XForms compliance matrix has not yet been updated to reflect all the changes in OPS 3.0.

  • Migration documentation from 2.8 to 3.0 is not complete yet.

  • The OPS Tutorial has not been updated for 3.0.

  • The OPS Blog example is not complete.

  • The Ajax-based XForms engine currently works with Mozilla Firefox and Microsoft Internet Explorer 6. Support for Opera and Safari is planned.

  • This release has only been tested with Tomcat.

  • The PDF version of the User Guide does not have page numbers.

3. XForms

3.1. New Features

The OPS XForms engine introduces a big step towards supporting all of the XForms 1.0 specification. The main changes are described below. Please also visit the new XForms examples, in particular the XForms Controls, the BizDoc NG example, and the XForms Sandbox example.

  • Ajax-based engine. The XForms engine is now based on Ajax technologies. This makes the XForms engine much more responsive to user interaction than with OPS 2.8.

  • Standard XHTML integration. The XForms engine works on standard XHTML + XForms documents, without the need for a separately described XForms model as was the case with OPS 2.8. XForms models are simply included in the XHTML page view under the <xhtml:head> element, as recommended by XForms 1.0. In this mode, you don't use the xforms attribute on the PFC <page> elements. The xforms attribute is still supported for backward compatibility, but its use triggers the use of the legacy OPS 2.8 XForms engine.

  • XForms event model. The XForms engine supports the XForms event model, most XForms events and all XForms actions.

  • Multiple XForms models and instances. The XForms engine supports multiple models and multiple instances within models. The instance() function is supported.

  • XForms switch module. The XForms engine fully supports the XForms switch module.

  • XForms repeat module. The XForms engine supports correctly the current index in repeated sections, including the index() function.

  • XForms submission. The XForms engine supports submitting forms as application/xml, including to external applications. Support for replace="instance", replace="all", and replace="none" is included.

  • XForms Range control. The XForms engine supports a subset of the functionality of the XForms Range (or slider) control.

  • Extension functions. The XForms engine supports the xxforms:call-xpl() extension function to call arbitrary XPL programs from XForms.

  • Dynamic XForms models. The new XForms engine and PFC improvements now allow to easily generate XForms models based on XML submissions. With OPS 2.8, this was much more difficult as this had to be done in a dynamic XForms model pipeline, which did not have access to an XML submission.

  • Simplified theme. The default theme and XForms make more use of CSS so that configuration of your own theme is easier.

  • XForms sandbox. The new XForms Sandbox example allows you to easily try your own XForms examples. Just write and XHTML + XForms example, upload it, and watch the results!

  • Other changes. The XForms engine supports the value attribute on xforms:output, handles inheritance of model item properties, and includes numerous bug fixes.

  • TODO: document (X)HTML attributes supported on XForms elements: id, class, navindex, accesskey, plus tabindex, style, and how to handle other attributes (xhtml:*).

TODO: link to updated XForms conformance map.

3.2. Incompatible changes

  • XSLT views now must always use doc('input:instance') to access a submitted XML instance instead of expecting the instance on their main input.

  • With OPS 2.8 if your XForms instance was:

      <credit-card>  <type>visa</type>...  </credit-card>

    and your first XForms element under the <xhtml:body> element was:

      <xforms:group ref="credit-card" xmlns:xforms="http://www.w3.org/2002/xforms"/>

    then credit-card would evaluate against the document node of the unique XForms instance. The above code worked, but this behavior was incorrect. The XPath evaluation context for top-level XForms controls has to be the root element of the default XForms instance instead. This means that the code above must be changed in one of two ways:

      <xforms:group ref="/credit-card" xmlns:xforms="http://www.w3.org/2002/xforms"/>

    or:

      <xforms:group ref="." xmlns:xforms="http://www.w3.org/2002/xforms"/>

    If you already use absolute XPath expressions for your top-level XForms controls, no change is necessary.

  • With OPS 2.8, the "required" model item property did not apply to elements validated with XML schemas. If for example a value was of type xs:integer but missing, it was marked as invalid. With OPS 3.0, the default value for the "required" model item property is "false" for values validated with XML schemas as well. This means that with OPS 3.0, some values invalid with OSP 2.8 are now valid. In order to fix this, explicitly set the "required" model item properties on values you would like to be required.

3.3. Migrating to the OPS 3.0 XForms Engine

Warning

By default, your applications written against OPS 2.8 will use the legacy 2.8 XForms engine in OPS 3.0. With OPS 3.0, you use XForms in the way you expect when combining XForms with XHTML, in that you do not declare an XForms model separately from your XHTML page.

In order to leverage most of the new features of XForms 3.0, it is necessary to migrate your forms. This is a list of tasks to accomplish and possible caveats:

  • For a given <page> element:if your OPS 2.8 XForms model is static (which is usually the case), copy it under your XHTML page view's xhtml:head element. Then remove the xforms attribute from the <page> element. You can then remove the file containing your XForms model.

    Another possibility is to keep your XForms model file, and to XInclude that file in your XHTML page view under the xhtml:head element. Here again, you must remove the xforms attribute from the <page> element.

  • TODO: xforms:submission and xforms:submit (id, action, method).

  • TODO: handling submissions: there are no longer roundtrips which are visible to the PFC for xforms:repeat, etc.

  • TODO: instance validation (remove from PFC, do it with XForms). Question of custom instance validation.

  • TODO: converting dynamic XForms models.

  • TODO: using events.

  • TODO: more?

4. Page Flow

Several improvements have been added to the Page Flow Controller, some of them motivated by the new XForms engine. The PFC is now more generic and less tied to the built-in OPS XForms implementation. At the same time it plays better than before with XForms, including client-side XForms engines. The major PFC concepts found with OPS 2.8 have not changed and backward compatibility is kept. The main changes are the following:

  • Documentation. The PFC documentation has been reworked and greatly improved.

  • Standard Epilogue. The standard epilogue has been restructured into three separate files so as to be easier to understand, modify, and extend. It is fully documented.

  • Deprecation of the xforms attribute. Using XForms with OPS no longer implies using an xforms attribute on the <page> element. Instead, XForms models are included in the XHTML page view under the <xhtml:head> element, as recommended by XForms 1.0. The xforms attribute is still supported for backward compatibility, and triggers the use of the legacy OPS 2.8 XForms engine.

  • New XML submission mechanism. The PFC features a new generic XML submission mechanism. Each page in the PFC, instead of supporting native OPS XForms engine submissions, now supports generic XML submissions. You submit XML by POST-ing content with an XML content-type (other types of XML submissions can be added). XML submissions can be performed from external applications (through Web Services, XML-RPC, etc.), client-side XForms engines, the built-in OPS XForms engine, or by the PFC itself when navigating between pages.

  • Deprecation of the <param> element. The PFC's <param> element was used to set values into a submitted XForms instance. A new, more flexible element, <setvalue>, now performs the same task. The <setvalue> element supports extracting information from regular expressions applied to the request path, as well as extracting request parameters. This allows for creating "clean", REST-like URLs in your appliation. param is still supported for backward compatibility.

  • Generic XML submission transformations. The PFC features a new generic and extensible XML submission transformation mechanism. With OPS 2.8, XUpdate code had to be used to transform XML instances between pages. XUpdate support in the PFC is now deprecated. Instead, XSLT or XQuery should be used for that purpose. For more information, please refer to the <result> element section of the PFC documentation.

  • Accessing XML submissions. XML submissions can be accessed from actions, page models, and page views, through the instance input. Users should not assume that XML submission are available from the data inputs.

  • Shorter page flows. Because of the enhanced XForms support, in particular, the XForms switch module and support for application/xml submissions, page flows are typically shorter to write. Compare for example the BizDoc Classic example with the BizDoc NG example.

  • Tracing: TODO

5. XSLT processor

The following improvements have been made to the XSLT processor:

  • Attributes input. The XSLT processor supports a new attributes input, which allows setting JAXP TransformerFactory attributes.

  • Safer defaults. The default XSLT processor (accessed with oxf:xslt, and configured in processors.xml) no longer allows executing external functions. To enable external functions, use oxf:unsafe-xslt, or configure the XSLT processor's attributes input. This makes the XSLT processor safer by default.

  • Default implementation. The default XSLT 1.0 processor implementation, configured in processors.xml, is now Saxon 8 instead of Xalan. The default XSLT 2.0 implementation remains Saxon 8, as was the case before.

  • Deprecated behavior. The XSLT processor used to support a value of DEFAULT or interpreter for the transformer input, for backward compatibility. This is no longer supported. The transformer must provide only a valid JAXP TransformerFactory class name. Most users should not be affected by this change.

Note

These changes should not affect applications that used oxf:xslt unless stylesheets use external functions. In this case, you have to use oxf:unsafe-xslt instead.

If you were using oxf:xslt-1.0 or were using XSLT 1.0 stylesheets directly referenced from a page flow, and used Xalan-specific features, you have to either convert your stylesheet to use Saxon features instead, or use oxf:xalan.

TODO: document the fact that transformation is separate from serialization with OPS. See XML serializer.

6. XQuery processor

The XQuery processor has been updated:

  • Default implementation. The default implementation of the XQuery processor is now Saxon 8.

  • Safer defaults. This processor is available with oxf:xquery or oxf:unsafe-xquery. The former does not allow calling external functions by default, while the latter does, similar to the new behavior of the XSLT processor.

  • Query format. In addition to XQuery code embedded into XML, the XQuery processor now supports in its config input a text document of the form:

      <document xsi:type="xs:string">xquery version "1.0"; ...  </document>

  • PFC integration. XQuery can be used in the PFC to perform XML submission transformations.

7. XHTML Support

XHTML is now much better supported:

  • Simplified theme. There is no need to remove the XHTML namespace from XSLT, as was done before in theme.xsl. Your theme should simply use the XHTML namespace.

  • Switching between XHTML and HTML. The standard epilogue illustrates how to generate XHTML and HTML to different browsers.

  • Using XHTML serialization. The standard epilogue illustrates how to to connect the XHTML serializer.

Note

In order to benefit from features such as XForms, you should make sure that your page views generate XHTML. In particular, your XHTML elements must in the XHTML namespace (http://www.w3.org/1999/xhtml).

8. Other Changes

The following changes are new in OPS 3.0 BETA:

  • HTML Documentation. The OPS User Guide in static HTML format, broken OPS 2.8, is now working correctly. This format allows you to consult the documentation offline without running OPS or without accessing the online documentation.

  • PDF Documentation. The OPS User Guide in PDF version is back! You can print this book for reference.

  • OPS Blog example. This new example illustrates many of the capabilities of OPS, including:

    • Implementing XML-RPC services
    • Connecting to a native XML database
    • Using XForms
    • Producing XHTML, RSS and other formats from a single data source
    • Implementing configurable themes with XSLT
    • Creating "clean" URLs in a REST perspective
  • Resource Manager. The Flat File and Filesystem resource managers have been merged. The Flat File resource manager is now deprecated, and the Filesystem resource manager should be used instead. The Flat File resource manager can still be used for backward compatibility. The main difference between the two resource managers is that the Filesystem resource manager can be configured with or without a sandbox.

  • PDF Processors. TODO

  • Directory Scanner Processor. The purpose of the Directory Scanner processor is to analyse a directory structure in a filesystem and to produce an XML document containing metadata about the files, such as name and size. It is possible to specify which files and directories to include and exclude in the scanning process. The Directory Scanner is also able to optionally retrieve image metadata. Two new command-line examples illustrate the use of this processor.

  • Faster URL Rewriting. In order to improve performance URL rewriting has been re-implemented in Java. The new implemetation is accessed through the new rewrite processors oxf:xhtml-rewrite and oxf:html-rewrite.

  • Disabled Validation. Previously the data input of the oxf:xforms-output processor and the config input of the oxf:portlet-include processor were validated unless one turned off all input parameter validation in OPS. However we found that validation of these two inputs came with at significant price and consequently these inputs are no longer validated by default. To enable the validation one must specify the appropriate schema URI with the schema-uri attribute. For the data input of oxf:xforms-output the URI is http://www.w3.org/2002/xforms/controls and for the config input of oxf:portlet-include the URI is http://orbeon.org/oxf/xml/portlet-include.

  • TODO