13.1. The "`GenericInclusion`" inclusion processor
Prev | 13. inclusionProcessor | Next

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

Prev | Up | Next
13. inclusionProcessor | Home | 14. menu