FlexDoc/XML - XMLDoc
- Template Summary
- XML Type
1. OverviewThe “XML File Documenter” (or “XMLDoc”) set of templates compiles any number of generic XML files into a nice looking web-ready HTML or printable RTF documentation with the optional inclusion of a namespace binding report.
It may also serve as an example of a very simple and, at the same time, practically useful application of FlexDoc/XML. See templates to learn how it works.
The set includes two main templates (i.e. those to be specified directly in the generator dialog or on the command line with -template option):
- SingleDoc.tpl template can be used to generate single file documentation in any output format supported by FlexDoc. See RTF demo and Plain HTML demo.
- FramedDoc.tpl template is a variant of the same but designed to generate a framed HTML documentation. See Framed HTML demo.
2. ExamplesThe following XML file demo documentation has been generated from three XSL files (XSL is a subset of XML that encodes XSLT scripts) found in Apache Ant software package.
We have chosen those files simply because we use Apache Ant itself (without learning much what those XSLT scripts do).
You can download the whole demo documentation shown on this page by clicking on the file link: xmldoc-demo.zip (26 Kb).
RTF demoThe following pages are from an RTF document generated with SingleDoc.tpl template (click on the screenshot to see the real size page preview):
Plain HTML demoThis is actually the same document as RTF above generated with SingleDoc.tpl template, however, now it is in HTML format (click on the screenshot to see the real HTML):
Framed HTML demoThe following is a framed HTML variant generated with FramedDoc.tpl template (click on the screenshot to see the real HTML):
3. Template SummaryThe “XML File Documenter” 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:
|SingleDoc.tpl||generates a single-file documentation from all specified XML files in any supported output format||generator|
|FramedDoc.tpl||generates a framed HTML documentation with a separate document for each XML file and table of contents frame||generator|
|Document.tpl||processes a single XML file||SingleDoc.tpl, FramedDoc.tpl|
|xmlns-bindings.tpl||generates Namespace Bindings report||SingleDoc.tpl, FramedDoc.tpl|
|TOC.tpl||generates summary frame document||FramedDoc.tpl|
|about.tpl||prints the about information at the bottom of document||SingleDoc.tpl, Document.tpl, xmlns-bindings.tpl|
4. XML TypeThe XML Type definition used by the “XML File Documenter” 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
xmldoc.defaultRootElement = Documents
5. SingleDoc.tplThis is the first main template included in the “XML File Documenter” template set. This template is able to compile any number of XML files of any possible types into a single document with the table of contents and optional inclusion of Namespace Bindings report (see xmlns-bindings.tpl).
Such 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.
See RTF demo and single-file HTML demo documentation generated with this template.
Template organizationThis is the screenshot of SingleDoc.tpl template open in Template Designer (click on the picture to see it in natural size): 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 DefinitionsThe SingleDoc.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:
6. FramedDoc.tplThis is the second main template included in the “XML File Documenter” 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.
The following demo documentation was generated with FramedDoc.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 organizationThe FramedDoc.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. 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 structureThe only file directly produced by the FramedDoc.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 FramedDoc.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.
7. Document.tplThe 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 SingleDoc.tpl template to document an XML file as part of a single output document
- From the FramedDoc.tpl to generate a separate HTML document for each particular XML file
The template consists of the following parts: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 blockThe 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):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
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-sectionStock-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:stock-section calls itself to process nested nodes – children of the one it received.
“AttrList” stock-sectionThis stock-section does a very simple work. It prints the list of attributes of an XML element. 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
'xmlns'or starts with
- The bottom section is for any other attributes.
8. xmlns-bindings.tplThis template generates the Namespace Bindings report like the one shown of the following screenshot:
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):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^::
- 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.
9. TOC.tplThis template is called from FramedDoc.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): #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).