Site Map   PRODUCTS ----------------------------------- DocFlex Technology    Overview    Features        Key Features        Data Processing        Formatting        Templates / Designer GUI    Documentaion        Template Components        Element Iterator (details)        CSS in generated HTML   DocFlex/XML    Overview    Features    Documentaion        Installation & Config Files        Running Generator        Designing Templates        Sample            XMLDoc            Sales Report            Alternative to XSLT        Tutorials    XSDDoc        Templates        Parameter Tree        Examples        FAQ    WSDLDoc        Templates        Examples    DiagramKit    Integrations        Apache Ant        Apache Maven        XMLSpy        Oxygen XML   DocFlex/Javadoc    Overview    Documentaion        Installation & Config Files        DocFlex Doclet        Integrations        FAQ    JavadocClassic        Templates        Parameters        Examples    Tutorials   DocFlex/Together    Overview    Examples    Basic Templates    Documentaion    Tutorials   TRY ----------------------------------- Downloads Registration Trial License   USE ----------------------------------- Licensing Shop Support   COMPANY ----------------------------------- News Products Customers User Forum About Us Imprint Legal    Terms of Use    Business Terms & Conditions    End User License Terms Contact Links

DocFlex/XML - XSDDoc - Templates

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

1.  Overview

{docflex-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

Besides them, there are many other templates (called subtemplates) that are used internally. Those templates work as procedures invoked from the main templates as well as from each other.

The entire «XSDDoc» template set (version 2.9.1) consists of 69 templates.

2.  XML Type

{XSDDoc}/xsddoc.xmltype

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

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:docflex-com: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.class = %IMAGE_PROVIDER_CLASS% xsddoc.imageProvider.XMLSpy.version = %XMLSPY_VERSION% xsddoc.imageProvider.XMLSpy.classPath = %XMLSPY_CLASSPATH% xsddoc.imageProvider.XMLSpy.libPath = %XMLSPY_LIBPATH% xsddoc.imageProvider.OxygenXML.command = %OXYGENXML_COMMAND% xsddoc.imageProvider.OxygenXML.config = %OXYGENXML_CONFIG% xsddoc.macro.IMAGE_PROVIDER_CLASS = com.docflex.xml.xsd.DiagramKit

Line	Explanation
1	The XML Type full name
2	A short description of the XML Type
3	This setting is most important for the whole XML Type definition. It specifies one or several XML schema files that provide the datatype information about all data-source XML files possible to process by any template set based on that XML Type. In case ox XSDDoc, it is http://www.w3.org/2001/XMLSchema.xsd (i.e. “XML schema for XML Schemas”) and those possible data-source XML files are any XML schema (XSD) files themselves. See Also: Defining XML Type | Assigning XML Schemas | xsd.files
4	The URI of an XML catalog that redirects the locations of the XSD files (specified in line 3 as well as any other XML schemas referenced from them) to some other locations, which may be easier to access. The specified URI ('urn:docflex-com:xml:defaultcatalog') denotes the Default XML Catalog, which redirects the Internet locations of all necessary files to their local copies held in DocFlex/XML resources: {docflex-xml}/lib/resources
5	Indicates that all global types (i.e. xs:simpleType and xs:complexType) defined in the XML schemas (line 3) should be exposed as abstract element types. In particular, this allows you to program in templates the searching and iterating elements not only by their XML names (directly found in XML files), but also by the element types associated with the elements according to the XML schemas. See Also: Defining XML Type | Assigning XML Schemas | xsd.includeAbstractTypes
6-9	These lines specify all namespace prefixes used in XSDDoc templates. Templates, like the XML files/documents they process, need to deal with namespace URIs, which are typically long character strings. Therefore, some shortcuts are needed to reference to particular namespaces. See Also: Defining XML Type | Assigning XML Schemas | Declaring Namespaces
10	This setting says that, in addition to normal elements and attributes, all other nodes of an XML document (i.e. DOM) should be exposed as special elements (called pseudo-elements). This is needed to be able to program in templates the processing of entire XML file content, for instance, to fully reproduce it in the generated documentation together with the special formatting and hyperlinks. See Also: Defining XML Type | Pseudo-elements
11	Indicates that any processing should start from the #DOCUMENTS pseudo-element, which is created by the template interpreter to represent the list of all data-source XML files specified on the generator command-line for processing. That virtual element will be passed to any main template, as the template's root element, from which the processing of the template starts. That allows XSDDoc to process/document any number of XML schemas at once. See Also: Defining XML Type | Pseudo-elements | #DOCUMENTS
12	Specify the main Java class of the Element Image Provider. Here “elements” mean not XML schema element components, but rather elements of the XML document that describes the schema (that it the XSD file), and “images” are diagrams, which depict content models of XML schema components defined by some of those elements (such as <xs:element>, <xs:complexType> and <xs:group>). «Element Image Provider» is actually a more technical name for a diagramming plugin, whose job is to generate those diagrams. DocFlex/XML currently includes three different diagramming plugins: DocFlex/XML DiagramKit XMLSpy Integration OxygenXML Integration Since the diagramming plugin is interchangeable, its main Java class is specified not directly, but via 'IMAGE_PROVIDER_CLASS' macro. That allows selecting the particular diagramming plugin externally on the Java command line of both Generator and Template Designer. However, xsddoc.xmltype specifies also the default value for 'IMAGE_PROVIDER_CLASS' macro (see line 18), which is the main class of DiagramKit. See Also: DocFlex/XML | Features | Diagramming Plugins DocFlex/XML | Documentation | Defining XML Type | Element Image Provider DocFlex/XML | Integrations | XMLSpy | Setting Details | XMLSpy Integration Main Class DocFlex/XML | Integrations | Oxygen XML | Setting Details | OxygenXML Integration Main Class DocFlex/XML | XSDDoc | How to include diagrams?
13	XMLSpy Integration parameter: The version number of the XMLSpy being used. It cannot be obtained via XMLSpy API, yet it is needed in the XSDDoc templates for the integration support. The XMLSpy version number is passed via 'XMLSPY_VERSION' macro, which can be specified on the command line. See Also: DocFlex/XML | Integrations | XMLSpy | Setting Details | XMLSpy Version XSDDoc | Parameters | Diagramming | XMLSpy Integration | XMLSpy Version
14	XMLSpy Integration parameter: The Java classpath to XMLSpy Java API. It is passed via 'XMLSPY_CLASSPATH' macro, which can be specified on the command line. See Also: DocFlex/XML | Integrations | XMLSpy | Setting Details | XMLSpy API Java Class Path
15	XMLSpy Integration parameter: The pathname of the directory containing a non-Java implementation of XMLSpy API (this is a Windows DLL that provides a bridge between Java and XMLSpy's Windows native code). It is passed via 'XMLSPY_LIBPATH' macro, which can be specified on the command line. See Also: DocFlex/XML | Integrations | XMLSpy | Setting Details | XMLSpy API Library Path
16	OxygenXML Integration parameter: Specify the OS command to call OxygenXML's own XML schema doc-generator. It is passed via 'OXYGENXML_COMMAND' macro specified on the command line. See Also: DocFlex/XML | Integrations | Oxygen XML | Setting Details | OS command to run OxygenXML's own DocGen
17	OxygenXML Integration parameter: Specify an alternative pattern file for the settings file passed to OxygenXML's XML schema doc-generator. This may be needed in case when that settings file substantially changes in the future OxygenXML version, so that one used now by the integration (and stored in resources) will not be adequate for this.
18	Specify the default value for 'IMAGE_PROVIDER_CLASS' macro (see line 12), which is the main class of DiagramKit – the default diagramming plugin. See Also: DocFlex/XML | XSDDoc | How to include diagrams?

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). Note: The term “DSM Type” (Data Source Model Type) visible on the screenshot is a generalization of the notion of XML Type extended to the whole DocFlex Technology, which is able to process in similar way not only XML-files, but any other data-sources provided via some Java APIs. For example, see DocFlex/Javadoc.

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):

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 DocFlex/XML DiagramKit
      • XMLSpy.tpl – in case of XMLSpy Integration
      • OxygenXML.tpl – in case of OxygenXML Integration
      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 (e.g. XMLSpy) to generate all the diagrams immediately or keep the component information so as to generate each diagram on request (see DocFlex/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:

   http://www.filigris.com/docflex-xml/xsddoc/examples/html/XMLSchema/index.html?schemas/XMLSchema_xsd/elements/element.html

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

5. At last, as everything has been generated, the «Template Finish Expression» is processed:

   

   which invokes the execution of «Finish» stock-section (click on the screenshot to enlarge):

   

   Currently, all it does is removing the temporary files produced by some of the diagramming plugins:
   • XMLSpy – in case of XMLSpy Integration
   • OxygenXML – in case of OxygenXML Integration

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.

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):

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:

5.  Subtemplates

Subtemplates are normal DocFlex/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]