Orbeon Search

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

XForms - Remote Portlet Deployment

Contents

  1. 1 Availability
  2. 2 Introduction
  3. 3 Architecture
  4. 4 Orbeon Forms configuration
  5. 5 What the portlet must do
  6. 6 Cookie/Session handling
  7. 7 Ajax portlets

Availability

As of Orbeon Forms 3.9, this feature is no longer available. However, the Form Runner Proxy Portlet is available for use from a portal.

Introduction

This is an experimental mode that explains how you can deploy Orbeon Forms in a servlet container, but accessing it (i.e. display forms and interact with them) from a Java JSR-286 portlet.

See also Ajax Portlets.

Architecture

  • The "remote portlet" consists of Orbeon Forms running as a servlet in a servlet container
  • The "local portlet" is your own portlet running in a portal (e.g. Liferay)
    • NOTE: Orbeon Forms MAY also run within the same portal as a servlet. There is no actual requirement for being deployed in a separate container or on a separate server.
  • Connection between local and remote portlet using HTTP
  • URL rewriting
    • Within Java portlets, the portal (portlet container) controls URL generation. In particular, pages running in a portlet are expected to call URL methods of the portlet API.
    • The remote Orbeon Forms portlet must therefore produce information allowing URL rewriting to take place in the local portlet.
  • Proxying
    • Local portlet must forward resource requests, including calls to /xforms-server, to remote portlet.

Orbeon Forms configuration

Configure the following properties under RESOURCE/config/properties-local.xml:

<!-- Set URL of the servlet container running the Orbeon Forms servlet (used by submissions, etc.) -->
<property as="xs:anyURI"  name="oxf.url-rewriting.service.base-uri"              value="http://localhost:8080/orbeon"/>
<!-- Tell servlet to use wsrp rewriting strategy -->
<property as="xs:string"  name="oxf.url-rewriting.strategy.servlet"              value="wsrp"/>
<!-- Tell rewriting strategy to prepend path "foobar" to all paths (optional) -->
<property as="xs:string"  name="oxf.url-rewriting.wsrp.context"                  value=""/>
<!-- Set this to true so that submission with replace="all" don't cause HTML Form submission -->
<property as="xs:boolean" name="oxf.xforms.ajax-portlet"                         value="true"/>


Assume the following:
  • Orbeon Forms servlet deployed at:
    • http://orbeon.example.org/orbeon
  • Example of form page URL:
    • http://orbeon.example.org/orbeon/fr/orbeon/bookshelf/new

What the portlet must do

This is what your portlet must implement in order to talk to Orbeon Forms deployed as a remote portlet:
  • Load initial Orbeon Forms page:
    • Perform an HTTP GET on:
      • http://orbeon.example.org/orbeon/fr/orbeon/bookshelf/new/?orbeon-embeddable=true
      • The orbeon-embeddable=true ensures that Orbeon Forms returns an HTML DIV instead of a full HTML page. If you can handle a full HTML page, do not provide this parameter.
      • [SINCE: 201-10-18] Set the Orbeon-Container header to portlet.
    • Intercept the HTTP response.
    • Perform URL rewriting on the response:
      • Call org.orbeon.oxf.portlet.WSRP2Utils.write(MimeResponse response, String body, boolean encodeForXML) throws IOException)
        • response: portlet response to write to
        • body: intercepted body received from Orbeon forms
        • encodeForXML: true only if the response is an Ajax response returned by Orbeon Forms
        • This method is implemented in orbeon.jar
    • Include ( or insert it using Ajax) the result with rewritten URLs into your portlet page (done through response above)
  • Handle portal requests for resources (serveResource())
    • Any resource containing the portlet parameter orbeon.path must be forwarded to the remote portlet
      • Most incoming resources are HTTP GET (for CSS, JavaScript, images, etc.)
      • However POST requests (to /xforms-server) can occur when the form is sending Ajax requests to the remote portlet
  • Handle request from remote portlet to replace page content:
    • [TODO: document]
  • Handle intercepting "final submission" request
    • [TODO: document]

Cookie/Session handling

The remote portlet must keep a session. The local portlet must make sure that the remote portlet's JSESSIONID is properly extracted, stored, and sent back to the remote portlet upon subsequent HTTP requests.

Ajax portlets

See also Ajax Portlets.

When using the "ajax portlet" strategy in the web browser, e.g. with Dojo contentPane or other, to load portlet content into a DIV:
  • Set the oxf.xforms.ajax-portlet property to true
  • You may have to load orbeon Forms CSS resources outside of the DIV element
  • Orbeon Forms must unregister certain event handlers
    • xforms.js has some code for this
    • [TODO: more]