Configuring Options
Edit online

The Oxygen XML Web Author functionality that is common with the standalone distribution of Oxygen XML Editor/Author share the same options. This allows you to configure a consistent editing experience for all users.

Author Mode Options

Oxygen XML Web Author stores its options in an options.xml file. The file is located in the options folder of the Oxygen Data Directory.

If you are using the Oxygen XML SDK project, the bundle-options/oxygen-options/options.xml file is bundled with your resulting application and used to provide default options. This file is copied in the Oxygen Data Directory when the application starts if an options.xml file is not already present there.

There are multiple ways to configure these options:

  • Some of the options can be changed using the Administration Page in your web browser.
  • Use an options file exported from an Oxygen standalone application. To export the file, use the Options > Export Global Options menu action.
    Note: Archived options are unpackaged to the options folder only if an options.xml file is not already present.
  • Manually edit the options file. To learn more about the supported options and the file format, continue reading the section below.

Oxygen Standalone Options Supported by Web Author

Oxygen XML Web Author supports some of the options used by Oxygen XML Editor/Author. The supported options are applied for all Web Author users. The options file has the following format:
<?xml version="1.0" encoding="UTF-8"?>
<serialized version="18.1" xml:space="preserve">
  <map>   
    <entry>
      <String>author.show.comments</String>
      <Boolean>true</Boolean>       
    </entry>
  </map>
</serialized>
An additional entry should be added in this file for each option.
Table 1. Oxygen XML Author Options Supported in Oxygen XML Web Author
Key Type Description
additional.frameworks.directories See example entry below

An array of java.lang.String objects representing paths to the additional frameworks folders (may also contain editor variables).

ADMIN_PAGE_IS_DISABLED Boolean true to disable the Administration Page completely.
author.convert.external.content.on.paste Boolean

Option that controls whether or not the content pasted in Author mode should be converted to match the destination styles.
author.convert.external.content.space.preserve Boolean

Option that controls whether or not the content pasted in Author mode should be converted to match the destination styles in space-preserved elements.
author.format.compatibility Integer Possible values include: 0, 1, 2

0: Nothing special is done for compatibility purpose.

1: Do not break lines, do not indent.

2: Break lines only after elements displayed as blocks, do not indent.
author.format.compatibility Integer Use this option to control how line breaks are handled when a document is serialized.

0 (default value) - none.

1 - Do not break, do not indent.

2 - Break lines only after block elements, do not indent.
author.image.width.autoscale.limit Integer If set to a value greater than 0, images wider than this number of pixels will be resized. By default 1024.
author.show.comments Boolean Show the comment nodes in the author page.
author.show.processing.instructions Boolean Show the pi nodes in the author page.
auto.correct.double.quotes See example entry below If set, Web Author automatically replaces double quotes with the specified quotation symbols.
auto.correct.single.quotes See example entry below If set, Web Author automatically replaces single quotes with the specified quotation symbols.
autocorrect.feature.state Boolean Used to enable/disable the auto-correct feature.
autocorrect.use.suggeestions.from.spell.check.dicts Boolean Used to enrich the auto-correct suggestions with entries from spell checking dictionaries.
automatically.accept.certificates Boolean Option that controls if Oxygen will accept all HTTPS certificates.
default.xml.schema.version String The XML Schema version to use if it is not specified in the schema file (see schema version note). The default version is 1.0.
dita.fill.link.format.attribute Boolean Use true to force the insertion of the format attribute when inserting a link in DITA even when the attribute has a default value.
dita.fill.link.scope.attribute Boolean Use true to force the insertion of the scope attribute when inserting a link in DITA even when the attribute has a default value.
dita.fill.link.type.attribute Boolean Use true to force the insertion of the type attribute when inserting a link in DITA even when the attribute has a default value.
dita.ot.directory String The directory path to the default DITA OT installation.
editor.line.width Integer Used to define the number of characters after which a hard line-wrapping action is performed (default is 100).
http.max.simultaneous.connections.per.host Integer Limits the number of connections the HTTP client can open to the same server host.
http.proxy.direct String Comma-separated list of hosts for which the proxy is bypassed.
http.proxy.host String Proxy hostname or IP address.
http.proxy.password String Proxy password.
http.proxy.port Integer Proxy port.
http.proxy.set Boolean HTTP proxy uses manual configuration.
http.proxy.system Boolean "True" to detect HTTP proxy from system.
http.proxy.user String Proxy user.
http.read.timeout.seconds Integer An integer number that configures the timeout used when waiting for an HTTP request.
insertOnlyElementsFromCCList Boolean If set to true, the content completion list will only show elements that are valid at the current position.
Schematron_custom_language String The two-letter country code (for example: en,fr).
Schematron_language_option Integer

2 (default value) - The Schematron xml:lang value defined on the root of the schema will be used.

3 - The language attributes are ignored. All messages will be presented.

4 - A custom language defined by the option Schematron_custom_languagewill be used.
show.caret.position.info Boolean Use false to disable the tooltip popup that is normally displayed at the cursor position.
showAllPossibleElementsInCCList Boolean If set to true, the content completion list will show all the elements in the schema, even those that are not valid at the current position.
spell.check.options See example entry below Can be used to set some spell-checking options, including the default language used when no xml:lang attribute is set.
topic.content.refs.limit Integer The maximum number of references that can be contained within a DITA map to display it in the View Topic Content mode.
track.changes.initial.state Integer Option for track changes initial state.
  • 0 - Initial state stored in document.
  • 1 - Track changes always on.
  • 2 - Track changes always off.
undo.history.limit.v10.3 Integer The number of operations that can be undone. By default 200.
validate.as.you.type Boolean Use false to turn off the automatic validation.
validate.max.errors.number Integer The maximum number of validation errors that can be shown. Default value is 100.
WEBAPP_SHOW_ADMIN_PAGE_LINK Boolean true to display the admin page link on the dashboard.
Schema Version Note: To specify an XML Schema version (for example, 1.1) directly in the schema file, you need to add an attribute to the namespace declaration like this:
xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" vc:minVersion="1.1"

Examples of Using Options

Example entry for additional.frameworks.directories option:
<entry>
  <String>
   additional.frameworks.directories
  </String>
  <String-array>
    <String>
     /path/to/frameworks
    </String>
  </String-array>
</entry>
Example entry for auto.correct.single.quotes and auto.correct.double.quotes option:
<entry> 
  <String>auto.correct.single.quotes</String> <!–- or auto.correct.double.quotes  -->
  <autoCorrectQuotes>
    <field name="enabled">
      <Boolean>true</Boolean>
    </field>
    <field name="startQuote">
      <Character>‘</Character>
    </field>
    <field name="endQuote">
      <Character>’</Character>
    </field>
  </autoCorrectQuotes>
</entry>
Example entry for spell.check.options option: 
<entry>
  <String>spell.check.options</String>
  <spellCheckOptions>
    <field name="language">
      <String>de_DE</String>
    </field>
  </spellCheckOptions>
</entry>

Web Author-Specific Options

A small number of options are specific only to Oxygen XML Web Author and they can be configured in the WEB-INF/web.xml file. Each option is specified as a context-param element.

The following is a list of these options and their accepted values:
Option name Value Default Value Description
com.oxygenxml.loadBuiltinProtocolHandlers true/false True Controls whether or not the built-in handlers for HTTP/HTTPS and FTP/SFTP protocols are installed. Default value is true.
com.oxygenxml.validation.threads.no An integer number Half the number of cores on the server Configures the number of validation threads.
com.oxygenxml.webapp.datastore.docs.disk.expire Duration (*) 30d Indicates the delay after which inactive sessions are discarded.
com.oxygenxml.webapp.datastore.docs.disk.size An integer number 1,000,000 Indicates the number of inactive editing sessions that can be stored on disk.
com.oxygenxml.webapp.datastore.docs.memory.expire Duration (*) 2d Indicates the delay after which inactive sessions are stored on disk.
com.oxygenxml.webapp.datastore.docs.memory.size An integer number 10,000 Indicates the number of editing sessions stored in memory.

(*) - Duration is represented by an integer, followed by "d", "h", "m", or "s", representing days, hours, minutes, or seconds, respectively.

Example:

Here is an example of how to configure a context parameter:
<context-param>
  <param-name>com.oxygenxml.loadBuiltinProtocolHandlers</param-name>
  <param-value>false</param-value>
</context-param>

Custom Options for the Git Plugin

It is possible to configure a master account for the Git connector so that users do not have to login to edit documents. The following options can be set in the Oxygen XML Web Author options.xml file.
Option name Value Description
PLUGIN_CUSTOM_OPTIONS.git.enforced_user string The master account username
PLUGIN_CUSTOM_OPTIONS.git.enforced_pass string The master account password
PLUGIN_CUSTOM_OPTIONS.git.enforced_mail string The master account address
Example: The options.xml file would look like this:
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.git.enforced_user</String>
  <String>example_username</String>
</entry>
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.git.enforced_pass</String>
  <String>example_password</String>
</entry>
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.git.enforced_mail</String>
  <String>mail@example.com</String>
</entry>