FlexDoc/XML - XSDDoc - Templates

FramedDoc.tpl

FramedDoc.tpl is a main template designed to generate multi-file (Javadoc-like) framed HTML documentation by any number of XML schema files.

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): 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.tpl template is called to generate «Overview Summary» page for the whole documentation.
    2. all-components.tpl template is called to generate «All Component Summary» page.
    3. All XML schemas (to be documented) are itereated.
      For each schema:
      1. schema.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): 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.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:
    http://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.