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.memory.expire	String (*)	Indicates the delay after which inactive sessions are disposed from memory. 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: &#xa; - Linux-style line separator. &#xd;&#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).
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	Set value to `true` to disable the Administration Page completely.
WEBAPP_SHOW_ADMIN_PAGE_LINK	Boolean	Set value to `true` to display the admin page link on the dashboard.
WEBAPP_ALLOW_EDIT_PROFILING_ATTRIBUTES	String	Set value to `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	Set value to `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.
ime_interface	String	Set value to `EditContext` to support Sougou Chinese IME on Chrome and Safari.
validate.frameworks	Boolean	Set value to `false` to deactivate the framework validation option that appears in the Administration page for uploading frameworks. The default value is `true`.

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

Custom Options for Content Security Policy (CSP)


Option name	Value	Description
use_csp_header	Boolean	Set to `true` to use the `Content-Security-Policy` header. This is recommended for enhanced security.
csp_use_custom_policy	Boolean	Set to `true` to customize the value of the `Content-Security-Policy` header.
You can contribute to each directive of the Content Security Policy using the following options: csp.default.src csp.script.src csp.style.src csp.img.src csp.connect.src csp.font.src csp.object.src csp.media.src csp.frame.src csp.sandbox	String Array	Specify an array of strings that will be appended the value of the CSP directive. Attention: These options are only taken into account if the value of `csp_use_custom_policy` is true. Tip: For more information about the CSP directives, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives.

Example: The options.xml file would contain the following snippet:

<entry> 	
  <String>use_csp_header</String> 	
  <Boolean>true</Boolean> </entry>
<entry> 	
  <String>csp_use_custom_policy</String> 	
  <Boolean>true</Boolean> </entry>
<entry> 	
  <String>csp.default.src</String> 	
  <String-array> 		
    <String>'self'</String> 		
    <String>https://www.oxygenxml.com</String> 	
  </String-array>
 </entry>

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.