• FlexDoc/XML
• XSDDoc
• Templates

FlexDoc/XML - XSDDoc - Templates

1. Overview
2. XML Type
3. Main Templates
   • FramedDoc.tpl
   • SingleDoc.tpl
4. Template Parameters
5. Subtemplates

1. Overview

{flexdoc-xml}/templates/XSDDoc/

The XSDDoc directory will be referred further simply as '{XSDDoc}'.

Here, you will find two main templates:

1. FramedDoc.tpl to generate framed HTML documentation
2. SingleDoc.tpl to generate single-file both RTF and HTML documentation

The entire «XSDDoc» template set (version 2.9.5) consists of 67 templates.

2. XML Type

{XSDDoc}/xsddoc.xmltype

1 2 3 4 5 6 7 8 9 10 11 12 13

xsddoc.name = W3C XML Schema Files xsddoc.doc = Represents any number of W3C XML Schema Definition (XSD) files xsddoc.xsd.files = http://www.w3.org/2001/XMLSchema.xsd xsddoc.xsd.catalogs = urn:flexdoc-xyz:xml:defaultcatalog xsddoc.xsd.includeAbstractTypes = true xsddoc.ns.1.prefix = xs xsddoc.ns.1.uri = http://www.w3.org/2001/XMLSchema xsddoc.ns.2.prefix = xhtml xsddoc.ns.2.uri = http://www.w3.org/1999/xhtml xsddoc.pseudo-elements.all = on xsddoc.defaultRootElement = Documents xsddoc.imageProvider.name = %IMAGE_PROVIDER% xsddoc.imageProvider.classPath = %IMAGE_PROVIDER_CLASSPATH%

The screenshot on the left shows a part of the tree representation of the element types and their attributes constructed by this XML Type definition (click on the picture to see a more expanded tree view).

3. Main Templates

FramedDoc.tpl

On left the you can see how this template looks when open in the Template Designer (click to enlarge). On the right is a sample documentation generated with it (click to view the HTML):

The FramedDoc.tpl template is interpreted as follows:

1. First, the «Template Init Expression» specified in the template properties is processed:

   

2. This, in turn, invokes the execution of «Init» stock-section (click on the screenshot to enlarge):

   

   This stock-section does not generate any output. Rather, it calls from itself some subtemplates for special purposes:
   1. init.tpl loads all XML schema files to be processed/documented (including those references from them directly or indirectly). It also creates element maps, which are essentially hash-maps. Element maps allow resolving very complicated queries. They are used in almost everywhere in XSDDoc template set (including even in init.tpl itself) and are critical for working of everything.
   2. Further, the Folder section «prepare diagramming engine» is processed, within which one of the procedure subtemplates is called according to the the specified diagramming plugin (see XML Type | Line 12):
      • DiagramKit.tpl – in case of FlexDoc/XML DiagramKit
      The purpose of those templates is to initialize the corresponding diagramming plugin, that is passing to it the information about each XSD component, which is necessary to generate its diagram (across all XML schemas to be documented that was collected by the init.tpl template).

      The template communicates with the diagramming plugin using special FlexQuery functions and properties registered and provided by it.

      What happens next depends on the particular plugin. It may call some external diagramming engine to generate all the diagrams immediately or keep the component information so as to generate each diagram on request (see FlexDoc/XML | Features | Element Images).
3. Further, the template's root section block is processed (which is the content of the «FramedDoc.tpl» tab):

   

   It does the following:
   1. overview-summary.tpl template is called to generate «Overview Summary» page for the whole documentation.
   2. all-components-summary.tpl template is called to generate «All Component Summary» page.
   3. All XML schemas (to be documented) are itereated.
      For each schema:
      1. schema-overview.tpl template generates the «Schema Overview» page.
      2. schema-source.tpl template generates the «Schema XML Source» page.
      3. schema-frame.tpl template generates «Schema» navigation page.
      4. For all global components and local element components (to be documented separately) that belong to the namespace the following templates are called (depending on the component type):
         • element.tpl
         • complexType.tpl
         • simpleType.tpl
         • group.tpl
         • globalAttribute.tpl
         • attributeGroup.tpl
         to generate the corresponding «Component Documentation» files.
   4. All namespaces targeted by the XML schemas to be documented are itereated.
      For each namespace:
      1. namespace-overview.tpl template generates «Namespace Overview» navigation page.
      2. namespace-frame.tpl template generates «Namespace» navigation page.
   5. all-components-frame.tpl template is called to generate «All Components» navigation page.
   6. overview-frame.tpl template is called to generate the page shown in the «Overview Frame».
   7. xmlns-bindings.tpl template is called to generate the «XML Namespace Bindings» page.
4. At this point, all document files have been generated. What is left is the HTML frameset file (normally named 'index.html'). That file starts the whole documentation to display particular HTML documents in three frame windows:

   

   The frameset file is generated according to the definition specified in the «Output File | Frameset Structure» tab of the FramedDoc.tpl properties dialog:

   

   The expression specified in the «Source Expression» field (on the right panel) should return the pathname (or URL) of a document to be initially loaded in the given frame.

   However, the initial content of the «Detail Frame» may be overridden dynamically by the Javascript, which is inserted in index.html according the «HTML Head Expression»:

   

   This particular Javascript obtains a URL parameter (specified after '?' in the initial URL) passed to index.html. If the parameter exists, the detailFrame will be reloaded according to the new URL found in the parameter. That allows you to construct URLs like this one:

   https://www.flexdoc.xyz/flexdoc-xml/xsddoc/examples/html/XMLSchema/index.html?schemas/XMLSchema_xsd/elements/element.html

   which will open the frameset documentation directly on a specified page.

SingleDoc.tpl

Below on the left you can see SingleDoc.tpl open in the Template Designer (click to enlarge). The selected is the Call Template section, which calls element.tpl to generate «Element Documentation» blocks. On the right are the selected section's properties, where the output into the same document is specified.

Here are a few screenshots of sample documentation generated with SingleDoc.tpl. The leftmost one shows a single-file HTML documentation (click to view the HTML). Others are pages of RTF documentation (click to enlarge):

4. Template Parameters

XSDDoc is controlled by more than 400 external parameters. On the left screenshot below you can see the parameter definitions of FramedDoc.tpl. On the right is the Parameter Inspector built by those definitions (click to enlarge):

To make so many parameters manageable, they are organized in a tree. Also, the default values of many parameters are calculated dynamically from the values of other parameters and properties. This helps you with setting of lots related parameters. Just a few most important ones may need to be changed to achieve necessary effects.

Below you can see how doc.comp.diagram parameter is defined (which is the one selected in the left screenshot above). On the right is the FlexQuery expression that calculates the default value of this parameter:

When the same parameter is defined in a subtemplate, it receives its value from the nearest equally named parameter in the template call chain. Such propagation of parameter values happens automatically. However, it can be overridden in any particular Call Template section, so as to pass different values (as well as the values of those parameters defined locally only in the called subtemplate), as it is shown in the screenshot below:

5. Subtemplates

Subtemplates are normal FlexDoc/XML templates. However, they are typically not designed to run directly from the generator as the main templates – that will cause an error or produce meaningless output.

• [lib]
• [lib/ann]
• [lib/attribute]
• [lib/component]
• [lib/diagramming]
• [lib/element]
• [lib/groups]
• [lib/images]
• [lib/namespace]
• [lib/schema]
• [lib/type]
• [lib/xml]