Edit online

Configuring Options

The Oxygen XML Web Author shares the same options as the standalone distribution of Oxygen XML Editor/Author for various functionality that is common to both products. This allows you to configure a consistent editing experience for all users.
Important: Whenever you change options for Oxygen XML Web Author, it is recommended that you restart the server to ensure the changes get applied.

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 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

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

Controls whether or not the content pasted in Author mode should be converted to match the destination styles in space-preserved elements.
author.display.references.expanded Boolean Controls whether or not referenced content is expanded and displayed in the visual editor.
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.
block.cross.protocol.author.references Boolean If set to true (default value), Author references (for example DITA conref) are blocked if their target URL has a different protocol than the URL of the file that contains the referencing element.

block.cross.protocol.system.entities

 Boolean If set to true (default value), XML external entities are blocked if their target URL does not have the same protocol as the URL of the file where the entity is declared.
code.insight.insert.required.attributes Boolean If set to true, required attributes will be automatically generated for elements inserted using content completion. The default value is false.
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.
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.separator.6.1.1 String Specifies the line separator to be used when saving the document:
  • &amp;#xa; - Linux-style line separator.
  • &amp;#xd;&amp;#xa; - Windows-style line separator.

If not specified, the line separator specified by the line.separator system property is used.
editor.line.width Integer Used to define the number of characters after which a hard line-wrapping action is performed (default is 100).
enable.file.protocol Boolean If set to false (default value), users cannot open resources (documents, images, etc.) whose URL uses the file protocol.
expand.map.refs.in.author.page Boolean Use false to avoid expanding DITA maps references when a DITA map is opened in the editor. The default value is true.
http.default.keepalive.timeout Integer The default Keep-Alive timeout for HTTP connections (for cases when the server does not advertise any timeout).
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.
ignore.absolute.file.system.entities Boolean If set to true (default value), system entities with an absolute URL (file://URL) are ignored.
ignore.extenal.entities.outside.frameworks Boolean If set to true (default value), XML external entities are resolved only if their target is inside a framework folder in the DITA-OT folder.
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.
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.
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 the table Can be used to set some spell-checking options, including the default language used when no @xml:lang attribute is set.
tagless.editor.tags.display.mode Integer

The default display mode for rendering XML tags in Author mode. Users can override this configuration in Options > Preferences > Editor > Edit Modes > Author. To override the user preference, the tags-mode URL parameter can be used.

Possible values:

0 - Full tags.

1 - No tags.

2 - Block tags.

3 - Partial tags (default).

4 - Full tags with attributes.

5 - Inline tags.
topic.content.refs.limit Integer The maximum number of references that will be expanded in a DITA map when it is opened.
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.
trusted.hosts See example entry below the table A string array property that can be used to specify patterns to match trusted hosts.
undo.history.limit.v10.3 Integer The number of operations that can be undone. By default 200.
untrusted.host.connection.behavior String Controls the behavior when a connection to an untrusted host is attempted. It is a string property with 3 possible values:
  • deny - The connection is denied (recommended).
  • log - The connection is allowed and the host name appears in the logs.
  • auto - The connection is denied if it is initiated by untrusted code (such as an untrusted Schematron file).
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.
author.skip.inner.entity.refs.expansion Boolean By default, the expansion of internal entities within other internal entities defined in an internal DOCTYPE is turned off. This is done to prevent denial of service attacks. Additionally, the loading of XML documents that contain a large number of entity references may be restricted. However, it is possible to disable this setting for specific server installations.
(*) - 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 the additional.frameworks.directories option:
<entry>
  <String>
   additional.frameworks.directories
  </String>
  <String-array>
    <String>
     /path/to/frameworks
    </String>
  </String-array>
</entry>
Example entry for the auto.correct.single.quotes and auto.correct.double.quotes options:
<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>
Example entry for the trusted.hosts option:
<entry>
  <String>trusted.hosts</String>
  <String-array>
    <String>*.oxygenxml.com</String>
    <String>*.w3c.org</String>
  </String-array>
</entry>

Web Author-Specific Options

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

Option name 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.
WEBAPP_ALLOW_EDIT_PROFILING_ATTRIBUTES String true to always show the "Edit Profiling Attributes" contextual menu action, false to never show it, and auto to show it only for DITA XML maps and topics. By default, the value is auto.
force.cookies.samesite.none Boolean true to force cookies to be set with the SameSite=None attribute and the Secure attribute for cases where it is unavoidable to serve Oxygen XML Web Author on a hostname that is different from the parent web application.
Example: The options.xml file would look like this:
<entry> 
  <String>force.cookies.samesite.none</String>
  <Boolean>true</Boolean>
</entry>

Other Web Author Configurations

A small number of configurations, specific only to Oxygen XML Web Author, can be configured in the WEB-INF/web.xml file. Each configuration is specified as a <context-param> element.

The following is a list of these configurations and their accepted values:
Key Value Default Value Description
com.oxygenxml.loadBuiltinProtocolHandlers Boolean 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 log in 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
PLUGIN_CUSTOM_OPTIONS.github.size_in_megabytes_for_a_read_file string The maximum allowed size for uploaded images (default value is 50M)
Example: The options.xml file would 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>
<entry>
  <String>PLUGIN_CUSTOM_OPTIONS.github.size_in_megabytes_for_a_read_file</String>
  <String>20</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>

Custom Options for the Outline Plugin

Option name Value Description
PLUGIN_CUSTOM_OPTIONS.outlinePlacement string Specifies which side of the interface that the Outline pane is placed. Accepted values are: left or right.

Impose a Set of Options Using a Plugin

A set of sample plugins can be found at https://github.com/oxygenxml/web-author-sample-plugins. It contains a JavaScript-based sample plugin called web-author-impose-options that provides an example of how you can impose a set of options for Oxygen XML Web Author.