bn
/
se


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
							<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2019"><meta name="DC.rights.owner" content="(C) Copyright 2019"><meta name="DC.type" content="concept"><meta name="description" content="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns."><meta name="DC.subject" content=", plug-ins, best practices, XSLT, preprocessing"><meta name="keywords" content=", plug-ins, best practices, XSLT, preprocessing"><meta name="DC.relation" scheme="URI" content="../topics/custom-plugins.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-customization.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-customization-approaches.html"><meta name="DC.relation" scheme="URI" content="../topics/plugin-best-practices.html"><meta name="DC.format" content="HTML5"><meta name="DC.identifier" content="ID"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Plug-in coding conventions</title></head><body id="ID"><header role="banner"><div class="header">
  <p>DITA Open Toolkit</p>
  <hr>
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.3</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/alternative-input-formats.html">Authoring formats</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../parameters/index.html">Setting parameters</a></li><li><a href="../topics/customizing.html">Customizing DITA-OT</a><ul><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/custom-plugins.html">Working with plug-ins</a><ul><li><a href="../topics/plugins-installing.html">Installing plug-ins</a></li><li><a href="../topics/plugins-removing.html">Removing plug-ins</a></li><li><a href="../topics/plugins-registry.html">Plug-in registry</a></li><li><a href="../topics/plugin-configfile.html">Plug-in descriptor file</a></li><li><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a></li><li><a href="../topics/plugin-applications.html">Plug-in applications</a></li><li><a href="../topics/plugin-sample.html">Example plugin.xml file</a></li><li><a href="../topics/plugin-best-practices.html">Best practices</a></li><li class="active"><a href="../topics/plugin-coding-conventions.html">Coding conventions</a></li></ul></li><li><a href="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../topics/migration.html">Migrating customizations</a></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/rebuilding-docs.html">Rebuilding documentation</a></li></ul></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
  <h1 class="title topictitle1" id="ariaid-title1">Plug-in coding conventions</h1>
  
  
  
  <div class="body conbody"><p class="shortdesc">To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases,
    the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding
    patterns.</p>
    <section class="section"><h2 class="title sectiontitle">Upgrade stylesheets to XSLT 2.0</h2>
      
      
      
      
      
      
      <p class="p">The Saxon project has announced plans to remove XSLT 1.0 support from the Saxon-HE library that ships with
        DITA-OT:</p>
      <blockquote class="lq">…we’re dropping XSLT 1.0
        backwards compatibility mode from Saxon-HE, and hope to eliminate it entirely in due course.<br><div style="text-align:right"><a href="https://www.xml.com/news/release-saxon-98/"><cite>https://www.xml.com/news/release-saxon-98/</cite></a></div></blockquote>
      <p class="p">DITA-OT 3.0 and 3.0.1 included Saxon-HE 9.8.0.5, which rejects XSLT stylesheets that specify
          <code class="ph codeph">version="1.0"</code>. Plug-ins with XSLT templates specifying version 1.0 will fail with the message
          “<samp class="ph msgph">XSLT 1.0 compatibility mode is not available in this configuration</samp>.”</p>
      <p class="p">To resolve this issue, change any occurrences of <code class="ph codeph">&lt;xsl:stylesheet version="1.0"&gt;</code> in custom
        plug-in stylesheets to at least <code class="ph codeph">&lt;xsl:stylesheet version="2.0"&gt;</code>.</p>
      <div class="note tip note_tip"><span class="note__title">Tip:</span> DITA-OT 3.0.2 includes Saxon-HE 9.8.0.7, which restores XSLT 1.0 backwards-compatibility mode,
        but the DITA Open Toolkit project recommends upgrading all stylesheets to XSLT 2.0 to ensure plug-ins remain
        compatible with future versions of DITA-OT and Saxon-HE.</div>
    </section>
    <section class="section"><h2 class="title sectiontitle">Use custom <code class="keyword markupname xmlelement">&lt;pipeline&gt;</code> elements</h2>
      
      <div class="div div-index">
        
        
        
      </div>
      <p class="p">In Ant scripts, use the XSLT module from DITA-OT instead of Ant’s built-in <code class="keyword markupname xmlelement">&lt;xslt&gt;</code> or
          <code class="keyword markupname xmlelement">&lt;style&gt;</code> tasks. </p>
      <p class="p">The XSLT module allows access to DITA-OT features like using the job configuration to select files in the
        temporary folder based on file metadata and custom XSLT extension functions. </p>
      <p class="p">Instead of:</p>
      <div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xslt style="${dita.plugin.example.dir}/custom.xsl"
      basedir="${dita.temp.dir}"
      destdir="${dita.output.dir}"
      includesfile="${dita.temp.dir}/${fullditatopicfile}"/&gt;</code></pre></div>
      <p class="p">use:</p>
      <div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;pipeline&gt;
  &lt;xslt style="${dita.plugin.example.dir}/custom.xsl"
        destdir="${dita.output.dir}"&gt;
    &lt;ditafileset format="dita" /&gt;
  &lt;/xslt&gt;
&lt;/pipeline&gt;</code></pre></div>
    </section>

    <section class="section"><h2 class="title sectiontitle">Use the plug-in directory property</h2>
      
      <p class="p">In Ant scripts, always refer to files in other plug-ins using the
            <code class="ph codeph">dita.plugin.<var class="keyword varname">plugin-id</var>.dir</code> property.</p>
      <p class="p">Instead of:</p>
      <div class="p"><pre class="pre codeblock language-xml"><code>&lt;property name="base" location="../example/custom.xsl"/&gt;</code></pre></div>
      <p class="p">use:</p>
      <div class="p"><pre class="pre codeblock language-xml"><code>&lt;property name="base" location="${dita.plugin.example.dir}/custom.xsl"/&gt;</code></pre></div>
      <p class="p">This fixes cases where plug-ins are installed to custom plug-in directories or the plug-in folder name doesn’t
        match the plug-in ID.</p>
    </section>

    <section class="section"><h2 class="title sectiontitle">Use <code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code> to select files</h2>
      
      <div class="div div-index">
        
        
        
        
      </div>
      <p class="p">In Ant scripts, use <code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code> to select resources in the temporary directory.</p>
      <p class="p">For example, to select all images referenced by input DITA files, instead of:</p>
      <div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;copy todir="${copy-image.todir}"&gt;
  &lt;fileset dir="${user.input.dir}"&gt;
    &lt;includes name="*.jpg"/&gt;
    &lt;includes name="*.jpeg"/&gt;
    &lt;includes name="*.png"/&gt;
    &lt;includes name="*.gif"/&gt;
    &lt;includes name="*.svg"/&gt;
  &lt;/fileset&gt;
&lt;/copy&gt;</code></pre></div>
      <p class="p">use:</p>
      <div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;copy todir="${copy-image.todir}"&gt;
  &lt;ditafileset format="image" /&gt;
&lt;/copy&gt;</code></pre>
      </div>
      <p class="p">The <code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code> resource collection can be used to select different types of
        files.</p>
      <table class="table table-hover frame-none"><caption><span class="table--title-label">Table 1. </span><span class="title">Usage examples of <code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code></span></caption><colgroup><col style="width:50%"><col style="width:50%"></colgroup><thead class="thead">
            <tr class="row">
              <th class="entry colsep-0 rowsep-1" id="ID__entry__1">Example</th>
              <th class="entry colsep-0 rowsep-1" id="ID__entry__2">Description</th>
            </tr>
          </thead><tbody class="tbody">
            <tr class="row">
              <td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><code class="ph codeph">&lt;ditafileset format="dita"/&gt;</code></td>
              <td class="entry colsep-0 rowsep-1" headers="ID__entry__2">Selects all DITA topics in the temporary directory.</td>
            </tr>
            <tr class="row">
              <td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><code class="ph codeph">&lt;ditafileset format="ditamap"/&gt;</code></td>
              <td class="entry colsep-0 rowsep-1" headers="ID__entry__2">Selects all DITA maps in the temporary directory.</td>
            </tr>
            <tr class="row">
              <td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><code class="ph codeph">&lt;ditafileset format="image"/&gt;</code></td>
              <td class="entry colsep-0 rowsep-1" headers="ID__entry__2">Selects images of all known types in the temporary directory.</td>
            </tr>
          </tbody></table>
    </section>

    <section class="section"><h2 class="title sectiontitle">Use the <code class="ph codeph">plugin</code> URI scheme</h2>
      
      <div class="div div-index">
        
        
      </div>
      <p class="p">In XSLT, use the <code class="ph codeph">plugin</code> URI scheme in <code class="keyword markupname xmlelement">&lt;xsl:import&gt;</code> and
          <code class="keyword markupname xmlelement">&lt;xsl:include&gt;</code> to reference files in other plug-ins.</p>
      <p class="p">Instead of:</p>
      <div class="p"><pre class="pre codeblock language-xml"><code>&lt;xsl:import href="../../org.dita.base/xsl/common/output-message.xsl"/&gt;</code></pre></div>
      <p class="p">use:</p>
      <div class="p"><pre class="pre codeblock language-xml"><code>&lt;xsl:import href="plugin:org.dita.base:xsl/common/output-message.xsl"/&gt;</code></pre></div>
      <p class="p">As with the plug-in directory property in Ant, this allows plug-ins to resolve to the correct directory even
        when a plug-in moves to a new location. The plug-in is referenced using the syntax
            <code class="ph codeph">plugin:<var class="keyword varname">plugin-id</var>:<var class="keyword varname">path/within/plugin/file.xsl</var></code>.</p>
    </section>

    <section class="section"><h2 class="title sectiontitle">Validating plug-ins</h2>
      
      <div class="div" id="ID__d29e92">
        <p class="p">DITA-OT includes a RELAX NG schema file that can be used to validate the <span class="ph filepath">plugin.xml</span>
          files that define the capabilities of each plug-in.
        
        
        </p>
        <p class="p">To ensure the syntax of your custom plug-in is correct, include an <code class="keyword markupname xmlpi">&lt;?xml-model?&gt;</code> processing
          instruction at the beginning of the <span class="ph filepath">plugin.xml</span> file, immediately after the XML
          prolog:</p>
        <p class="p"><code class="keyword markupname xmlpi">&lt;?xml-model href="dita-ot/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;</code></p>
        <p class="p">If your authoring environment does not apply this schema automatically, point your editor to <span class="ph filepath" id="ID__d29e123"><var class="keyword varname">dita-ot-dir</var>/resources/plugin.rnc</span> to associate the schema with
          your plug-in file.</p>
      </div>
    </section>

  </div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/custom-plugins.html" title="You can install or create DITA-OT plug-ins to change the default output types in various ways, add entirely new kinds of output formats, or implement DITA topic specializations.">Working with plug-ins</a></div></div><div class="linklist relinfo relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-customization-approaches.html" title="Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these approaches have advantages and shortcomings that should be considered when preparing a customization project. Some of these methods are considered “anti-patterns” with disadvantages that outweigh their apparent appeal. In most cases, you should create a custom PDF plug-in.">PDF customization approaches</a></li><li class="linklist"><a class="link" href="../topics/plugin-best-practices.html" title="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.">Best practices for custom plug-ins</a></li></ul></div><div class="linklist relinfo reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-customization.html" title="You can create custom DITA-OT plug-ins that build on the default DITA to PDF transformation. Plug-ins can customize covers and page layouts, modify formatting, override logic of the default PDF plug-in, and much more.">Customizing PDF output</a></li></ul></div></nav></article></main></body></html>