13.1. The "GenericInclusion" inclusion processor

The "GenericInclusion" inclusion processor is a general purpose, extensible, inclusion processor which allows to run commands which generate one or more elements on the fly in order to include these generated elements in the document being opened.

For example, using this inclusion processor, it is possible to execute a shell script (or .bat file) which queries a database, which converts what has been returned by the query to row elements and which adds these row elements to the tbody of a DocBook table. Like any other included element, the row elements included this way are made read-only, are automatically refreshed each time the document is reopened, may be refreshed by hand by using View|Redraw (Ctrl-L), etc.

Example 7.6. Simple date inclusion example

DocBook document sample.xml contains:

...
<?xxe-begin-inclusion %C/date.sh?>
<phrase>Wed Jun 7 18:03:34 CEST 2006</phrase>
<?xxe-end-inclusion ?>
...

where date.sh is this simple shell script:

#!/bin/sh
now=`date`
echo "<?xml version='1.0'?><phrase><![CDATA[$now]]></phrase>"

Unlike the "XInclude" inclusion processor which is predeclared, the "GenericInclusion" inclusion processor needs to be declared in a configuration in order to be used by XXE. Let's suppose the user has added this snippet[9] to docbook.xxe, the DocBook configuration for XXE:

  <inclusionProcessor name="GenericInclusion">
    <class>com.xmlmind.xmleditapp.genericincl.GenericInclusionProcessor</class>
  </inclusionProcessor>

Each time sample.xml is opened, XXE invokes the "XInclude" inclusion processor and then, because this processor has been declared in docbook.xxe, the "GenericInclusion" inclusion processor.

The "GenericInclusion" inclusion processor replaces all the elements found between <?xxe-begin-inclusion?>/<?xxe-end-inclusion?> pairs by the elements generated by the command which is contained in <?xxe-begin-inclusion?>. For this example, the command is "%C/date.sh"[10].

The <?xxe-begin-inclusion?>/<?xxe-end-inclusion?> pairs themselves are removed and included elements are made read-only and are marked as being managed by the "GenericInclusion" inclusion processor.

Then, each time sample.xml is saved, XXE requests the included elements having the "GenericInclusion" inclusion mark to restore their inclusion directives, that is, to restore the <?xxe-begin-inclusion?>/<?xxe-end-inclusion?> pairs.


Just like commands copyAsInclusion and include create included elements which are managed by the "XInclude" inclusion processor, there is command, generally called genericInclude, which may be used to create included elements which are managed by the "GenericInclusion" inclusion processor. This generic inclusion command is documented in Section 95, “A generic inclusion command” in XMLmind XML Editor - Commands.



[9] The easiest way to do so is to include genericincl.incl in the XXE configuration file (for this example, docbook.xxe).

[10] %C is the name of the directory containing the XXE configuration file where the "GenericInclusion" inclusion processor has been declared.

This makes it easy deploying the shell scripts invoked by the "GenericInclusion" inclusion processor: suffice to copy them in the directory containing the XXE configuration file.