Orbeon Forms User Guide

Other Processors

1. File Processor

The File processor allows you to delete files on disk. In the future, it may be enhanced to provide more actions such as renaming files, moving files, etc.

1.1. Inputs and Outputs

Type Name Purpose Mandatory
Input config Configuration Yes

The config input contains a single delete element. In turn, it contains a file element which specifies the name of the file to delete, and an optional directory element containing a base directory against which the file name is resolved.

If the file exists and is writable, the processor attempts to delete it. Otherwise, no attempt is made. If an attempt is made and deleting fails, an exception is raised.

1.2. Example

The following is an example of a pipeline running the File Processor in order to delete a file called SomeImpossibleFileName.jpg present under the C:/TEMP directory.

<p:config xmlns:oxf="http://www.orbeon.com/oxf/processors"><p:processor name="oxf:file"><p:input name="config"><config><delete><file>SomeImpossibleFileName.jpg</file><directory>C:/TEMP</directory></delete></config></p:input></p:processor></p:config>

2. Resource Server

The Resource Server serves resources such as images, CSS stylesheet or other static files. Resources are sent to the HTTP response untouched, and the HTTP cache control headers are set.

2.1. Config Input

The config input contains a single url element containing an absolute URL. The URL can be any URL supported by your platform, in particular URLs with the following protocols:

  • file
  • http
  • oxf (to access Orbeon Forms resources)

The Resource Server supports the deprecated use of a config input containing a single path element representing the absolute Resource Manager path of the file to serve. Since the url element also allows to access to Orbeon Forms resources, it is recommended to use it instead of path.

2.2. MIME Types Input

The mime-types input contains a list of patterns and MIME Media Types. This mapping list determines which content-type header to send to the browser. The patterns are case-insensitive. Orbeon Forms is bundled with a default mapping file under the URL oxf:/oxf/mime-types.xml. You can create your own mapping to suit your needs. The RelaxNG schema is provided below.

<element name="mime-types" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" xmlns="http://relaxng.org/ns/structure/1.0"><oneOrMore><element name="mime-type"><element name="name"><data type="string"/></element><oneOrMore><element name="pattern"><data type="string"/></element></oneOrMore></element></oneOrMore></element>

2.3. Example

The example below shows the Resource Server configured to send a PNG image file with the appropriate MIME type.

<p:processor name="oxf:resource-server"><p:input name="mime-types"><mime-types><mime-type><name>image/png</name><pattern>*.png</pattern></mime-type></mime-types></p:input><p:input name="config"><url>oxf:/images/logo.png</url></p:input></p:processor>

3. Identity Processor

The Identity processor is one of the simplest processors of Orbeon Forms: it simply copies the content of its data input to its data output. While at first this doesn't seem like a very useful feature, it actually can be very convenient, for example in the following scenarios.

3.1. Embedding XML Documents

XML documents can be embedded within pipeline inputs. When you want the same document to be passed to the input of multiple processors in a pipeline, instead of duplicating it and embedding it in every input, you can use the Identity processor: embed the document in the data input of the Identity processor, assign an id to the output of the Identity processor, and reference that id from other inputs you want to feed with that document.

<p:config><!-- Embed employee data --><p:processor name="oxf:identity"><p:input name="data"><employees><employee><first-name>Joe</first-name><last-name>Dalton</last-name></employee><employee><first-name>Averell</first-name><last-name>Dalton</last-name></employee></employees></p:input><p:output name="data" id="employees"/></p:processor><!-- Apply a first transformation on the employee data --><p:processor name="oxf:xslt"><p:input name="config" href="oxf:/transform-1.xsl"/><p:input name="data" href="#employees"/><p:output name="data" id="result-1"/></p:processor><!-- Apply a second transformation on the same employee data --><p:processor name="oxf:xslt"><p:input name="config" href="oxf:/transform-2.xsl"/><p:input name="data" href="#employees"/><p:output name="data" id="result-2"/></p:processor><!-- ... --></p:config>

3.2. Aggregating and Modifying Documents

Pipeline inputs support aggregation with the aggregate() function, as well as the XPointer syntax. The Identity processor can then be used to aggregate or otherwise modify existing documents in a pipeline, for example before sending a result to a pipeline output.

<p:config><p:param type="output" name="data"/><!-- ... --><!-- Assuming the XSLT transformations in the previous example, transform the two results and send them to the data output --><p:processor name="oxf:identity"><p:input name="data" href="aggregate('result', #result-1#xpointer(/*/*), , #result-2#xpointer(/*/*[position() *lt; 10]))"/><p:output name="data" ref="data"/></p:processor></p:config>

4. Debug Processor

Note

In most cases you do not need to use the oxf:debug processor: you can instead use the debug attribute on processor and pipeline inputs and outputs.

The oxf:debug processor logs XML documents to the Orbeon Forms log output. It has 2 inputs: data contains the XML document to log, and config has a config root element that contains a message typically be used to describe the XML document. The data output document is the exactly the same as the data input document. Consequently the debug processor can be easily inserted in a pipeline to log the XML data flow at a given point.

For instance, the processor can be called with:

<p:processor name="oxf:debug"><p:input name="config"><config>Employee</config></p:input><p:input name="data"><employee><firstname>John</firstname><lastname>Smith</lastname></employee></p:input><p:output name="data" id="emp"/></p:processor>

This will generate the message: 

Employee:

    <employee>
        <firstname>John</firstname>
        <lastname>Smith</lastname>
    </employee>

Using debug attributes in pipelines is a shortcut for inserting the oxf:debug processor in the pipeline: the oxf:pipeline processor will automatically insert a oxf:debug processor when encountering debug attributes. By changing processors.xml you can map the oxf:debug processor to your own "Debug processor". If you decide to implement your own oxf:debug processor, note that it must have the same interface as the default oxf:debug processor that comes with Orbeon Forms.

5. Redirect Processor

The Redirect Processor allows redirecting or forwarding the execution to a new URL:

  • Client-side the browser is redirected to another URL. Typically, for a Servlet environment, the sendRedirect() method is called on the HTTP response object.

    If the redirection URL is an absolute path (e.g. /hello) then it is interpreted as a path relative to the Orbeon Forms Servlet context (i.e. if your Orbeon Forms WAR file is under /ops, then the resulting path is /ops/hello). For other purposes, including redirecting to a path within the same Servlet container but outside the Orbeon Forms WAR context, you have to use an absolute URL complete with scheme and host name.

  • Server-side: a server-side forward is executed. Typically, for a Servlet environment, the forward method is called on a Servlet request dispatcher.

The processor's data input must conform to the following Relax NG schema:

<element name="redirect-url" xmlns="http://relaxng.org/ns/structure/1.0"><interleave><optional><element name="server-side"><choice><value>true</value><value>false</value></choice></element></optional><element name="path-info"><text/></element><optional><element name="parameters"><zeroOrMore><element name="parameter"><element name="name"><text/></element><oneOrMore><element name="value"><text/></element></oneOrMore></element></zeroOrMore></element></optional></interleave></element>

The optional boolean server-side element determines whether a server-side forward is performed. The default is false.

This example creates a processor that redirects the browser to /login?user=jsmith:

<p:processor name="oxf:redirect"><p:input name="data"><redirect-url><path-info>/login</path-info><parameters><parameter><name>user</name><value>jsmith</value></parameter></parameters></redirect-url></p:input></p:processor>
Note

It is recommended, whenever possible, to use the Page Flow Controller to perform page redirections within a Orbeon Forms application. The Page Flow Controller provides a much higher-level abstraction of the notion of redirection than the Redirect processor.