| 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 DITA-OT plug-ins"/>
|
|---|
| 11 | <meta name="abstract" content="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."/>
|
|---|
| 12 | <meta name="description" content="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."/>
|
|---|
| 13 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/developer-reference.html"/>
|
|---|
| 14 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-configfile.html"/>
|
|---|
| 15 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-xmlcatalog.html"/>
|
|---|
| 16 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-anttarget.html"/>
|
|---|
| 17 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-antpreprocess.html"/>
|
|---|
| 18 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-newtranstype.html"/>
|
|---|
| 19 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-overridestyle.html"/>
|
|---|
| 20 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-addgeneratedtext.html"/>
|
|---|
| 21 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-xsltparams.html"/>
|
|---|
| 22 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-javalib.html"/>
|
|---|
| 23 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-messages.html"/>
|
|---|
| 24 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-dependencies.html"/>
|
|---|
| 25 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-support.html"/>
|
|---|
| 26 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-newextensions.html"/>
|
|---|
| 27 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/plugin-sample.html"/>
|
|---|
| 28 | <meta name="DC.Format" content="XHTML"/>
|
|---|
| 29 | <meta name="DC.Identifier" content="plugins-overview"/>
|
|---|
| 30 | <meta name="DC.Language" content="en-us"/>
|
|---|
| 31 | <link rel="stylesheet" type="text/css" href="../commonltr.css"/>
|
|---|
| 32 | <link rel="stylesheet" type="text/css" href="../dita-ot-doc.css"/>
|
|---|
| 33 | <title>Creating DITA-OT plug-ins</title>
|
|---|
| 34 | </head>
|
|---|
| 35 | <body id="plugins-overview">
|
|---|
| 36 |
|
|---|
| 37 |
|
|---|
| 38 | <h1 class="title topictitle1">Creating DITA-OT plug-ins</h1>
|
|---|
| 39 |
|
|---|
| 40 |
|
|---|
| 41 | <div class="body refbody"><p class="shortdesc">The DITA Open Toolkit comes with a built in mechanism for
|
|---|
| 42 | adding in extensions through plug-ins. These plug-ins may do a wide
|
|---|
| 43 | variety of things, such as adding support for specialized DITA DTDs
|
|---|
| 44 | or Schemas, integrating processing overrides, or even providing entirely
|
|---|
| 45 | new output transforms. Plug-ins are the best way to extend the toolkit
|
|---|
| 46 | in a way that is consistent, easily sharable, and easy to preserve
|
|---|
| 47 | through toolkit upgrades.</p>
|
|---|
| 48 |
|
|---|
| 49 | <div class="section"><p class="p">A plug-in consists of a directory, typically stored directly within the
|
|---|
| 50 | <span class="ph filepath">plugins/</span> directory inside of the DITA-OT. Every plug-in is controlled
|
|---|
| 51 | by a file named <span class="ph filepath">plugin.xml</span>, located in the plug-in's root
|
|---|
| 52 | directory.</p>
|
|---|
| 53 | <div class="p">Benefits
|
|---|
| 54 | of extending the toolkit through plug-ins include:<ul class="ul">
|
|---|
| 55 | <li class="li">Plug-ins are easily sharable with other users, teams, or companies;
|
|---|
| 56 | typically, all that is needed is to unzip and run a single integration
|
|---|
| 57 | step. With many builds, even that integration step is automatic.</li>
|
|---|
| 58 |
|
|---|
| 59 | <li class="li">Allows overrides or customizations to grow from simple to complex
|
|---|
| 60 | over time, with no increased complexity to the extension mechanism.</li>
|
|---|
| 61 |
|
|---|
| 62 | <li class="li">Plug-ins can be moved from version to version with an upgraded
|
|---|
| 63 | toolkit simply by unzipping again, or by copying the directory from
|
|---|
| 64 | one install to another; there is no need to re-integrate code based
|
|---|
| 65 | on updates to the core processing.</li>
|
|---|
| 66 |
|
|---|
| 67 | <li class="li">Plug-ins can build upon each other. If you like a plug-in provided
|
|---|
| 68 | by one user, simply install that plug-in, and then create your own
|
|---|
| 69 | that builds on that extension. The two plug-ins can then be distributed
|
|---|
| 70 | to your team as a unit, or you can even share your own extensions
|
|---|
| 71 | with the original provider.</li>
|
|---|
| 72 |
|
|---|
| 73 | </ul>
|
|---|
| 74 | </div>
|
|---|
| 75 | </div>
|
|---|
| 76 |
|
|---|
| 77 | </div>
|
|---|
| 78 |
|
|---|
| 79 | <div class="related-links">
|
|---|
| 80 | <ul class="ullinks">
|
|---|
| 81 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-configfile.html">Plug-in configuration file</a></strong><br/>
|
|---|
| 82 | The <span class="ph filepath">plugin.xml</span> controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and integrates those changes into the core code.</li>
|
|---|
| 83 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-xmlcatalog.html">Extending the XML Catalog</a></strong><br/>
|
|---|
| 84 | 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.</li>
|
|---|
| 85 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-anttarget.html">Adding new targets to the Ant build process</a></strong><br/>
|
|---|
| 86 | 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.</li>
|
|---|
| 87 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-antpreprocess.html">Adding Ant targets to the pre-process pipeline</a></strong><br/>
|
|---|
| 88 | Every step in the pre-process pipeline defines an extension point before and after the step, to allow plug-ins to integrate additional processing. This allows a plug-in to insert a new step before any pre-processing step, as well as before or after the entire preprocess pipeline.</li>
|
|---|
| 89 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-newtranstype.html">Integrating a new transform type</a></strong><br/>
|
|---|
| 90 | Plug-ins may integrate an entire new transform type. The new transform type can be very simple, such as an XHTML build that creates an additional control file; it can also be very complex, adding any number of new processing steps.</li>
|
|---|
| 91 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-overridestyle.html">Override styles with XSLT</a></strong><br/>
|
|---|
| 92 | 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 <samp class="ph codeph">file</samp> 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.</li>
|
|---|
| 93 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-addgeneratedtext.html">Modifying or adding generated text</a></strong><br/>
|
|---|
| 94 | Generated text is the term for strings that are automatically added by the build, such as "Note" before the contents of a <note> element.</li>
|
|---|
| 95 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-xsltparams.html">Passing parameters to existing XSLT steps</a></strong><br/>
|
|---|
| 96 | Plug-ins can define new parameters to be passed from the Ant build into existing XSLT pipeline stages, usually to have those parameters available as global <samp class="ph codeph"><xsl:param></samp> values within XSLT overrides.</li>
|
|---|
| 97 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-javalib.html">Adding Java libraries to the classpath</a></strong><br/>
|
|---|
| 98 | 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.</li>
|
|---|
| 99 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-messages.html">Adding diagnostic messages</a></strong><br/>
|
|---|
| 100 | Plug-in specific warning and error messages can be added to the set of messages supplied by the DITA-OT. These messages can then be used by any XSLT override.</li>
|
|---|
| 101 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-dependencies.html">Managing plug-in dependencies</a></strong><br/>
|
|---|
| 102 | The <samp class="ph codeph"><require></samp> element in a <span class="ph filepath">plugin.xml</span> file is used to create a dependency on another plug-in. The <samp class="ph codeph"><require></samp> element requires the <samp class="ph codeph">plugin</samp> attribute in order to reference the dependency.</li>
|
|---|
| 103 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-support.html">Version and support information</a></strong><br/>
|
|---|
| 104 | The following extension points are used by convention to define version and support info within a plug-in.</li>
|
|---|
| 105 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-newextensions.html">Creating a new plug-in extension point</a></strong><br/>
|
|---|
| 106 | If your plug-in needs to define its own extension point in an XML file, add the string "<samp class="ph codeph">_template</samp>" to the filename before the file suffix. During integration, this file will be processed like the built-in DITA-OT templates.</li>
|
|---|
| 107 | <li class="link ulchildlink"><strong><a href="../dev_ref/plugin-sample.html">Example plugin.xml file</a></strong><br/>
|
|---|
| 108 | The following is a sample of a <span class="ph filepath">plugin.xml</span> file. This file adds support for a new set of specialized DTDs, and includes an override for the XHTML output processor.</li>
|
|---|
| 109 | </ul>
|
|---|
| 110 |
|
|---|
| 111 | <div class="familylinks">
|
|---|
| 112 | <div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../dev_ref/developer-reference.html" title="The DITA Open Toolkit Developer Reference is designed to provide more advanced information about the DITA OT. It is geared to an audience that needs information about the DITA-OT architecture, configuring and extending the DITA-OT, and creating DITA-OT plug-ins.">DITA Open Toolkit Developer Reference</a></div>
|
|---|
| 113 | </div>
|
|---|
| 114 | </div>
|
|---|
| 115 |
|
|---|
| 116 | </body>
|
|---|
| 117 | </html>
|
|---|
