FlexDoc/XML - XMLDoc
- Template Summary
- XML Type
- 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.
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).SingleDoc.tpl template (click on the screenshot to see the real size page preview):
|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|
xmldoc.name = Generic XML Files xmldoc.pseudo-elements.all = true xmldoc.defaultRootElement = Documents
xmldoc.defaultRootElement = Documents
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.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. 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:
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. 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.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.
- 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). 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.
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.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:stock-section calls itself to process nested nodes – children of the one it received. 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.
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.
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).FlexDoc/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: