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 | (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.