Overview
Orbeon Forms is mainly configured via properties. A property is made of:
- a type, such as
xs:boolean
a name, such as oxf.resources.versioned- a value, such as
true
- optionally, a processor name, such as
oxf:request, which refers to an XPL processor name
The basic format looks like this:
<property
as="xs:boolean"
name="oxf.resources.versioned"
value="true"/>
Some properties support wildcards, for example:
oxf.fr.persistence.app.uri.*.*.*
Properties fall in two categories:
- standard: defined by Orbeon Forms
- custom: defined by programmers
All standard properties have standard values defined in built-in property files, described below, and can be overridden when needed. They are documented in sub-pages.
In general, here is how you deal with properties:
- look up the documentation for a given property
- if needed, override it in one of the
properties-local*.xml files under your web app's WEB-INF/resources/config
Property files are reloaded every time they are changed (after a short delay), however some properties are taken into account only when the server is first started.
Overriding properties
To override properties, you create one of the following
files under your web app's WEB-INF/resources/config:
properties-local.xmlproperties-local-dev.xml
dev run
mode only [SINCE 2012-05-03]- properties in this file also override properties in properties-local.xml
properties-local-prod.xml
prod run mode only [SINCE 2012-05-03]- properties in this file also override properties in properties-local.xml
Properties defined in these files override properties in the standard property files.
By following this practice, you avoid modifying files that ships with Orbeon Forms, which
makes upgrading to newer versions of Orbeon Forms easier.
If you don't already have one of the properties-local*.xml files:
- copy any or all of the following files, as required:
properties-local.xml.template to properties-local.xml
properties-local-dev.xml.template to properties-local-dev.xml
properties-local-prod.xml.template to properties-local-prod.xml
- add your own properties to the resulting XML files
NOTE: The *.template files are just templates for the actual property
files. We don't recommend you modify the template files themselves.
Wildcards in properties
Property names may be defined
using wildcards. A property name is assumed to be built as a series of path elements separated by . characters. A path element may contain a * character instead of an actual path element value.
<property
as="xs:anyURI"
name="oxf.fr.persistence.app.uri.*.*.*"
value="/fr/service/exist"/>
<property
as="xs:anyURI"
name="oxf.fr.persistence.app.uri.*.*.data"
value="/fr/service/oracle"/>
<property
as="xs:anyURI"
name="oxf.fr.persistence.app.uri.orbeon.builder.form"
value="/fr/service/resource"/>
In this example:
- If the property name
oxf.fr.persistence.app.uri.orbeon.builder.form is
requested, the value /fr/service/resource is
returned (exact match).
- If the property name
oxf.fr.persistence.app.uri.orbeon.foobar.data is
requested, the value /fr/service/oracle is
returned, because the path elements orbeon, foobar match wildcards, and data matches the last path element.
- If the property name
oxf.fr.persistence.app.uri.orbeon.foobar.form is
requested, the value /fr/service/exist is
returned, because the path elements orbeon, foobar and form all
match wildcards.
This allows creating
hierarchical properties with generic defaults and more specific values.
In general these are used with
Form Runner or Form Builder and in these cases:
- The first wildcard matches a forms "application name"
- The second wildcard matches a forms "form name"
There is a precedence order
with wildcards:
- an exact match is checked first and always wins if found
- a wildcard match is done then, starting from the left
So:
foo.bar wins over *.*, *.bar,
and foo.*foo.* wins over *.bar
Built-in property files
The default values for those properties are provided in the following files, which are stored in orbeon-resources-private.jar:
config/properties-dev.xml[SINCE 2012-05-03]- root of
dev mode properties
config/properties-prod.xml[SINCE 2012-05-03- root of
prod mode properties [SINCE 2012-05-03]
config/properties-base.xml- base Orbeon Forms properties
config/properties-xforms.xmlconfig/properties-form-runner.xmlconfig/properties-form-builder.xml
In general, you shouldn't modify these files.
Properties types
Properties have a documented type, which must be one of the following:
xs:stringxs:booleanxs:integerxs:anyURIxs:QNamexs:datexs:dateTimexs:NMTOKENS
Defining your own properties
In addition to the standard properties, you can define your own properties. You can then access them
from:
- XPath expressions in XForms with
xxforms:property().
- XPath expressions in XPL with
p:property(),
where the prefix p is mapped to the
namespace http://www.orbeon.com/oxf/pipeline.
- XPath expressions in XSLT with
pipeline:property(), where the prefix
pipeline is mapped to namespace java:org.orbeon.oxf.processor.pipeline.PipelineFunctionLibrary.
In all cases, for security reasons, those functions won't return the value of properties that contain the string
"password" in the name of the property.
Properties subsystem initialization
The properties sub-system is initialized after the Resource Manager (the properties being read like any other Orbeon Forms resources). By default, the following top-level URL is loaded:
- web app in
prod mode: oxf:/config/properties-prod.xml [SINCE 2012-05-03]
- web app in
dev mode: oxf:/config/properties-dev.xml [SINCE 2012-05-03]
- web app (prior to 2012-05-03): oxf:/config/properties.xml
- command-line: oxf:/properties.xml
Property files support inclusions via XInclude. This is the mechanism used by Orbeon Forms to load all the secondary property files.
|
|
