Umbrella: Easy embedding of forms

[ebruchez]

Related bugs

• Server-side Form Runner embedding #1808
• Client-side Form Runner embedding #1577

What is already supported

We want to make it easy to embed Form Runner forms within another application. Right now, we support:

• Simply linking to pages produced by Orbeon Forms. (Pages produced by Orbeon Forms can be styled and XSLT can be used to add elements to the page, like top navigation bar, or footer.)
• Using the Liferay portal, in which Orbeon Forms can be deployed as a portlet.

Approaches

In addition, we could provide the capability for forms to be included into existing pages:

• On the server – A number of customers have done this one their own, but this is tricky for customers to implement and for Orbeon to support. The idea here would be to offer a built-in way to do this, for instance on the Java platform.
• On the client – Years ago we had a prototype for something like this, called the Ajax Portlet (project, doc). This was removed in 3.9. But there is demand for this, and we want a good and easy to use solution.

Embedding from the server [IMPLEMENTED]

To get this right, we need:

1. To call Orbeon Forms to get the initial HTML <div> to embed in the page.
   • If we already have an Orbeon Forms JSESSSIONID saved in the session, we send it to Orbeon Forms.
   • If a JSESSSIONID is set in the response, we save it in the session.
2. The server to proxy Ajax and resources (CSS, JavaScript, images) requests to Orbeon Forms.
   • We add/replace the JSESSSIONID with the one saved in the session.
3. For submission replace="all", we could support just embedding the result. (If users want the whole page to be replaced, then they can use an xf:load.)

For the Java platform, this could be implemented with a filter:

1. For the above point 1, it would run after the app, and replace a special tag, e.g. <fr:form uri="app/form/new">.
2. For the above point 2, it would intercept certain paths and do the proxying to Orbeon Forms.
3. For the above point 3, it would notice then the request is an Orbeon Forms submission replace="all", proxy the submission, get result, run the app, and replace the <fr:form> with the result from the submission.

Embedding from the client

To get this right, we need:

• Initial content load must make sure JavaScript and CSS are loaded properly.
• Identifiers might have to be namespaced as we do in a portlet context.
• Page navigation must be handled. There are two possibilities:
  • Either the current page is replaced entirely and reloaded.
  • Or just the section under the <div> is replaced (JS and CSS must be handled properly too).

From an API perspective, ideally it should just be a small JavaScript library. Maybe even no library at all for the initial load of the content. But you could imagine a JS API being helpful to do things such as "load such and such form now". In the "future future" Web components might help us do with this in a really clean way.

The main requirement is for this to work with Form Runner. We don't really have a need for this to work with generic XForms. But if that works too, that is obviously fine. Also, embedding Form Builder is not a requirement.

[ebruchez]

On embedding from the server:

• This is a proxy which would be similar to what the proxy portlet (source) does.
• If there is any replace="all" and we in fact replace the embedded content only, the issue of CSS/JavaScript clean-up arises as in the case of the client embedding.

On embedding from the client:

• If the content of the <div> is replaced, there is a need to properly clean-up JavaScript and CSS definitions. Right now it's unclear what xforms.js and XBL components might leave behind. It would be valuable and sane to spend a bit of time evaluating this.

A note on style: we are already reasonably sandboxed as we use the orbeon class around.

We should do create clear embedding scenarios to make it clear what is covered. For example:

1. Embedding a single form in a host application's page
   • host application embeds form acme/order
   • form shows on page with host application's header, footer, and styles
   • embedded form mostly shows with the Orbeon Forms L&F, including Bootstrap
   • user fills out form without leaving host app page
   • when completing, user uses "Send" button
     • either a confirmation dialog shows
     • or there is replacement of the embedded form with confirmation content
     • or there is navigation of the whole page to another host app page
2. ...

[avernet]

+1 form customer for the server-side part.

[ebruchez]

First phase:

• don't handle replacing content
• implement filter and maybe API