Edit online

Integrating Web Author with Your Content by Creating Custom Frameworks

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-based 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 an interesting Blog post written on this subject available at: https://blog.oxygenxml.com/topics/SchematronBCs.html.

There is also a public project in the Oxygen GitHub account pages that offers guidance and instructions for integrating an Intelligent Style Guide for imposing business rules and assisting the content authors. You can download the project and try it for yourself at: https://github.com/oxygenxml/integrated-styleguide.

Document 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 Custom 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-custom.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 contains your custom framework folder that you created in the first step of this procedure. The archive should contain exactly one folder on the first level. 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 procedure 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: https://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 Oxygen XML Editor/Author.

    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 1. 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 to upload.
    Important: The framework should be a ZIP or JAR archive that contains exactly one folder. This folder should contain the framework descriptor file with the .framework extension and other supporting files. If the uploaded archive does not have this format you will receive an error that the upload was rejected.

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

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

Adding JavaScript Code to a Framework

To load JavaScript code, you can add JavaScript files (.js extension) directly inside the [Framework_Directory]/web folder.
Important:
  • All the files will be loaded in the browser in lexicographical order.
  • JavaScript files located in subfolders of the web folder will not be loaded.
  • If you have a framework extension, both the JavaScript files from the base framework and those from the extension will be loaded. If the extension contains a JavaScript file with the same name as a file in the base framework, the one in the extension takes precedence.
The framework's script needs to create an instance of sync.ext.Extension and register it in the sync.ext.Registry.extension field. For example:
class MyExtension extends sync.ext.Extension {
  // your implementation here ...
}
sync.ext.Registry.extension = new MyExtension();

When extending a framework, it is recommended to register an sync.ext.Extension instance that delegates to the sync.ext.Extension instance registered by the base framework.

These files can contain code that calls the Web Author JavaScript API to implement custom editing actions. Some possible use cases include:
The structure of the JavaScript extension should be the following:
MyExtension = function() {}
MyExtension.prototype.editorCreated = function (editor) {
  // ... work with the editor...
};
// Register the extension so that it will be notified when the editor is created.
sync.ext.Registry.extension = new MyExtension();
Tip: Some tutorials are available for other use cases in the Oxygen XML Web Author Component API Documentation, in the Tutorials section.

Loading Static Resources from the Framework Directory

All the resources (such as images, HTML, or CSS files) found in the web sub-folder of the framework folder can be accessed from the web browser using a URL obtained by evaluating sync.ext.Registry.extensionURL in JavaScript. For example, a file located at <framework-folder>/web/resources/image.png can be accessed by the following URL:
sync.ext.Registry.extensionURL + 'resources/image.png'

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) {
 ... 
}

  • If the framework contains custom 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.

    If you plan to invoke a custom Author mode operation from the JavaScript code (as in this tutorial), the operation has to be annotated with ro.sync.ecss.extensions.api.webapp.WebappRestSafe.
    Warning: Operations annotated with ro.sync.ecss.extensions.api.webapp.WebappRestSafe can be invoked with user-supplied parameters. Use this annotation only for operations that are safe to execute with any parameter combination. For example, an action that would execute a process on the server based on a command-line script specified by the user is not safe.
    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.