source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/dev_ref/plugin-newextensions.dita@ 99040

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="plugin-newextensions" xml:lang="en-us">
  <title>Creating a new plug-in extension point</title>
  <shortdesc>If your plug-in needs to define its own extension point in an XML file, add the string
      "<codeph>_template</codeph>" to the filename before the file suffix. During integration, this
    file will be processed like the built-in DITA-OT templates.</shortdesc>
  <refbody>
    <section><p>Template files are used to integrate most DITA-OT extensions. For example, the file
          <filepath>dita2xhtml_template.xsl</filepath> contains all of the default rules for
        converting DITA topics to XHTML, along with an integration point for plug-in extensions.
        When the integrator runs, the file dita2xhtml.xsl is recreated, and the integration point is
        replaced with references to all appropriate plug-ins.</p><p>To mark a new file as a template
        file, use the <codeph>&lt;template></codeph> element.</p>
      <p>The template extension namespace has the URI
          <codeph>http://dita-ot.sourceforge.net</codeph>. It is used to identify elements and
        attributes that have a special meaning in template processing. This documentation uses a
        prefix of  <codeph>dita:</codeph>  for referring to elements in the template extension
        namespace. However, template files are free to use any prefix, provided that there is a
        namespace declaration that binds the prefix to the URI of the template extension namespace.
      </p>
    </section>
    <section>
      <title><codeph>dita:extension</codeph> element</title>
      <p>The <codeph>dita:extension</codeph> elements are used to insert generated content during
        integration process. There are two required attributes:</p>
      <ul>
        <li>The <codeph>id</codeph> attribute defines the extension point ID which provides the
          argument data.</li>
        <li>The <codeph>behaviour</codeph> attribute defines which processing action is used.</li>
      </ul>
      <p>Supported values for <codeph>behavior</codeph> attribute:</p>
      <dl>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.CheckTranstypeAction</codeph></dt>
          <dd>Create Ant condition elements to check if <codeph>${transtype}</codeph> property value
            equals a supported transtype value.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.ImportAntLibAction</codeph></dt>
          <dd>Create Ant <codeph>pathelement</codeph> elements for <xref href="plugin-javalib.dita"
              format="dita">library imported extension point</xref>. The <codeph>id</codeph>
            attribute is used to define the extension point ID.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.ImportPluginCatalogAction</codeph></dt>
          <dd>Include plug-in metadata catalog content.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.ImportPluginInfoAction</codeph></dt>
          <dd>Create plug-in metadata Ant properties.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.ImportStringsAction</codeph></dt>
          <dd>Include plug-in string file content base on <xref href="plugin-addgeneratedtext.dita"
              format="dita">generated text extension point</xref>. The <codeph>id</codeph> attribute
            is used to define the extension point ID.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.ImportXSLAction</codeph></dt>
          <dd>Create <codeph>xsl:import</codeph> elements based on <xref
              href="plugin-overridestyle.dita">XSLT import extension point</xref>. The
              <codeph>id</codeph> attribute is used to define the extension point ID.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.InsertAction</codeph></dt>
          <dd>Include plug-in conductor content based on <xref href="plugin-anttarget.dita"
              format="dita">Ant import extension point</xref>. The <codeph>id</codeph> attribute is
            used to define the extension point ID.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.InsertAntActionRelative</codeph></dt>
          <dd>Include plug-in conductor content based on <xref href="plugin-anttarget.dita"
              format="dita">relative Ant import extension point</xref>. The <codeph>id</codeph>
            attribute is used to define the extension point ID.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.InsertCatalogActionRelative</codeph></dt>
          <dd>Include plug-in catalog content based on <xref href="plugin-xmlcatalog.dita"
              format="dita">catalog import extension point</xref>. The <codeph>id</codeph> attribute
            is used to define the extension point ID.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.dost.platform.ListTranstypeAction</codeph></dt>
          <dd>Create a pipe delimited list of supported transtypes.</dd>
        </dlentry>
      </dl>
    </section>
    <section id="section_vfc_gvw_mg">
      <title><codeph>dita:extension</codeph> attribute</title>
      <p>The <codeph>dita:extension</codeph> attribute is used to process attributes in elements
        which are not in template extension namespace. The value of the attribute is a space
        delimited tuple, where the first item is the name of the attribute to process and the second
        item is the action ID.</p>
      <p>Supported values:</p>
      <dl>
        <dlentry>
          <dt><codeph>depends org.dita.dost.platform.InsertDependsAction</codeph></dt>
          <dd>Ant target dependency list is processed to replace all target names which start with
            an open curly bracket and end with a close curly bracket. The value of the extension
            point is the ID between the curly brackets.</dd>
        </dlentry>
      </dl>
    </section>
    <example><title>Example</title><p>The following plug-in defines
          <filepath>myBuildFile_template.xml</filepath> as a new template for extensions, and two
        new extension points.</p><?Pub Caret -1?><codeblock>&lt;plugin id="com.example.new-extensions">
  &lt;extension-point id="com.example.new-extensions.pre"
                   name="Custom target preprocess"/>
  &lt;extension-point id="com.example.new-extensions.content"
                   name="Custom target content"/>
  &lt;template file="myBuildFile_template.xml"/>
&lt;/plugin></codeblock>
      <p>When the integrator runs, this will be used to recreate
          <filepath>myBuildFile.xml</filepath>, replacing Ant file content based on extension point
        use.</p>
      <codeblock>&lt;project xmlns:dita="http://dita-ot.sourceforge.net">
  &lt;target name="dita2custom"
          depends="dita2custom.init,
                   {com.example.new-extensions.pre},
                   dita2xhtml"
          dita:extension="depends org.dita.dost.platform.InsertDependsAction">
    &lt;dita:extension id="com.example.new-extensions.content"
                    behaviour="org.dita.dost.platform.InsertAction"/>
  &lt;target>
&lt;/project></codeblock></example>
  </refbody>
</reference>
<?Pub *0000001608?>