This page is for programmers interested in the nitty-gritty details of how Orbeon Forms can be embedded in portals or other applications.
Often times, Orbeon Forms integrators wish to embed Orbeon Forms within a portal or another application. Orbeon Forms offers some support for this, but does not necessarily have a one-size-fits-all solution. This page is meant to help you better understand what is involved to make such as setup work.
Here by "embedding" we don't mean shipping Orbeon Forms with something else. Rather we mean setting up an application to work with Orbeon Forms such as a page/form rendered by Orbeon Forms appears embedded within that application's page.
Here "proxying" means that Orbeon Forms runs as a separate entity, typically connected via HTTP. It could be on the same app server/container, or even in a separate machine. So for example:
NOTE: Proxying is a way to achieve embedding. It's not the only way: for example when the Orbeon Forms full portlet is used, there is no proxying going on.
URL rewriting means that in HTML or XML produced by Orbeon, you replace (rewrite) some URLs before sending that HTML or XML to the client.
For example, within a Java portlet container, a form submission must reach a specific portlet, not a regular web application running in the container.
Orbeon Form expects that if it produces a page's HTML within a given Java servlet session, then later incoming Ajax requests address the same session. This means in general that the
When Orbeon Forms runs standalone, it produces a full HTML page. This includes HTML <html>, <head> and <body> elements. When Orbeon Forms produces HTML to be embedded into a portlet or another application, it produces an HTML fragment, rooted in a <div> element instead. This is because you can't simply embed a full HTML document within another. For any Orbeon page, you can enable the production of an HTML fragment by appending the
This produces a fragment that looks like this:
The fragment is produced by an XSLT stylesheet set via the
When embedding Orbeon Forms, you should always set the
NOTE: Below paths starting with /orbeon denote that Orbeon Forms is installed under the
Orbeon Forms needs the following resources:
In Ajax mode, additionally:
This means that the URLs seen by the browser must, directly or via proxying, reach Orbeon Forms.
The Orbeon XForms Server responds at the path /orbeon/xforms-server. It does the following:
Any access to the XForms Server must include the proper session cookie.
After an Orbeon Forms form is loaded in the browser, the user can interact with it. As that happens, the form typically needs to talk back to the XForms Server, via two means:
Ajax requests use the URL of the XForms Server.
For a given page, Orbeon Forms generates an action attribute with the URL of the current page as known by Orbeon. For example, if you load this standard Orbeon Forms page:
Then that's also the value placed in the <form> element:
The POST method is always used for this.
NOTE: In some modes, instead, the URL is
Using XForms, there are 2 ways of navigating to a new page:
This translates on the client to:
This behaves as if the user had entered the given URL in the browser URL bar. This case is rare, and can even be disabled.
In this case:
This describes the case of a JSR-168/286 portlet with a hypothetical proxy portlet, similar to the Form Runner Liferay Proxy Portlet.
Say URL rewriting is NOT performed. This URL will be present in the browser:
Unless there is an
With a JSR-286 container, resource URLs can be rewritten to portlet resource URLs, and the proxy portlet can forward the request to Orbeon.
With a JSR-168 container, resources cannot go through the portlet, so either a proxy servlet must be used, or the Orbeon Forms servlet must be deployed under /orbeon.
This is an important one.
Imagine, in particular in Noscript mode, that the HTML <form> action URL is not rewritten. Its value is, for example:
When the user clicks a button, the browser submits the whole page to that URL, which belongs to Orbeon Forms. Orbeon Forms produces a response which does not include the portal's header, footer, decorations, etc. In effect, the user has left the portal.
What needs to be done here is that the URL must be rewritten to be a portlet action URL. If this is done, the URL as seen in the browser is a URL encoded by the portal. When the HTML form is submitted to that URL, the portal can:
The data flow here is interesting:
This describes the scenario where the form is embedded within an application which is not a portal.
TODO: to possibilities for updates:
In a very simple case, the HTML returned by Orbeon could simply be parsed for URLs, in particular the <form action=""> attribute.
A better way, used by the Form Runner proxy portlet, is to put the Orbeon server in a special mode, where it encodes all URLs via a special WSRP-inspired scheme of markers. The portlet can then efficiently parse the resulting HTML for such markers, and rewrite URLs as it goes.
[SINCE: 2012-05-14] When Orbeon Forms receives a
This header must be set on all requests for pages, HTML, and CSS.
NOTE: Between 2011-10-18 and 2012-05-14, the header was named Orbeon-Container instead of Orbeon-Client. It was renamed for clarity.
Orbeon Forms has a class which helps deal with WSRP encoding: WSRPURLRewriter.scala.