Best practices for custom plug-ins

Adhering to certain development practices will properly isolate your code from that of DITA Open Toolkit. This will make it easier to you to upgrade to new versions of DITA-OT when they are released.

  • Use a properly-constructed DITA-OT plug-in.

  • Use a version control system to store your code.

  • Never modify any of the core DITA-OT code.
    Tip: You may want to set the permissions on default plug-in directories such as org.dita.pdf2 to “read-only” to ensure that you do not accidentally modify the files within as you develop your customized plug-in.

  • Avoid copying entire DITA-OT files into your customization plug-in. When you only copy the attribute sets and templates that you need to override, there is less risk of impact from new features or fixes in the base code, making your code more stable and easier to upgrade between releases.

  • If you only need to change a few attribute sets and templates, you may prefer to store your overrides in custom.xsl files, or a simple folder hierarchy within your custom plug-in.

  • In cases that require substantial customizations, you may prefer to organize the files in a folder structure that mimics the hierarchy of the default plug-in you are customizing. This facilitates comparisons with the default settings in the base plug-in and makes it easier to migrate your changes to new toolkit versions.

  • Upgrade your customization plug-in to new versions of DITA-OT regularly. Do not wait through several major releases before upgrading.

  • DITA-OT includes a RELAX NG schema file that can be used to validate the plugin.xml files that define the capabilities of each plug-in.

    To ensure the syntax of your custom plug-in is correct, include the following <?xml-model?> processing instruction at the beginning of the plugin.xml file, immediately after the XML prolog:

    <?xml-model href="dita-ot/plugin.rnc" type="application/relax-ng-compact-syntax"?>

    If your authoring environment does not apply this schema automatically, point your editor to dita-ot-dir/resources/plugin.rnc to associate the schema with your plug-in file.

  • For XSLT customizations, use a custom namespace for any modified template modes, template names, attribute sets, functions, and variables. This helps to clarify which portions of the code are specific to your customizations, and serves to isolate your changes in the event that items with the same name are added to the base plug-ins in the future.

    For example, instead of creating a template named searchbar, use something like corp:searchbar instead. This ensures that if future versions of DITA-OT add a searchbar template, your custom version will be unaffected.

    Instead of: 
    <xsl:template name="searchbar"/>
    use: 
    <xsl:template name="corp:searchbar"/>