History | Edit

Oxygen XML Editor has an extensive set of options that you can configure. When Oxygen XML Editor in installed, these options are set to default values. You can provide a different set of default values for an installation using an XML options file.

Creating an XML Options File

To create an options file, follow these steps:
  1. It is recommended that you use a fresh install for this procedure, to make sure that you do not copy personal or local preferences.
  2. Open Oxygen XML Editor and open the Preferences dialog box (Options > Preferences).
  3. Go through the options and set them to the desired defaults. Make sure that Global Options is selected in each page.
  4. Click OK and close the Preferences dialog box.
  5. Go to Options > Export Global Options to create an XML options file.

Controlling Which Options are Stored in the Default Options File

If you want to control exactly which option pages will be stored in the default options file, you can choose to attach them to a project file (.xpr file extension) by following this procedure:
  1. You many want to use a fresh install for this procedure, to make sure that you do not copy personal or local preferences.
  2. In the Project view, create a project or open an existing one.
  3. Open the Preferences dialog box (Options > Preferences).
  4. Configure the options in each preferences page that you want to be included in the project file and switch the storage preference to Project Options in each page.
    Note: Some pages do not have the Project Options button, since the options they host might contain sensitive data (such as passwords, for example) that is unsuitable for sharing with other users.
  5. Click OK and close the Preferences dialog box.
    All explicitly set values are now saved in the project file. You can then share the project file so that your team will have the same option configuration that you stored in the project file.
    Note: The project file extension (.xpr) must be preserved when the file is distributed to others.
    Note: When a project is opened for the first time, a confirmation dialog box will be displayed that asks you to confirm that the project came from a trusted source. This is meant to help prevent potential security issues.

Configuring an Installation to Use Customized Default Options

There are several methods that you can use to configure an Oxygen XML Editor installation to use the customized default options from the created XML options file.
Warning: The disadvantage of customizing the default options is that if the end user manually changes an option, the default value will no longer be used. An alternative would be to use a plugin to impose a set of options.

The possible methods for using customized default options during an installation include:

  • Copy the XML Options File to the Installation Directory

    In the [OXYGEN_INSTALL_DIR], create a folder called preferences and copy the created XML options file into it (for example, [OXYGEN_INSTALL_DIR]/preferences/default.xml).

  • Specify a Path to the XML Options File in a Startup Parameter
    Set the path to the XML options file as the value of the com.oxygenxml.default.options system property in the startup parameters. The path can be specified with any of the following:
    • A URL or file path relative to the application installation folder. For example:
      -Dcom.oxygenxml.default.options=options/default.xml
    • A system variable that specifies the file path. For example:
      com.oxygenxml.default.options=${system(CONFIG)}/default.xml
    • An environmental variable that specifies the file path. For example:
      com.oxygenxml.default.options=${env(CONFIG)}/default.xml
    Note: If you are using the Java Webstart distribution, use the optionsDir property to specify the path of the options file (in this case, the file must be named default.xml), or you can edit the .jnlp file that launches the application and set the com.oxygenxml.default.options parameter using a property element, as in the following example:
     <property name="oxy:com.oxygenxml.default.options" 
               value="http://host/path/to/default.xml"/>

Impose a Set of Options Using a Plugin

The Oxygen XML SDK includes a sample Java-based oxygen-sample-plugin-impose-options plugin that shows how to impose a set of options for the end users every time the API is called. It is possible to use this plugin to impose options but still allow the end user to change options by calling the API only once, the first time the plugin starts alongside Oxygen XML Editor.

A similar JavaScript-based sample impose-options plugin is also available here: https://github.com/oxygenxml/wsaccess-javascript-sample-plugins. This plugin imports a fixed set of options (saved in XML format) when Oxygen XML Editor starts.