| 1 | <?xml version="1.0" encoding="UTF-8"?>
|
|---|
| 2 | <!DOCTYPE html
|
|---|
| 3 | PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|---|
| 4 | <html xml:lang="en-us" lang="en-us">
|
|---|
| 5 | <head>
|
|---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
|
|---|
| 7 | <meta name="copyright" content="(C) Copyright 2005"/>
|
|---|
| 8 | <meta name="DC.rights.owner" content="(C) Copyright 2005"/>
|
|---|
| 9 | <meta name="DC.Type" content="reference"/>
|
|---|
| 10 | <meta name="DC.Title" content="Creating a new plug-in extension point"/>
|
|---|
| 11 | <meta name="abstract" content="If your plug-in needs to define its own extension point in an XML file, add the string "_template" to the filename before the file suffix. During integration, this file will be processed like the built-in DITA-OT templates."/>
|
|---|
| 12 | <meta name="description" content="If your plug-in needs to define its own extension point in an XML file, add the string "_template" to the filename before the file suffix. During integration, this file will be processed like the built-in DITA-OT templates."/>
|
|---|
| 13 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugins-overview.html"/>
|
|---|
| 14 | <meta name="DC.Format" content="XHTML"/>
|
|---|
| 15 | <meta name="DC.Identifier" content="plugin-newextensions"/>
|
|---|
| 16 | <meta name="DC.Language" content="en-us"/>
|
|---|
| 17 | <link rel="stylesheet" type="text/css" href="../commonltr.css"/>
|
|---|
| 18 | <link rel="stylesheet" type="text/css" href="../dita-ot-doc.css"/>
|
|---|
| 19 | <title>Creating a new plug-in extension point</title>
|
|---|
| 20 | </head>
|
|---|
| 21 | <body id="plugin-newextensions">
|
|---|
| 22 |
|
|---|
| 23 |
|
|---|
| 24 | <h1 class="title topictitle1">Creating a new plug-in extension point</h1>
|
|---|
| 25 |
|
|---|
| 26 |
|
|---|
| 27 | <div class="body refbody"><p class="shortdesc">If your plug-in needs to define its own extension point in an XML file, add the string
|
|---|
| 28 | "<samp class="ph codeph">_template</samp>" to the filename before the file suffix. During integration, this
|
|---|
| 29 | file will be processed like the built-in DITA-OT templates.</p>
|
|---|
| 30 |
|
|---|
| 31 | <div class="section"><p class="p">Template files are used to integrate most DITA-OT extensions. For example, the file
|
|---|
| 32 | <span class="ph filepath">dita2xhtml_template.xsl</span> contains all of the default rules for
|
|---|
| 33 | converting DITA topics to XHTML, along with an integration point for plug-in extensions.
|
|---|
| 34 | When the integrator runs, the file dita2xhtml.xsl is recreated, and the integration point is
|
|---|
| 35 | replaced with references to all appropriate plug-ins.</p>
|
|---|
| 36 | <p class="p">To mark a new file as a template
|
|---|
| 37 | file, use the <samp class="ph codeph"><template></samp> element.</p>
|
|---|
| 38 |
|
|---|
| 39 | <p class="p">The template extension namespace has the URI
|
|---|
| 40 | <samp class="ph codeph">http://dita-ot.sourceforge.net</samp>. It is used to identify elements and
|
|---|
| 41 | attributes that have a special meaning in template processing. This documentation uses a
|
|---|
| 42 | prefix of <samp class="ph codeph">dita:</samp> for referring to elements in the template extension
|
|---|
| 43 | namespace. However, template files are free to use any prefix, provided that there is a
|
|---|
| 44 | namespace declaration that binds the prefix to the URI of the template extension namespace.
|
|---|
| 45 | </p>
|
|---|
| 46 |
|
|---|
| 47 | </div>
|
|---|
| 48 |
|
|---|
| 49 | <div class="section"><h2 class="title sectiontitle"><samp class="ph codeph">dita:extension</samp> element</h2>
|
|---|
| 50 |
|
|---|
| 51 | <p class="p">The <samp class="ph codeph">dita:extension</samp> elements are used to insert generated content during
|
|---|
| 52 | integration process. There are two required attributes:</p>
|
|---|
| 53 |
|
|---|
| 54 | <ul class="ul">
|
|---|
| 55 | <li class="li">The <samp class="ph codeph">id</samp> attribute defines the extension point ID which provides the
|
|---|
| 56 | argument data.</li>
|
|---|
| 57 |
|
|---|
| 58 | <li class="li">The <samp class="ph codeph">behaviour</samp> attribute defines which processing action is used.</li>
|
|---|
| 59 |
|
|---|
| 60 | </ul>
|
|---|
| 61 |
|
|---|
| 62 | <p class="p">Supported values for <samp class="ph codeph">behavior</samp> attribute:</p>
|
|---|
| 63 |
|
|---|
| 64 | <dl class="dl">
|
|---|
| 65 |
|
|---|
| 66 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.CheckTranstypeAction</samp></dt>
|
|---|
| 67 |
|
|---|
| 68 | <dd class="dd">Create Ant condition elements to check if <samp class="ph codeph">${transtype}</samp> property value
|
|---|
| 69 | equals a supported transtype value.</dd>
|
|---|
| 70 |
|
|---|
| 71 |
|
|---|
| 72 |
|
|---|
| 73 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.ImportAntLibAction</samp></dt>
|
|---|
| 74 |
|
|---|
| 75 | <dd class="dd">Create Ant <samp class="ph codeph">pathelement</samp> elements for <a class="xref" href="plugin-javalib.html" title="If your Ant or XSLT extensions require additional Java libraries in the classpath, you can add them to the global DITA-OT classpath with the following feature.">library imported extension point</a>. The <samp class="ph codeph">id</samp>
|
|---|
| 76 | attribute is used to define the extension point ID.</dd>
|
|---|
| 77 |
|
|---|
| 78 |
|
|---|
| 79 |
|
|---|
| 80 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.ImportPluginCatalogAction</samp></dt>
|
|---|
| 81 |
|
|---|
| 82 | <dd class="dd">Include plug-in metadata catalog content.</dd>
|
|---|
| 83 |
|
|---|
| 84 |
|
|---|
| 85 |
|
|---|
| 86 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.ImportPluginInfoAction</samp></dt>
|
|---|
| 87 |
|
|---|
| 88 | <dd class="dd">Create plug-in metadata Ant properties.</dd>
|
|---|
| 89 |
|
|---|
| 90 |
|
|---|
| 91 |
|
|---|
| 92 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.ImportStringsAction</samp></dt>
|
|---|
| 93 |
|
|---|
| 94 | <dd class="dd">Include plug-in string file content base on <a class="xref" href="plugin-addgeneratedtext.html" title="Generated text is the term for strings that are automatically added by the build, such as "Note" before the contents of a <note> element.">generated text extension point</a>. The <samp class="ph codeph">id</samp> attribute
|
|---|
| 95 | is used to define the extension point ID.</dd>
|
|---|
| 96 |
|
|---|
| 97 |
|
|---|
| 98 |
|
|---|
| 99 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.ImportXSLAction</samp></dt>
|
|---|
| 100 |
|
|---|
| 101 | <dd class="dd">Create <samp class="ph codeph">xsl:import</samp> elements based on <a class="xref" href="plugin-overridestyle.html" title="The XSLT import extension points are used to override various steps of XSLT processing. For this, the extension attribute indicates the step that the override applies to; the file attribute is a relative path to the override within the current plugin. The plugin installer will add an XSL import statement to the default code so that your override becomes a part of the normal build.">XSLT import extension point</a>. The
|
|---|
| 102 | <samp class="ph codeph">id</samp> attribute is used to define the extension point ID.</dd>
|
|---|
| 103 |
|
|---|
| 104 |
|
|---|
| 105 |
|
|---|
| 106 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.InsertAction</samp></dt>
|
|---|
| 107 |
|
|---|
| 108 | <dd class="dd">Include plug-in conductor content based on <a class="xref" href="plugin-anttarget.html" title="The Ant conductor extension point is used to make new targets available to the Ant processing pipeline. This may be done as part of creating a new transform, extending pre-processing, or simply to provide Ant targets for the use of other plug-ins.">Ant import extension point</a>. The <samp class="ph codeph">id</samp> attribute is
|
|---|
| 109 | used to define the extension point ID.</dd>
|
|---|
| 110 |
|
|---|
| 111 |
|
|---|
| 112 |
|
|---|
| 113 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.InsertAntActionRelative</samp></dt>
|
|---|
| 114 |
|
|---|
| 115 | <dd class="dd">Include plug-in conductor content based on <a class="xref" href="plugin-anttarget.html" title="The Ant conductor extension point is used to make new targets available to the Ant processing pipeline. This may be done as part of creating a new transform, extending pre-processing, or simply to provide Ant targets for the use of other plug-ins.">relative Ant import extension point</a>. The <samp class="ph codeph">id</samp>
|
|---|
| 116 | attribute is used to define the extension point ID.</dd>
|
|---|
| 117 |
|
|---|
| 118 |
|
|---|
| 119 |
|
|---|
| 120 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.InsertCatalogActionRelative</samp></dt>
|
|---|
| 121 |
|
|---|
| 122 | <dd class="dd">Include plug-in catalog content based on <a class="xref" href="plugin-xmlcatalog.html" title="The XML Catalogs extension point is used to update the XML Catalogs used to resolve DTD or Schema document types, or to add URI mappings. This is required in order to support DITA specializations or new DITA document type shells.">catalog import extension point</a>. The <samp class="ph codeph">id</samp> attribute
|
|---|
| 123 | is used to define the extension point ID.</dd>
|
|---|
| 124 |
|
|---|
| 125 |
|
|---|
| 126 |
|
|---|
| 127 | <dt class="dt dlterm"><samp class="ph codeph">org.dita.dost.platform.ListTranstypeAction</samp></dt>
|
|---|
| 128 |
|
|---|
| 129 | <dd class="dd">Create a pipe delimited list of supported transtypes.</dd>
|
|---|
| 130 |
|
|---|
| 131 |
|
|---|
| 132 | </dl>
|
|---|
| 133 |
|
|---|
| 134 | </div>
|
|---|
| 135 |
|
|---|
| 136 | <div class="section" id="plugin-newextensions__section_vfc_gvw_mg"><h2 class="title sectiontitle"><samp class="ph codeph">dita:extension</samp> attribute</h2>
|
|---|
| 137 |
|
|---|
| 138 | <p class="p">The <samp class="ph codeph">dita:extension</samp> attribute is used to process attributes in elements
|
|---|
| 139 | which are not in template extension namespace. The value of the attribute is a space
|
|---|
| 140 | delimited tuple, where the first item is the name of the attribute to process and the second
|
|---|
| 141 | item is the action ID.</p>
|
|---|
| 142 |
|
|---|
| 143 | <p class="p">Supported values:</p>
|
|---|
| 144 |
|
|---|
| 145 | <dl class="dl">
|
|---|
| 146 |
|
|---|
| 147 | <dt class="dt dlterm"><samp class="ph codeph">depends org.dita.dost.platform.InsertDependsAction</samp></dt>
|
|---|
| 148 |
|
|---|
| 149 | <dd class="dd">Ant target dependency list is processed to replace all target names which start with
|
|---|
| 150 | an open curly bracket and end with a close curly bracket. The value of the extension
|
|---|
| 151 | point is the ID between the curly brackets.</dd>
|
|---|
| 152 |
|
|---|
| 153 |
|
|---|
| 154 | </dl>
|
|---|
| 155 |
|
|---|
| 156 | </div>
|
|---|
| 157 |
|
|---|
| 158 | <div class="example"><h2 class="title sectiontitle">Example</h2><p class="p">The following plug-in defines
|
|---|
| 159 | <span class="ph filepath">myBuildFile_template.xml</span> as a new template for extensions, and two
|
|---|
| 160 | new extension points.</p>
|
|---|
| 161 | <pre class="pre codeblock"><plugin id="com.example.new-extensions">
|
|---|
| 162 | <extension-point id="com.example.new-extensions.pre"
|
|---|
| 163 | name="Custom target preprocess"/>
|
|---|
| 164 | <extension-point id="com.example.new-extensions.content"
|
|---|
| 165 | name="Custom target content"/>
|
|---|
| 166 | <template file="myBuildFile_template.xml"/>
|
|---|
| 167 | </plugin></pre>
|
|---|
| 168 |
|
|---|
| 169 | <p class="p">When the integrator runs, this will be used to recreate
|
|---|
| 170 | <span class="ph filepath">myBuildFile.xml</span>, replacing Ant file content based on extension point
|
|---|
| 171 | use.</p>
|
|---|
| 172 |
|
|---|
| 173 | <pre class="pre codeblock"><project xmlns:dita="http://dita-ot.sourceforge.net">
|
|---|
| 174 | <target name="dita2custom"
|
|---|
| 175 | depends="dita2custom.init,
|
|---|
| 176 | {com.example.new-extensions.pre},
|
|---|
| 177 | dita2xhtml"
|
|---|
| 178 | dita:extension="depends org.dita.dost.platform.InsertDependsAction">
|
|---|
| 179 | <dita:extension id="com.example.new-extensions.content"
|
|---|
| 180 | behaviour="org.dita.dost.platform.InsertAction"/>
|
|---|
| 181 | <target>
|
|---|
| 182 | </project></pre>
|
|---|
| 183 | </div>
|
|---|
| 184 |
|
|---|
| 185 | </div>
|
|---|
| 186 |
|
|---|
| 187 | <div class="related-links">
|
|---|
| 188 | <div class="familylinks">
|
|---|
| 189 | <div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../dev_ref/plugins-overview.html" title="The DITA Open Toolkit comes with a built in mechanism for adding in extensions through plug-ins. These plug-ins may do a wide variety of things, such as adding support for specialized DITA DTDs or Schemas, integrating processing overrides, or even providing entirely new output transforms. Plug-ins are the best way to extend the toolkit in a way that is consistent, easily sharable, and easy to preserve through toolkit upgrades.">Creating DITA-OT plug-ins</a></div>
|
|---|
| 190 | </div>
|
|---|
| 191 | </div>
|
|---|
| 192 |
|
|---|
| 193 | </body>
|
|---|
| 194 | </html>
|
|---|
