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.
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 . menu actionNote: 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.
<?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.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. |
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.width | Integer | Used to define the number of characters after which a hard line-wrapping action is performed (default is 100). |
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. |
insertOnlyElementsFromCCList | Boolean | If set to true, the content completion list will only show elements that are valid at the current position. |
editReferencesInPlace | Boolean | Set this option to true to enable in-place editing of the content of referenced topics within a DITA map. |
Schematron_custom_language | String | The two-letter country code (for example:
en ,fr ). |
Schematron_language_option | Integer |
2 (default value) - The Schematron 3 - The language attributes are ignored. All messages will be presented. 4 - A custom language defined by the
|
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 |
0 - Full tags. 1 - No tags. 2 - Block tags. 3 - Partial tags. 4 - Full tags with attributes. 5 - Inline tags. |
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. |
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. |
track.changes.initial.state | Integer | Option for track changes initial state.
|
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:
|
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. |
xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" vc:minVersion="1.1"
<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>
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. |
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. |
<entry> <String>force.cookies.samesite.none</String> <Boolean>true</Boolean> </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.
Option name | 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:
<context-param> <param-name>com.oxygenxml.loadBuiltinProtocolHandlers</param-name> <param-value>false</param-value> </context-param>
Custom Options for the Git Plugin
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 |
<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 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.