Thursday, October 06, 2016

Customizing the DITA Visual Editing Experience

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

The Author visual editing experience in Oxygen is CSS driven. Let's say I have a team of writers using Oxygen and they want to visually edit DITA dl elements in a table-like layout.

All the validation, editing and publishing support Oxygen has for a specific XML vocabulary is defined in a framework configuration.

Instead of copying an entire framework configuration folder (like DITA or Docbook), modify and distribute it you can choose to extend that framework and distribute the extension. In this way, you will benefit of new functionality added to the base framework by newer Oxygen versions and still use your customizations.

The steps below describe how an extension of the DITA framework which removes certain elements from the content completion list can be constructed and shared:
  1. Create somewhere on your disk, in a place where you have full write access a folder structure like: custom_frameworks/dita-extension.
  2. In that folder create a new CSS stylesheet called for example custom.css which will keep your custom CSS styles:
    dl{
        display:table !important;
    }
    dlentry{
        display:table-row !important;
    }
    dt, dd {
        display:table-cell !important;
        border: 1px solid black;
        padding: 2px;
    }
  3. In the Document Type Association / Locations preferences page add in your Additional frameworks directories list the path to your custom_frameworks folder. Then click Apply in the Preferences dialog.
  4. In the Document Type Association Preferences page select the DITA document type configuration and use the Extend button to create an extension for it.
  5. Give a custom name to the extension, for example DITA - Custom and then change its Storage to external, then save it to a path like: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
  6. Make changes to the framework configuration, in the Author tab click the CSS tab and add a reference to your custom CSS. Do not set a title for the CSS and also do not check the Alternate checkbox as you want your CSS to apply by default.
  7. Click OK to close the dialog and then either OK or Apply to save the preferences changes.

After you perform the steps above you will have in the dita-extension folder a fully functioning framework which can be shared with others: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.

To check that your framework extension works, you can create a new DITA topic and insert a dl element inside it. It should now be presented in a table-like layout.

In order to know which CSS styles to override for a specific DITA element, you can right click inside that element in the Author visual editing mode and use the Inspect Styles action to see all CSS styles defined for it by default. You can also define alternate CSS styles which are applied manually by the writer by using the Author toolbar Styles drop down menu.

No comments:

Post a Comment