Adding CALS-table related functionality to your custom Oxygen framework

Oxygen comes with full support for CALS tables in DITA and Docbook documents, meaning that you can easily make selections, resize columns, and invoke special actions like insert or delete rows and columns, join, or split cells. You can also easily customize tables properties such as alignments, separators, and table borders. But what if you are editing documents from other vocabularies, containing tables with CALS structure? What you can do to obtain the same table editing features?

Let's suppose that you already created an Oxygen framework for your documents vocabulary (if you need further information about frameworks, see http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html). What we want to obtain next is to extract all the CALS tables related support from Docbook framework and add it to your custom framework. Why Docbook and not DITA as reference? Because the DITA customization is based on the "class" attribute checking while the Docbook one is more general (element-name oriented).

1. Table rendering
   1. copy [oXygen_install_dir]\frameworks\docbook\css\cals_table.css in your framework css directory
   2. in the Document Type edit dialog, Author tab, CSS sub-tab, add the ${framework}/css/cals_table.css entry to the list of the CSSs

   In this way the table will be rendered properly in Author mode and the following features will be available:

   • select cells (CTRL+click), rows (click before the row), columns (click on top of the row), tables (click in the left-up corner of the table)
   • resize table column
2. Create table actions

   Here are the table-related actions implemented in Docbook that you can implement also in you framework:

   • Expand colspecs
   • Insert/Delete Rows
   • Insert/Delete Columns
   • Table Properties
   • Join cells
   • Split cell
   1. Copy [oXygen_installation_dir]\frameworks\docbook\docbook.jar in your framework directory (this jar contains all the table operations classes needed to create table actions). In Document type edit dialog go to Classpath tab and add the docbook.jar from your framework directory to the list of paths. In this way you have access to all table operations from your framework.
   2. For every table action you have to define a corresponding action in the Document type configuration dialog. Here are the details: https://www.oxygenxml.com/doc/versions/17.1/ug-editor/#topics/the-action-dialog.html. You can look at the corresponding Docbook action to see the properties (id, name, icons, the conditions that enables it, the specific operation for CALS tables).
      Once you created these actions you can add them to the UI.
3. Add table actions to menu, toolbar and contextual menu
   1. To add an action to the menu go to Document Type configuration dialog, Author tab, Menu sub-tab, select the action from Available actions section and add it to the Current action section.
   2. To add an action to the contextual menu go to Document Type configuration dialog, Author tab, Contextual menu sub-tab, select the action from Available actions section and add it to the Current action section.
   3. To add an action to the toolbar go to Document Type configuration dialog, Author tab, Toolbar sub-tab, select the action from Available actions section and add it to the Current action section.

If all goes well, your custom framework which uses the standard CALS table naming mechanism will properly handle tables, both for display and for table-related operations.

How Special Paste works in Oxygen

If you've worked with one of the XML vocabularies for which Oxygen has out of the box support like DITA, Docbook, TEI, XHTML you've probably already used the support Oxygen has for converting content pasted in the application from external applications like Microsoft Word, Excel or from any web browser. This is a very useful feature for converting various types of content to XML because it preserves and converts styling, links, lists, tables and image references.

The feature relies on the fact that when copying content in the applications mentioned above, they set in the clipboard the HTML equivalent of the copied content. So all Oxygen has to do is clean up that HTML, make it wellformed XHTML and apply conversion XSLT stylesheets over it.

This support is not hardcoded and anybody who is developing an Oxygen framework customization for a certain XML vocabulary can provide conversion stylesheets for external pasted HTML content.

I will describe how this works for the DITA framework and you can do the same for yours. You can also use this information to modify the way in which smart paste works for the bundled framework configurations.

1. In the Preferences->Document Type Association page you can choose to edit (or extend) the DITA document type association.
2. In the Extensions tab the Extensions bundle implementation is set to DITAExtensionsBundle which resides in the DITA Java extensions archive dita.jar.
3. The DITAExtensionsBundle is an extension of the ExtensionsBundle API and it provides its own external object extension handler:

     /**
      * @see ro.sync.ecss.extensions.api.ExtensionsBundle#createExternalObjectInsertionHandler()
      */
     @Override
     public AuthorExternalObjectInsertionHandler createExternalObjectInsertionHandler() {
       return new DITAExternalObjectInsertionHandler();
     }

4. The DITAExternalObjectInsertionHandler extends the base class AuthorExternalObjectInsertionHandler and provides a reference to its specific conversion stylesheet:

     /**
      * @see ro.sync.ecss.extensions.api.AuthorExternalObjectInsertionHandler#getImporterStylesheetFileName(ro.sync.ecss.extensions.api.AuthorAccess)
      */
     @Override
     protected String getImporterStylesheetFileName(AuthorAccess authorAccess) {
       return "xhtml2ditaDriver.xsl";
     }

   Note: The Extensions tab also allows you to specify the external object insertion handler as a separate extension.
5. In the same Document Type edit dialog in the Classpath tab you will see that there is a reference to a framework-specific resources folder like:${framework}/resources/
6. If you look on disk in the DITA framework resources folder: "OXYGEN_INSTALL_DIR\frameworks\dita\resources" you will find the xhtml2ditaDriver.xsl stylesheet there. The stylesheet imports various other stylesheets which you could probably fully reuse and which apply various cleanups on HTML produced with MS Word. It also handles the conversion between the pasted HTML content and DITA so it is a good starting point, you can copy the entire set of XSLT stylesheets to your framework and use those as a starting point.

DITA-related improvements and goodies in Oxygen 17.1

I'm happy to announce this autumn the release of Oxygen 17.1. We've been quite buzy in the last months working on it and we hope you'll enjoy it in your daily XML-related activities.

Oxygen 17.1 comes with official support for the latest operating systems, Windows 10 and Mac OSX OS X El Capitan (10.11).

It also comes with a new user interface color theme called "Light" that makes the entire application interface look crisp and clean. Besides this, you now have the support to define custom color themes and share them with your team.

As always we also have lots of DITA-related improvements:

1. The dialogs for inserting conkeyrefs, conrefs and keyrefs to metadata have all been merged in one intuitive to use toolbar action called "Reuse content".
2. The dialog used to insert or to edit properties for a topic reference now also allows you to:
   1. Set profiling attributes.
   2. Define metadata content.
   3. Set any other valid attribute on the topic reference.
3. Experimental support for DITA 1.3. You can enable DITA 1.3 support (using the latest DITA Open Toolkit 2.1.2 bundled with the application) from the "Preferences->DITA" page. This support includes support for editing and validation, scoped keys and branch filtering.
   1. Scoped Keys Support. You can establish key scopes and insert references to keys inside or outside key scopes. oXygen will also takes key scopes into account when it validates and checks for completeness, resolves key and content key references, and publishes.
   2. Branch Filtering Support. The DITA 1.3 branch filtering mechanism makes it possible to reuse the content of topics multiple times within the same map, each time using different filters.

   You can find out more about DITA 1.3 support from our user's manual:

   http://www.oxygenxml.com/doc/versions/17.1/ug-editor/#topics/dita1-3-support.html

   or by watching this video demo:

   https://www.oxygenxml.com/demo/DITA_13.html

4. The oXygen WebHelp system was also improved to enhance your published output. Google Search, Google Analytics, and some popular social media widgets can now be integrated into your WebHelp system and search features are now available in offline mode.
5. Oxygen 17.1 comes bundled with an experimental new plugin developed by Jarno Elovirta for generating MS Word output (OOXML) from DITA content.
6. Once you decide in the "Preferences->DITA" page to use the bundled DITA Open Toolkit 2.1.2, you will also enable the ability to create Lightweight DITA topics and maps so you can experiment with this exciting new standard in the making:
   http://dita.xml.org/blog/lightweight-dita.