Command-line utility w2x and desktop application w2x-app support plugins.
Let’s suppose you have created a plugin called “rss” which may be used to convert DOCX to RSS. Once registered with w2x, this plugin may be invoked as it were a stock conversion, for example:
w2x -o rss my.docx my.xml
Other example, using a plugin called “wh5_zip” (see description below):
w2x -o wh5_zip -p zip.include-top-dir false my.docx my.zip
In w2x-app, you'll find the registered plugins in the "Convert to" combobox and in the "Output format" screen of the setup assistant.
A plugin is simply a plain text file, using an UTF-8 character encoding, having a ".w2x_plugin" file suffix, containing a number of w2x command-line arguments and starting with comment lines containing information about the plugin (for example, its name). Example, w2x_install_dir/sample_plugins/rss/rss.w2x_plugin:
### plugin.name: rss
### plugin.outputDescription: RSS 2.0
### plugin.outputExtension: xml
### plugin.multiFileOutput: no
-c
-e w2x:xed/main.xed
-t rss.xslt
# Image files not useful here.
-step:com.xmlmind.w2x.processor.DeleteFilesStep:cleanUp
-p cleanUp.files "%{~pO}/%{~nO}_files"
Field Name | Default Value | Description |
| Basename of the " | The name of the plugin (a single word). |
| The name of the plugin. | A short description (just a few words) of the output format of this plugin. |
|
| Preferred extension for the files created by this plugin. |
|
| Whether this plugin creates multiple files or just a single one. A boolean: “ |
The above rss plugin converts DOCX to RSS. This process is partly implemented by XSLT 1.0 stylesheet w2x_install_dir/sample_plugins/rss/rss.xslt which is part of this plugin. Stylesheet rss.xslt transforms its input, the semantic XHTML 1.0 Transitional file created by the Edit step (invoked using -e w2x:xed/main.xed), to RSS.
Aside XSLT 1.0 stylesheets, a plugin may also include XED scripts as well as ".jar" files containing support code and/or custom conversion steps implemented in Java™. Example, w2x_install_dir/sample_plugins/wh5_zip/wh5_zip.w2x_plugin:
### plugin.outputDescription: Web Help ZIP containing "semantic" (X)HTML 5.0
### plugin.outputExtension: zip
-o webhelp5
-p webhelp.split-before-level 8
-p webhelp.use-id-as-filename yes
-p webhelp.omit-toc-root yes
-p webhelp.wh-layout simple
# Generate all HTML files in a subdirectory of the output directory
# having the same basename as the ".zip" output file.
-p convert.xhtml-file "%{~pO}/%{~nO}/%{~nO}.xhtml"
-p transform.out-file "%{~pO}/%{~nO}/%{~nO}_tmp.xhtml"
-p webhelp.out-file "%{~pO}/%{~nO}/%{~nO}.html"
-p cleanUp.files "%{~pO}/%{~nO}/%{~nO}_tmp.xhtml"
-step:ZipStep:zip
-p zip.out-file "%{O}"
The above wh5_zip plugin specializes the stock conversion called webhelp5 (Web Help containing XHTML 5.0) by giving specific values to some of its parameters (e.g. -p webhelp.wh-layout simple) and also by archiving all the output files in a single “.zip” file.
This last step, -step:ZipStep:zip, is implemented by a custom conversion step found in w2x_install_dir/sample_plugins/wh5_zip/src/ZipStep.java. This Java™ code is compiled and archived in w2x_install_dir/sample_plugins/wh5_zip/zip_step.jar by the means of ant build file w2x_install_dir/sample_plugins/wh5_zip/src/build.xml.
Note that these ".jar" files, just like the ".w2x_plugin" files, are automatically discovered and loaded by w2x and w2x-app during their startup phase.
A plugin is registered with both w2x and w2x-app by copying all its files anywhere inside directory w2x_install_dir/plugin/.
However it's strongly recommended to group all the files comprising a plugin in a subdirectory of its own having the same name as the plug-in (e.g. w2x_install_dir/plugin/rss/).
If the .dmg distribution has been used to install XMLmind Word To XML on the Mac, the plugin directory is WordToXML.app/Contents/Resources/w2x/plugin/.
Alternatively, this plugin may be installed anywhere you want provided that the directory containing the ".w2x_plugin" file is referenced in the W2X_PLUGIN_PATH environment variable. Example: set W2X_PLUGIN_PATH=C:\Users\John\w2x\rss;C:\temp\w2x_plugins.
The W2X_PLUGIN_PATH environment variable (or, equivalently, the W2X_PLUGIN_PATH Java™ system property; e.g. -DW2X_PLUGIN_PATH=C:\Users\John\w2x\rss;C:\temp\w2x_plugins) may contain absolute or relative directory paths separated by semi-colons (";"). A relative path is relative to the current working directory.
The W2X_PLUGIN_PATH environment variable may also contain "+", which is a shorthand for w2x_install_dir/plugin/. Windows example: set W2X_PLUGIN_PATH=..\sample_plugins;+. Linux/macOS example: export W2X_PLUGIN_PATH=+;/home/john/w2x_plugins.