Build and Add Plugins
Guidelines for building and adding plugins.
DITA Open Toolkits and plugins are stored separately on the server. This allows them to be mixed and matched when you Set up a Publishing Scenario.
Any plugins that have been selected for use will be temporarily moved into the DITA Open Toolkit during the publishing process. They are moved back into their storage location after the process is complete.
Use Cases for Plugins
There are four primary use cases for using DITA Open Toolkit plugins in easyDITA:
Using a standard DITA Open Toolkit plugin to extend or modify the DITA Open Toolkit
Adding custom CSS or XSLT to modify the styling of your output
Using a custom ANT file
Adding DITAVal files to filter output
Plugins can be any combination of these cases. But it’s often best to separate them out into small pieces to allow them to be reused in various combinations.
Protyping Your Plugin
DITA Open Toolkit plugins can be protyped on a local instance of the DITA Open Toolkit, then zipped and uploaded into easyDITA. When building a plugin, you should place your files in a folder in the plugins directory in the DITA Open Toolkit. This is because easyDITA will take the plugin and move it into this directory while it’s running the publishing process.
You should also place your source content in a directory parallel (next to) the DITA Open Toolkit you’re using to test your plugin. This more closely represents the structure easyDITA will build at publish time.
How easyDITA Runs the Build
It’s important to take into account that easyDITA is always going to pass a few parameters into the ANT build file. These parameters are:
|dita.dir||Absolute path to the DITA Open Toolkit that is being used.|
|args.input||Absolute path to the source content being published. This is always in a directory tree completely removed from the being run.|
|output.dir||Absolute path to the directory easyDITA will place the published output.|
|dita.extname||At the time of this writing, easyDITA sets the extname as the expect “.dita” extension. This may change in future releases.|
If you’re developing a plugin with an ANT file that will be the build.xml file, it’s important that these values are passed along as is. easyDITA has a highly structured publishing environment and expects these values to be as it produces them.
Other ANT parameters can be set through configuration when you Set up a Publishing Scenario.