 DocFlex/XML - XMLDoc - Templates
- Summary
- XML Type
- XMLDoc.tpl
- XMLDocFrames.tpl
- Document.tpl
- xmlns-bindings.tpl
- TOC.tpl
- about.tpl
1. Summary
The “XML File Documentor” set of templates is based on a special “xmldoc”
XML Type, which is detailed below.
The set includes 2 main templates
and 4 subtemplates, which are summarized in the following table:
2. XML Type
The XML Type definition
used by the “XML File Documentor” templates covers a very general case of XML files.
It is not based on any DTD or XSD, but instead enables all kinds of
pseudo-elements
which represent all possible nodes of an XML document.
Here is how that definition looks:
xmldoc.name = Generic XML Files
xmldoc.pseudo-elements.all = true
xmldoc.defaultRootElement = Documents
The following tree represents the DSM Type
(Data Source Model Type) constructed by this definition (click on the picture to see
the expanded tree):
The last line of the XML Type definition:
xmldoc.defaultRootElement = Documents
says that for any main template
based on this type, the generator should open all XML files specified for the processing and pass them
to the template as children of an #DOCUMENTS
pseudo-element, which will be the template's
root element.
See <typeId>.defaultRootElement
setting for more details.
3. XMLDoc.tpl
This is the first main template
included in the “XML File Documentor” template set.
This template is able to compile any number of XML files of any possible types into
a single document with the fancy formatting, table of contents and optional inclusion of
the Namespace Bindings report (see xmlns-bindings.tpl).
Such a documentation can be generated in any supported output format (which may be
especially suitable for printing).
To specify a necessary destination output format all you need is to select
that format in “Output format” combo-box in the
generator dialog
or using
-format
option on the
generator command line.
RTF demo
Here is how an RTF documentation generated with the XMLDoc.tpl template looks
(click on the screenshot to see the real size page preview):
Plain HTML demo
The following is the same documentation however generated in HTML format
(click on the screenshot to see the real HTML):
Template organization
This is the screenshot of XMLDoc.tpl template open in
Template Designer
(click on the picture to see it in natural size):
The template is designed to process all XML files specified for the generator.
In according with the “xmldoc” XML Type,
the generator will open all those XML files and prepare them as children of
an #DOCUMENTS
pseudo-element passed to the template as its root element.
The Element Iterator
titled “DOC FOR EACH XML FILE” is actually where all XML files are processed
by calling Document.tpl subtemplate for each XML file.
Parameter Definitions
The XMLDoc.tpl template accepts a few parameters, which provides some additional
data for the generated documentation (such as title) as well as control the template behavior (e.g.
sorting of multiple XML files, inclusion of Namespace Bindings report, etc).
The following screenshots show how those parameters are defined:
This is the definition of a single parameter:
And this is how the result
Parameter Inspector looks:
4. XMLDocFrames.tpl
This is the second main template
included in the “XML File Documentor” template set.
This template is designed to generate a framed HTML documentation
with a separate document for each XML file and table of contents frame.
Framed HTML demo
The following demo documentation was generated with XMLDocFrames.tpl template.
This is a framed HTML variant of the same documentation shown in RTF demo
(click on the picture to see the real HTML):
Template organization
The XMLDocFrames.tpl template is a special
frameset template.
Its main block by itself does not produce any output at all. Instead, it calls other templates
which generate separate HTML documents.
The template's main block start with the
element iterator section,
which iterates by all XML files specified for processing by the
generator.
The generator opens each XML file and represents it as an
#DOCUMENT pseudo-element.
Such pseudo-elements are provided as children of another special pseudo-element
#DOCUMENTS,
which is the one passed to the template as its
root element.
The iterator contains a
call
to the Document.tpl template that generates
a separate HTML document for each XML file.
The next call template section
following the iterator call xmlns-bindings.tpl template which generates
the Namespace Bindings report.
The last one is a call of TOC.tpl template that generates the table of contents
HTML document.
Frameset structure
The only file directly produced by the XMLDocFrames.tpl template
is the HTML frameset document (such as 'index.html') that displays the whole
documentation.
This frameset HTML is generated by a special frameset structure definition contained
in the XMLDocFrames.tpl template and
shown on the following screenshot:
The frameset structure defines frame windows and specifies which HTML document should be initially
loaded in each frame.
The frame definition shown on the screenshot specifies that the 'detailFrame' frame
should be preloaded with the first document produced by the Document.tpl template.
That would correspond with the first item in the table of contents produced by
TOC.tpl template.
5. Document.tpl
The Document.tpl template is the one that processes a single XML file. It is used only as a subtemplate.
That means, this template is not supposed to be specified directly for the generator, rather
it is called from within both main templates:
- From the XMLDoc.tpl template to document an XML file as part of a single output
document
- From the XMLDocFrames.tpl to generate a separate HTML document
for each particular XML file
The Document.tpl template works by reproducing the original content
of an XML document. In a certain sense, it "understands" the XML document's structure and, then,
"retells" it in its own way.
The template consists of the following parts:
Besides this, there is a
hypertext target definition
specified in the template properties:
This is used to generate a hyperlink to the detail of the particular XML file
from the item representing it in the Table of Content (see TOC.tpl template).
The main block
The Document.tpl template receives an XML file to process prepared
in the form of #DOCUMENT
pseudo-element, which is passed as the template's
root element.
Then, the generator starts
processing the template's main block shown on the following screenshot (click to see in the full size):
The main block starts from the
Area Sections,
which generate the title information about the XML file.
Then, the Element Iterator
follows which iterates by all direct children of the Document node
provided by DOM (specifically, that is the node
represented by Java interface org.w3c.dom.Document).
The node associated with the XML file's <!DOCTYPE> statement is processed directly
within the iterator's body.
All other DOM nodes are processed by
“Node” stock-section.
At the very bottom, you can see the Page Footer block. This block contains
template components
to generate a page footer used in RTF documentation (see RTF demo).
That page footer displays the information specific to the given XML document.
To make it appear on the pages related to the XML file, the generator produces a separate RTF output
section per each call of the Document.tpl template.
“Node” stock-section
Stock-sections
are the template parts which behave similar to procedures in ordinary programming languages.
Each stock-section
can be called from different locations in a template (including from within this stock-section itself).
This particular
stock-section
processes an XML document's node which may contain other child nodes:
You may notice a place where this
stock-section
calls itself to process nested nodes -- children of the one it received.
“AttrList” stock-section
This
stock-section
does a very simple work. It prints the list of attributes of an XML element.
The two nested area sections
are variants of the same with slightly different text formatting.
-
The top section is executed only for reserved XML attributes (that is, when the attribute's name
is
'xmlns' or starts with 'xmlns:' or 'xml:' prefixes).
-
The bottom section is for any other attributes.
6. xmlns-bindings.tpl
This template generates the Namespace Bindings report like the one shown of the following screenshot:
When you are reading certain XML documents, sometimes you may notice that the element tags contained in them
are littered with various unknown namespace prefixes. For a big XML document, it may take some efforts
to find the location where a particular namespace prefix is defined and to which URI it is bound
(especially when that XML document is in the printed form).
The Namespace Bindings report helps to quickly find by a each prefix the namespace URI
corresponding to it and the location where that binding is defined.
The xmlns-bindings.tpl template
has a very simple structure shown on this screenshot (click to see in normal size):
Basically, the template consists of an
Element Iterator
that generates a table in which every namespace binding is represented by a row.
Here is how it works.
The template receives as its
root element
the #DOCUMENTS
pseudo-element that represents all XML files.
Then, the Element Iterator
iterates by the #NAMESPACE pseudo-elements
collected according to the following
Location Rule
(specified in the iterator properties):
* -> child::#DOCUMENT/namespaces^::#NAMESPACE
The left part of the rule is the
Location Path
which defines the search of the #NAMESPACE
elements:
-
The first step starts from the root #DOCUMENTS
element and selects all its children of #DOCUMENT
type that represent XML files.
-
The second step selects all #NAMESPACE
pseudo-elements by references obtained from values of
namespaces attribute
of each #DOCUMENT element.
This is specified using
link-axis.
7. TOC.tpl
This template is called from XMLDocFrames.tpl
to generate a summary frame document which appears in the left frame (see
Framed HTML demo).
The template is shown on the following screenshot (click to enlarge):
The template receives #DOCUMENTS
root element.
The Element Iterator
iterates by all XML documents and generates the summary list of XML files.
Each summary item is produced by a
data control
(shown on the screenshot as rectangle with “xmlName”).
This data control prints the name of each particular XML file as well as
generates a hyperlink to the XML file's detailed documentation.
The hyperlink is defined in the
data control's
properties:
When a hyperlink is generated, it is connected to the target using values of keys
generated by expressions specified in the hyperlink definition properties (see screenshot).
The corresponding target keys are generated using similar expressions
defined in the properties of Document.tpl template.
The “detailFrame” is the name of the target frame window where the HTML
document referenced by hyperlink is loaded
(see frameset structure definition).
8. about.tpl
This template just prints the information about DocFlex/XML
product together with the hyperlinks to this web-site at the bottom of each generated document.
You can easily suppress this by disabling the
Area Section,
as shown on the screenshot:
or replace it with something of your own.
| 
