JavaScript Embedding API
- [SINCE Orbeon Forms 2020.1]
- The Form Runner JavaScript Embedding API is a PE feature.
If you have your own application and would like to embed a form created with Form Builder:
- In all other cases, we recommend you use the JavaScript Embedding API described on this page. It offers the most flexibility, and will work irrelevant of the server-side technology you are using.
If you're using the JavaScript embedding API, chances are that your application isn't Java-based. This means that Orbeon Forms and your application are likely to be running on a different server or different port.
All browser requests, whether for the page of your app that uses the embedding API, or for Orbeon Forms resources, need to be made to the same server and port. It is your responsibility to setup that server so requests to Orbeon Forms are forwarded to the Orbeon Forms server, as shown in the diagram below. Exactly how to do so will depend on the server-side technology you are using. For instance:
- If you're using Microsoft IIS, you configure this with the IIS Manager, by creating a Reverse Proxy rule.
Network setup
You can identify the requests made to Orbeon Forms based on their path, which is typically
/orbeon. (With Java web apps, that first part of the path is referred to as the "context", and you can deploy Orbeon Forms on a context other than /orbeon, say /forms. However, in what follows, we'll just assume you've kept /orbeon.)When forwarding HTTP requests, you need to make sure the
JSESSIONID cookie is properly forwarded. You can for instance check this with the Chrome Dev Tools using the Network tab. Make sure that:- 1.The first time the browser makes a request to Orbeon Forms, that is with a path starting with
/orbeon, the response setsJSESSIONIDcookie. - 2.In every subsequent request made to Orbeon Forms, that
JSESSIONIDcookie set earlier is sent by the browser, and the server doesn't in turn set anotherJSESSIONIDin the response. (I.e. the value of theJSESSIONIDcookie sent by the browser to the server shouldn't change for the duration of the session.)
Users will be accessing your application, so you can continue to authenticate them as usual. If you are only requiring authentication for certain paths, you'll just want to make sure you also include everything under
/orbeon. If you don't require users to be authenticated to access that path, they might be able to bypass the authentication you've put in place for your app, say under /app, and instead access directly Orbeon Forms making requests to paths under /orbeon.If your users are authenticated, you'll most likely want Orbeon Forms to also know about who the current user is, so Orbeon Forms can control the access to forms and enforce permissions. In the context of the JavaScript embedding API, this is typically done by your having your forwarding code pass information about the current user to Orbeon Forms using headers, and setting up Orbeon Forms to use this information it receives in what is called the header-driven method (you will find all the details on what headers you need to pass, and how setup Orbeon Forms to use header-based authentication on that page).
In the page where you want to embed a form, include the following JavaScript by adding this element inside the page's
<head>:<script
type="text/javascript"
src="/orbeon/xforms-server/baseline.js?updates=fr"></script>
You embed a form in the page by calling the following API:
ORBEON.fr.API.embedForm(
container,
context,
app,
form,
mode,
documentId,
queryString,
headers
);
Parameter | Optional | Type | Example | Description |
|---|---|---|---|---|
container | No | HTML element | | DOM element you want the form to be placed in |
context | No | String | "/orbeon" | Context where Orbeon Forms is deployed, typically "/orbeon" |
app | No | String | "human-resources" | App name |
form | No | String | "job-application" | Form name |
mode | No | String | "new" | Either "new", "edit", or "view" |
documentId | See point 1 below | String | | For modes other than new, the document to be loaded |
queryString | Yes | String | "job=clerk" | Additional query parameters |
headers | Yes | new Headers({ 'Foo': 'bar' }) | Additional HTTP headers; see point 2 below |
- 1.The
documentIdparameter is mandatory for modes other thannew, and must beundefinedwhen the mode isnew. Fornew, if you don't need to pass ny of parameters afterdocumentId, you can just omit thedocumentIdand all subsequent parameters in your call toORBEON.fr.API.embedForm(); otherwise, you must explicitly passundefinedas the value ofdocumentId. - 2.The
headersparameter is supported [SINCE Orbeon Forms 2021.1.1]. You can also access the value of such headers in the form you're embedding with the functionxxf:get-request-header().
[SINCE Orbeon Forms 2022.1]
embedForm() returns a JavaScript Promise object. This allows you to know when the embedding has succeeded or failed. For example:ORBEON.fr.API.embedForm(
document.getElementById("my-container-element"),
"/orbeon",
"human-resources",
"job-application",
"new"
)
.then(() => {
console.log("`embedForm()` successfully loaded the form");
})
.catch((e) => {
console.log("`embedForm()` returned an error");
console.log(e);
});
Note that with earlier versions,
embedForm() always returned the JavaScript undefined value.To remove a form that you embedded earlier, call:
ORBEON.fr.API.destroyForm(container);
If you want to replace a form A shown in a given container by another form B, you can just do so by calling
ORBEON.fr.API.embedForm() a second time for form B, and don't need to explicitly first call destroyForm().[SINCE Orbeon Forms 2022.1] Like
embedForm(), destroyForm() returns a JavaScript Promise object. See the above section about embedForm() for more information about how to use the returned Promise.Last modified 2mo ago