Thursday, January 25, 2018

Composing Author Actions

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Suppose that each time you insert a DITA table in the Author visual editing mode, you want to always have the attributes colsep="1" rowsep="1" frame="all" set on it. The purpose of this post is to create a new DITA-specific action for inserting a table that invokes the current table insertion action and then forces those three attributes to be set on the table element. Here are some steps to accomplish this:
  1. Follow the steps listed in this older blog post to create an extension of the DITA framework: http://blog.oxygenxml.com/2016/10/customizing-dita-visual-editing.html.

  2. In the Document Type Association preferences page, edit the DITA framework extension you just created. Go to the Author->Actions tab and create a new action with the ID change.table.colsep. Use the predefined ChangeAttributeOperation to set the (colsep="1" attribute) on the closest table element. The custom action would look like this:

  3. Based on the same idea, create two more new actions called "change.table.rowsep" and "change.table.frame" that will set the rowsep="1" and frame="all" attributes on the closest table, respectively.

  4. Create a new action with the ID insert.table.fixed.attributes and use the predefined ExecuteMultipleActionsOperation to call 4 actions in a row, the original insert.table action ID that inserts the table, followed by the three action IDs that set various attribute values to the inserted table.

  5. Go to the Author->Toolbar tab and in the "Current actions" panel, remove the current "insert.table" action and replace it with the insert.table.fixed.attributes action ID.

  6. When editing a DITA topic, pressing the toolbar action for inserting a table should now call your custom action that sets those three attributes on the inserted table.

Wednesday, January 03, 2018

Sorting glossary lists in a DITA Bookmap

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

The idea behind this DITA refactoring action started from this forum post: https://www.oxygenxml.com/forum/viewtopic.php?f=2&t=15284&p=45137#p45137.

Suppose you have a DITA Bookmap that at some point references all of its glossary entries:
            <glossarylist>
                <topicref href="glossary/glossItem1.dita"/>
                <topicref href="glossary/glossItem2.dita"/>
                <topicref href="glossary/glossItem3.dita"/>
                <topicref href="glossary/glossItem4.dita"/>
            </glossarylist>
and you want to have all of these glossary topics sorted alphabetically by title as they appear in the PDF output.

One option for this is to create a PDF customization that automatically sorts the glossary entries no matter what order they were originally specified in the DITA Map.

The other option is to create a custom Oxygen XML Refactoring operation that, when applied on the DITA Bookmap containing the "glossarylist", will sort the glossentries in alphabetical order according to the title of each glossentry.

The following steps will help you achieve this:
  1. Somewhere on disk, create a folder (for example, customRefactor) and add a reference to it in the Oxygen Preferences->"XML / XML Refactoring" page.

  2. In that custom folder, create an XML file (for example, sortGlossentries.xml) that has the following content:

    <refactoringOperationDescriptor 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.oxygenxml.com/ns/xmlRefactoring" id="op_tck_rp1_hcb" name="Sort glossentries">
        <description>Sort glossentries.</description>    
        <script type="XSLT" href="sortGlossentries.xsl"/>
    </refactoringOperationDescriptor>

    This particular descriptor file contains the name of the operation, its description, and points to an XSLT stylesheet that will be applied to sort the entries in the DITA Bookmap.

  3. In the same folder, create a file called sortGlossentries.xsl with the following content:

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        exclude-result-prefixes="xs"
        version="2.0">
        <xsl:template match="node() | @*">
            <xsl:copy>
                <xsl:apply-templates select="node() | @*"/>
            </xsl:copy>
        </xsl:template>
        <xsl:template match="glossarylist">
            <xsl:copy>
                <xsl:apply-templates select="@*"/>
                <xsl:for-each select="*" >
                    <xsl:sort select="document(@href, .)/*/glossterm/text()"/>
                    <xsl:apply-templates select="."/>
                </xsl:for-each>
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>

    This particular XSLT processing copies almost all the Bookmap content unchanged. However, the topicrefs in the glossarylist are sorted according to the glossterm titles specified inside each of them.

  4. Restart Oxygen.

  5. Open the bookmap that contains the glossarylist in the Oxygen main editing area, right-click, choose Refactoring and in the Other operations submenu you will find the new Sort glossentries refactoring action. Invoke the action and use the Preview button to check if the sorting is properly done.