Edit online

Customizing Options and Features

It is possible to customize the online editor that is built into the Oxygen Content Fusion interface by using a custom framework, but it is also possible to customize certain options and features by making changes to particular configuration files. For example, you can configure term lists used by the spell checker or AutoCorrect feature, and you can configure various options to customize the editing experience for all users.

Configuring Options for the Users' Editing Experience

The functionality of the Oxygen Content Fusion built-in visual editor shares many of the same options used in Oxygen XML Editor/Author. The options are stored in an options.xml file that is located in the /fusion/data/temp/webauthor/options folder. You can adjust this file to configure the options used for the editing experience of all 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 Content Fusion
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>

Enabling the Outline Pane

The visual editor includes an Outline side-pane that displays a general tag overview of the currently open document. It is enabled and available, by default, for DocBook, TEI, and XHTML documents. However, it is possible to configure other frameworks (such as DITA) to display the pane.

To enable the Outline pane for a custom framework, see Enabling the Outline Pane for DITA and Other Frameworks. You can also configure which side of the interface it appears by using either of the following:

In both cases, the accepted values are: left or right.

Adding Custom Term Lists for the Spell Checker

You can create personalized term lists that are used to store specialized terms (learned words) or control forbidden words. They can then be added to one of the directories that store the spell check dictionaries and the spell checker will merge them with all the dictionaries and other term lists for a particular language.

To create and add a personalized terms list, follow these steps:
  1. Create a term list file (with a .tdi file extension). The name of the file must begin with a two letter prefix that indicates the language it should be attached to, followed by an underscore or hyphen, and then a descriptive name (for example, en_US_myterms.tdi for term list in the US version of the English language or en_myterms.tdi for a less specific English term list). For a list of language codes, see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.
  2. In the term list file (.tdi extension), add the terms you want to be included in your custom dictionary. If you need to specify forbidden terms, those words simply need to be preceded by an asterisk. Add one word per row, as in the following example:
         parabola
         asimptotic
         *hyperbola
  3. Save the file (.tdi) in the /fusion/data/temp/webauthor/options/spell folder.
  4. Restart the server for the web-based editor for the spell checker to start using the new terms list.

Customizing the AutoCorrect Terms List

The Oxygen Content Fusion built-in visual editor includes an AutoCorrect feature to automatically correct misspelled words as you type. There is a default list of commonly misspelled words and symbols for each supported language, but you can modify the list to suit your needs.

To customize the term list used by the AutoCorrect feature, follow these steps:
  1. In Oxygen XML Editor/Author, go to Options > Preferences > Editor > Edit Modes > Author > AutoCorrect.
  2. Make whatever changes you require and click Apply. If you need help with any of the options in this preferences page, see AutoCorrect Preferences.
  3. Go to Options > Preferences > Editor > Edit Modes > Author > AutoCorrect > Dictionaries and note the location where the dictionaries are stored.
  4. Navigate to that location with a file explorer and look for a patch file (it should look like: en_patch.xml).
  5. Copy or move that patch file to the /fusion/data/temp/webauthor/options/autocorrect folder.
  6. Restart the server for the web-based editor for the AutoCorrect feature to start using the new terms list.

Alternate Method for Customizing the AutoCorrect Terms List (Without Using Oxygen XML Editor/Author)

  1. Create a patch file called en_patch.xml with content like this:
    <?xml version="1.0" encoding="UTF-8"?>
    <replacements>
        <deletion match="i" substitution="I"/>
        <deletion match="(c)" substitution="©"/>
    </replacements>
  2. Save it in the options/autocorrect folder that is located inside your Oxygen Data Directory (oxygen.data.dir/options/autocorrect).
  3. Restart the server for the web-based editor for the AutoCorrect feature to start using the new terms list.