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 Web Author Component integration project, zip the options.xml file and save it in the src/main/weapp/WEB-INF directory. During the deployment, this file is copied in the Oxygen Data Directory 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">
  <serializableOrderedMap> 
    <entry>
      <String>author.show.comments</String>
      <Boolean>true</Boolean>       
    </entry>
  </serializableOrderedMap>
</serialized>
An additional <entry> should be added in this file for each option.
Table 1. Oxygen XML Editor/Author Options Supported in Oxygen XML Web Author
Key Type Description
additional.frameworks.directories See example entry below the table

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

always.send.keepalive Boolean Option that controls whether or not keep-alive requests are sent to the server every 150 seconds. By default, the value is false. In this case, such requests are sent only for protocols that use the ro.sync.exml.plugin.lock.LockHandler (such as WebDAV).
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 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 the table If set, Web Author automatically replaces double quotes with the specified quotation symbols.
auto.correct.single.quotes See example entry below the table 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 the schema version note below the table). 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 that is bypassed by the proxy.
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 Schematron_custom_language option will be used.
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.
show.caret.position.info Boolean Use false to disable the tooltip popup that is normally displayed at the cursor position.
show.profiling.attributes Boolean Use false to disable the rendering of profiling attributes.
spell.check.options See example entry below the table 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.
com.oxygenxml.webapp.datastore.docs.disk.expire String (*) Indicates the delay after which inactive sessions are discarded. Default value is 3d.
com.oxygenxml.webapp.datastore.docs.memory.expire String (*) Indicates the delay after which inactive sessions are stored on disk. Default value is 12h.
(*) - The value is a duration, which is a string that is represented by a number, followed by "d", "h", "m", or "s" (days, hours, minutes, or seconds, respectively).
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"
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 using spell.check.options to setting the default language: 
<entry>
  <String>spell.check.options</String>
  <spellCheckOptions>
    <field name="language">
      <String>de_DE</String>
    </field>
  </spellCheckOptions>
</entry>
Example entry for using spell.check.options to disable the default Hunspell spell checker: 
 <entry>
  <String>spell.check.options</String>
  <spellCheckOptions>
    <field name="preferredChecker">
      <Integer>2</Integer>
    </field>
  </spellCheckOptions>
</entry>

Other Options Supported in the Options File

Oxygen XML Web Author supports some additional options that can be configured using the options.xml file.

Key Type Description
ADMIN_PAGE_IS_DISABLED Boolean true to disable the Administration Page completely.
WEBAPP_SHOW_ADMIN_PAGE_LINK Boolean true to display the admin page link on the dashboard.

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.

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 contain the following snippet:
<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>

Custom Options for the SharePoint Plugin

If your documents use absolute URLs to reference other resources (such as images or DITA conrefs), Oxygen XML Web Author considers them as external and does not use the current user account to retrieve them. As a result, they may not be displayed in the editor. To fix this problem, you need to set the following option in the Oxygen XML Web Author options.xml file. If you use SharePoint Online, this option is not necessary.
Option name Value Description
PLUGIN_CUSTOM_OPTIONS.sharepoint_domain_name string The domain name of the SharePoint installation.
Example: The options.xml file would look like this:
<entry> 
  <String>PLUGIN_CUSTOM_OPTIONS.sharepoint_domain_name</String>
  <String>sharepoint.my-company.com</String>
</entry>