History | Edit

You can customize Web Author to make it simple for everyone to write structured content and still adhere to your project conventions. This topic provides details about reusing frameworks between the standalone versions of Oxygen and Web Author, how to create customized frameworks, how to test and upload your customization, and other framework customization tips.

Examples of Framework Customization Use-Cases

Document Schema
Web Author supports any XML schema in any schema language. It also offers built-in support for DITA, DocBook, TEI and XHTML.
Add Support for a New XML Vocabulary
You can customize Web Author to work with any XML-based document type. For example, you can customize Web Author to work with a DITA specialization.
Authoring Experience
You can configure how documents are rendered in Web Author or display inline form-controls to allow users to edit attribute values.
Business Rules
You can configure the automatic validation to use Schematron to enforce various business rules and propose solutions for them. For more information, see the Schematron Quick Fixes (SQF) section in the Oxygen XML Editor User Manual. There is also an interesting Blogpost written on this subject available at: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.
File Templates
You can specify document templates that users can choose from when creating a new document.
Embedded Formats
Web Author supports embedded formats such as MathML, SVG, videos, and others using plugins or flexible form-controls. Also, support for embedded formats can be implemented by third parties. For example, WIRIS provides a plugin that can be used to edit MathML equations in a visual way.

Reusing Frameworks Between Oxygen XML Editor/Author and Web Author

Custom frameworks that are designed for documentation purposes can be reused interchangeably between Oxygen standalone distributions and the Oxygen XML Web Author. However, some fine-tuning might be necessary to maximize the editing experience for your content authors. The advantages of using a common framework include:
  • Uniform experience across multiple Oxygen XML Editor/Author distributions.
  • Ability to reuse previously developed frameworks.
  • Many of the customized items that are added to your framework in the Oxygen XML Editor/Author standalone distribution also carry over to Oxygen XML Web Author. For example, items that are added to the list of proposals for the Content Completion Assistant will appear in both distributions.

How to Create a Customized Framework (Document Type)

You can create a custom framework by extending an existing one:

  1. In a location where you have full write access, create a folder structure similar to this: custom_frameworks/dita-extension.
  2. Open a standalone version of Oxygen XML Editor/Author.
  3. Open the Preferences dialog box (Options > Preferences) and go to Document Type Association > Locations. In this preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list.
  4. Go to the Document Type Association preferences page and select an existing framework configuration and use the Extend button to create an extension for it.
  5. Give the extension an appropriate name (for example, DITA - Custom), select External for the Storage option, and specify an appropriate path (for example, path/to/.../custom_frameworks/dita-extension/dita-extension.framework).
  6. Make your changes to the extension. There is a large variety of ways to customize your extended framework. These are just some of the ways:
  7. Click OK to close the dialog box and then OK or Apply to save the changes.
  8. Create an archive that only contains your custom framework folder that you created in the first step of this procedure. The archive should contain exactly one folder (for example, dita-extension). You will need this archive structure to upload the framework to Web Author.

Testing a Custom Framework Using the Oxygen XML Web Author Test Server Add-on

The following procedures assumes that you have access to an Oxygen XML Editor/Author standalone installation. This is not a mandatory requirement, but rather a way to speed up the development process.

  1. Use the standalone installation of Oxygen XML Editor/Author to customize a specific framework.
  2. Install the Oxygen Web Author Test Server add-on.
    1. Go to Help > Install new add-ons to open an add-on selection dialog box.
    2. In the Show add-ons from text box, enter the following url: http://www.oxygenxml.com/InstData/Addons/optional/updateSite.xml.
    3. Select the Oxygen Web Author Test Server add-on and click Next.
    4. Select the I accept all terms of the end user license agreement option and click Finish.
    5. Restart the application.

      Result: You should now have a Start Web Author Server button on the toolbar.

  3. Open an XML file in Oxygen XML Editor/Author.
    Note: The Web Author Test Server does not load frameworks that have the Storage option set to Internal in the Document Type configuration dialog box. Therefore, the XML file needs to be from a framework that has that option set to External.
  4. Click the Start Web Author Server button found on the toolbar. This starts a Tomcat server and opens a file chooser dialog box:

    Figure: Web Author Test Server File Chooser Dialog Box

    The dialog box shows a URL entry for up to two network interfaces that are available on your desktop PC. The Tomcat server accesses the frameworks and options currently in use by Oxygen XML Editor/Author.
  5. Open the XML document with one of the following methods:
    • Mobile Device - To open the current document in your mobile device, click the QR Code button next to one of the network interface listings and use a QR code reader on your mobile device.
    • Desktop Browser - To open the current document in your desktop browser, click the Open in Browser button next to one of the network interface listings.
  6. Make whatever changes you want to your framework. Note that these changes will not automatically be reflected in the Oxygen XML Web Author if it was already running. To see the results of changes, close the server using the Close and stop server button in the file chooser dialog box and start it again.
Attention: When using this test server add-on, editing sessions have a limited duration. If the session stops working, click the Close and stop server button in the file chooser dialog box and start it again.

Uploading a Custom Framework to Web Author

To upload a custom framework to your Web Author deployment, follow this procedure:
  1. Go to your Administration Page.
  2. Select Frameworks.
  3. Click Upload Framework and choose a framework archive to upload.
    Important: Oxygen XML Web Author does a validation check to make sure the uploaded framework archive contains the proper extension descriptor file (*.framework). The archive should contain exactly one folder. Otherwise you will receive an error that the upload was rejected.
  4. Click OK to upload the file.

    Result: The framework should appear in the list on this Frameworks page. Uploaded frameworks appear with a light green highlight so that you can identify them easily.

  5. Once you are finished with all of your changes, restart the server.

Other Customization Tips

  • If you want to use CSS rules that only apply when the framework is used in the Oxygen XML Web Author, use the following media query:
    @media oxygen AND (platform:webapp) {
     ... 
    }
  • In the web folder of each framework, you can add a framework.js file that calls the JavaScript API to implement custom editing actions. The possible use cases include the following:
  • If the framework contains Author mode operations (Java implementations of the ro.sync.ecss.extensions.api.AuthorOperation interface), they can be enabled to be used by the Oxygen XML Web Author using the ro.sync.ecss.extensions.api.WebappCompatible annotation.
    Note: Author mode operations that use Java Swing components to display a graphical interface are not compatible with the Oxygen XML Web Author and they should not be annotated.
  • The Oxygen XML Web Author continuously validates the XML documents using the default validation scenarios defined at framework level. Only the validation units that have the Automatic Validation option selected in the Edit Scenario dialog box that is accessed by editing a scenario in the Validation subtab when editing a document type.