Java Embedding API
Availability
[SINCE Orbeon Forms 4.7]
The Form Runner Java Embedding API is a PE feature.
Rationale
The intent is to allow Java (and other Java Virtual Machine (JVM)-based languages) applications to easily embed forms produced with Form Builder within other pages.
Configuration
Basic configuration
Your web application
Your own web app does the following:
Include
orbeon-embedding.jar
andslf4j-api-1.7.7.jar
underWEB-INF/lib
. Both are included inorbeon-embedding.war
which ships with Orbeon Professional Edition (PE) only.Setup the filter in your
web.xml
per the snippet below.Call the embedding API when producing a page, as done in the example below.
The page you do the embedding from must:
Start with
<!DOCTYPE html>
, so your page is in full standards mode. Without this, you will notice that some CSS fails to apply as it should.Use the UTF-8 character encoding for the HTML response. This is a typical filter configuration:
[SINCE Orbeon Forms 2023.1] If you are using Orbeon Forms 2023.1 or newer, and are running a servlet container that uses the Jakarta Servlet API (e.g. Tomcat 10+, WildFly 27+), you need to use the org.orbeon.oxf.fr.embedding.servlet.JakartaServletFilter
servlet filter class instead of org.orbeon.oxf.fr.embedding.servlet.ServletFilter
.
And here is an example of embedding a form from a JSP page:
The Map<String, String>
allows passing a Java Map
of HTTP header name/value pairs. These are passed to Form Runner when loading a form. Form Runner can access HTTP headers using the xxf:get-request-header()
XPath function.
[SINCE Orbeon Forms 2023.1] The request
parameter can be either of type javax.servlet.http.HttpServletRequest
or of type jakarta.servlet.http.HttpServletRequest
.
Form Runner configuration
You deploy Form Runner in a separate web app, which can be located in the same servlet container as your web app or in a separate or even remote servlet container.
Form runner must use "combined resources" to work. This is the case by default in prod
mode (see Run Modes), but if you happen to have setup Orbeon Forms in dev
mode, make sure to add this property in your properties-local.xml
:
Passing information about the current user
You can pass information about the current user to Orbeon Forms through headers. For this:
Enable header-based authentication by editing the
properties-local.xml
in your Orbeon Forms web app, adding:[SINCE Orbeon Forms 2020.1] You need to enable sticky authentication headers, adding:
Back to your web app, pass the current user's username as the value of the
My-Username-Header
header, through a map you provide as the last argument to your call toAPI.embedFormJava()
:
If needed, you can also pass the user's roles and group through additional headers.
Logging configuration
The embedding JAR uses SLF4J for logging. If your application already uses SLF4J and already has slf4j-api.jar, you can remove the one provided by Orbeon under WEB-INF/lib
. Otherwise, you must keep slf4j-api.jar in your application's WEB-INF/lib
folder.
Optionally, and in addition, if you want to actually configure logging for the embedding library, you must add a logging adapter for SLF4j and the appropriate configuration file, for example for log4j. See the sample configuration file under WEB-INF/classes/log4j.properties.template
. Here are example JAR files which work with Orbeon Forms 2018.2:
slf4j-log4j12-1.7.25.jar
log4j-1.2.17.jar
HTTP client configuration
The embedding implementation communicates with the rest of Orbeon Forms via HTTP or HTTPS. In general, you probably won't have to change this configuration. By default, it is as follows:
Details about the meaning of these parameters are available here.
HTTP server configuration
You can enable HTTP gzip compression between the embedding implementation and Form Runner. For example, with Tomcat:
Usage scenarios
In your Java web application, any page covered by the servlet filter can call the embedding API. You can have a single page calling a single form, or several pages each calling a different form. Or, pages can (based on URL parameters, internal application state, etc.), embed a form dynamically.
The embedded form cannot navigate in place to another form or mode (such as Review).
However, it can save form or send form data as it does in the standalone case. It can also run custom processes which can redirect the entire embedding page with navigate
, or run JavaScript functions with navigate(uri = "javascript:alert('Done!')")
. This allows communicating with the embedding application.
Form Builder embedding
[SINCE Orbeon Forms 2016.3]
In addition to published forms, you can embed Form Builder: just use orbeon
and builder
as Form Runner app/form names.
The embedding application can set the size the embedded Form Builder <div>
element via CSS or JavaScript, and Form Builder will adjust its size accordingly:
The Form Builder "New" and "Summary" buttons are hidden when Form Builder is embedded, as navigating between pages is not yet supported when embedding.
How it works
The embedding implementation:
makes an HTTP or HTTPs request to Form Runner to retrieve the HTML to embed when you call the API
appropriately rewrites URLs in the HTML returned by Form Runner
keeps track of session and other cookies
proxies requests for resources, Ajax calls and file uploads to Form Runner
Caveats
Make sure that you do not disable combined resources. Specifically, you cannot have the following in your properties-local.xml
:
If you do have this property, make sure you remove it, comment it out, or explicitly set:
Limitations
Using non-combined resources is not supported (so
oxf.xforms.combine-resources
must be set totrue
, which is the default).Embedding multiple forms is known to work in some cases, but has known issues so we don't recommend doing this (see #1854)
Navigation between pages, such as the Form Runner Edit and Review pages, is not supported. Because of this:
The
send
action within a process does not supportreplace="all"
.Autosave is not supported, as the prompts made to users, whether when creating data or editing existing data, make use of page navigation. If some of the users are logged in, you should probably disable the autosave feature.
See also
Blog post: Form Builder embedding
Last updated