DocFlex/XML - Documentation - Designing Templates

1. How to Create a Template?
2. Defining XML Type
   • XML Type Configuration File
   • Assigning DTD
     • dtd.file
     • dtd.systemID
     • dtd.publicID
   • Assigning XML Schemas
     • xsd.files
     • xsd.includeAbstractTypes
     • Local Element Types
   • Declaring Namespaces
     • ns.<n>.uri
     • ns.<n>.prefix
     • ns.<n>.default
     • Example
   • Pseudo-elements
     • pseudo-elements.all
     • pseudo-elements.<NAME>
     • defaultRootElement
     • #CDATA
     • #COMMENT
     • #DOCTYPE
     • #DOCUMENT
     • #DOCUMENTS
     • #NAMESPACE
     • #PI
     • #STUB
     • #TEXT
   • Using Macros
3. Running Template Designer
   • Command Line Options
   • Creating a New Template
   • Invoking Generator from Template Designer

1.  How to Create a Template?

Here are your steps:

1. You should start from creating an XML schema that describes your XML files (that is, with which all your XML files must conform).

   (Instead of the XML schema, you may also create a DTD file, which will serve the same role. However, XML schema is a better and more modern alternative with a lot more capabilities.)

   Why is XML schema needed?

   Because it will provide DocFlex/XML with the data structure and type information about your XML files. Without it, you will not be able to program much of the processing in your templates. Everything will be limited only to the case of Generic XML Files used in XMLDoc templates. If your processing is supposed to be something more than that, an XML schema is the must!

2. Once your XML schema is ready, you should define an XML Type.

   In short, XML Type is a group of records in an XML Type configuration file, which provide DocFlex/XML with all information necessary for processing a specific set of XML files. In particular, this will include the location of your XML schema (XSD) file and some other settings.

   For further details about how to specify your XML Type, please see Defining XML Type (below).

3. Having prepared the XML Type, you can start the Template Designer and create a new template (or a set of templates) basing on that XML Type. In that template, you should program/design all the processing you need.
4. After finishing the template, you can run the generator and process your XML files using your template.

For a detailed example of creating a sample template from scratch, please see DocFlex/XML | Tutorials.

2.  Defining XML Type

Each XML Type is associated with a certain class of XML documents with the same data structure. Such a class is normally based on a certain DTD or W3C XML Schema file (see Assigning DTD and Assigning XML Schemas respectively). However, some additional settings may be added.

The information provided by the XML Type is used both by the Template Designer during designing your templates and by the generator during processing those templates and generating output documents.

In a more general terminology of the DocFlex Technology, each XML Type is actually a special kind of DSM Type (Data Source Model Type), which is limited to a certain class of XML file data sources.

XML Type Configuration File

The XML Type is identified by a short name called XML Type identifier, which we shall refer as <typeId>. (The identifier must contain only letters, digits and '_' sign. No other characters should be used!)

Once the XML Type identifier name is chosen, it must be used everywhere as a prefix of each property related to the definition of this XML Type.

Besides the identifier, the XML Type must have a certain display name, which is specified using '<typeId>.name' property. That display name will be shown in the Template Designer.

You may also add a short description to your XML Type using '<typeId>.doc' property.

For example, let our XML Type has an identifier 'my_xml'. Then, the whole XML Type definition may look like the following:

my_xml.name = My XML Files
my_xml.doc = Describes the XML files I use in my project
my_xml.xsd.files = C:/myproject/xml/myxml.xsd
my_xml.ns.1.prefix = myxml
my_xml.ns.1.uri = http://www.company.com/MyProject/

It is also possible to specify neither DTD nor XSD files. However, in that case, you will be limited to a very general case of XML files with few capabilities to process them (see XMLDoc).

A single XML Type Configuration File may contain definitions of any number of different XML Types. Alternatively, you can place a particular XML Type definition in a separate XML Type Configuration File and store it near the templates based on that type.

How does DocFlex/XML use XML Types?

To open any particular template in the Template Designer or to process it with the generator (in order to generate some output), DocFlex/XML needs the XML Type on which that template is based. It searches for the necessary XML Type (by the XML Type Identifier found in the template) among those XML Types that have been loaded from all known XML Type Configuration Files.

DocFlex/XML supports a number of ways to specify locations of XML Type Configuration Files:

• You may specify the locations of all XML Type Configuration Files at once statically within the DocFlex main configuration file. In that case, any such files will be load automatically both by the Template Designer and the generator.
• Additionally, the XML Type Configuration Files can be specified directly on the command line of both Template Designer and generator using the -xmltype option.
• You can place an XML Type Configuration File in the same directory where the templates based on it are located. In that case, the XML Type Identifier must be used as the name of that file and ".xmltype" as the extension (e.g. 'my_xml.xmltype').

  When the Template Designer or generator open a template from this directory and the necessary XML Type is unknown, it will be loaded from that configuration file.

• In the case when the XML Type configuration file will be stored together with the templates and loaded completely dynamically, to bootstrap the whole process of designing new templates, you can preload that config file in the Template Designer directly in the “New Template” dialog.

Assigning DTD

• dtd.file
• dtd.systemID
• dtd.publicID

<typeId>.dtd.file=<DTD file>

Specifies the DTD file which contains the data type information that describes your XML files.

Any XML documents which you want to associate with this XML Type (and process with the templates based on it) should be based on this DTD!

Example:

my_xml.dtd.file=C:/xml/myxml.dtd

<typeId>.dtd.systemID=<URI>

This optional property may be used to bind your XML files to the DTD specified with the dtd.file setting so as when the XML files are parsed, this DTD file will be used by the parser.

Example:

Let's suppose your XML files contain the following <!DOCTYPE> instruction:

<!DOCTYPE SYSTEM "http://www.myorg.org/dtd/myxml.dtd">

Then, to bind your XML files to the local DTD, you may use the following settings:

my_xml.dtd.file=C:/xml/myxml.dtd
my_xml.dtd.systemID=http://www.myorg.org/dtd/myxml.dtd

<typeId>.dtd.publicID=<name>

This optional property may be used to bind your XML files to the DTD specified with the dtd.file setting so as when the XML files are parsed, this DTD file will be used by the parser.

Example:

Let's suppose your XML files contain the following <!DOCTYPE> instruction:

<!DOCTYPE PUBLIC "-//MYORG//DTD My special XML 1.x//EN">

Then, to bind your XML files to the local DTD, you may use the following settings:

my_xml.dtd.file=C:/xml/myxml.dtd
my_xml.dtd.publicID=-//MYORG//DTD My special XML 1.x//EN

Assigning XML Schemas

• xsd.files
• xsd.includeAbstractTypes

<typeId>.xsd.files=<XSD file1>;<XSD file2>;...

Specifies one or several XSD (XML Schema) files which contain the data type information describing your XML Type.

Notes:

• Any XML documents which you want to associate with this XML Type (and process with the templates designed for it) should be consistent with the specified XML Schemas!
• If you specify several schema files, all of them will be loaded, so you will see the element types from all of them in the Template Designer.

Example:

my_xml.xsd.files=C:/xml/myschema.xsd
my_xml.xsd.files=C:/xml/myschema1.xsd;C:/xml/myschema2.xsd

<typeId>.xsd.includeAbstractTypes=<true | false>

To understand this setting, you need to know a little bit about what is described in XML Schemas (see also XSDDoc | FAQ | Where can I learn more about XML schemas?).

XML Schemas contain definitions basically about two major things: elements (e.g. <xs:element>) and types (e.g. <xs:complexType> or <xs:simpleType>).

Each element definition describes a class of the XML elements identified by a certain name (which is the one used as the element tag in XML documents).

Unlike the pure elements, element type definitions generally are not bound to specific XML elements with the specific names. Instead, they serve as abstract the definitions of element data structures, which can extend one another, and eventually should be used as bases in particular definitions of elements.

From the DocFlex/XML's point of view, both notions are considered as Element Types because they describes certain classes of elements rather than particular element instances, which are things contained in XML documents and carrying the data to be processed.

XML Schemas allow two kinds of element type definitions: local and global ones.

Local type definitions are nested within the definitions of elements. DocFlex/XML considers them simply as parts of the corresponding element definitions.

Global type definitions always have individual names. Each global type definition may be used as a base for different element definitions simultaneously. Effectively, it represents a certain abstract Element Type which can be specifically recognized by DocFlex so as by that Element Type a specific processing in templates may be organized (e.g. filtering or iterations).

When 'xsd.includeAbstractTypes' property is specified as true, all global types declared in the XML Schema will be treated as separate Element Types and appear in various dialogs and treeviews in Template Designer. The names of such Element Types are produced from the original names started from '%' (to ensure they are different from any global element names).

When this property is specified as false (which is assumed by default), all global types will be treated the same way as the local ones. That is, anything declared with them will be considered as parts of element definitions to which those types are applied.

Here is how the Element Types treeview looks with the inclusion of global types (left picture) and without them (right picture):

 

The Element Types produced from XML Schema's global type definitions are considered as abstract Element Types (shown with '%'). That means, neither of them, as it is, can be assumed by any XML element. Anyway, you may find this notion useful to program specific processing for the whole set of different physical Element Types derived from the same global type definition in the schema.

Local Element Types

1. any other elements (both global and local ones)
2. global complex types
3. global model groups

In an XML document, the names of the locally defined elements are guaranteed to be unique only within the scope of their parent elements. That means, in the same XML document, there may be several absolutely different local XML elements (possibly having even different structures) sharing the same name. That situation presents a problem with referencing such elements.

DocFlex/XML resolves this problem by introducing Local Element Types.

For every local element definition in the XML schema, there is a certain logical Local Element Type representing it in the XML Type. In various treeviews in the Template Designer, the Local Element Types are shown as child nodes of their parent Element Types (see the right picture above).

The logical Element Types representing the XML schema's global element definitions as well as the definitions of global types (see xsd.includeAbstractTypes option) are called Global Element Types.

Since the names of Local Element Types are not guaranteed to be unique anymore, to distinguish all logical Element Types from one another, DocFlex/XML generates for each Element Type a special global name, which is unique for the whole XML Type. Further, the Element Type is referred by that global name in every situation that may be ambiguous.

The global name of a Global Element Type is always the same as its normal (local) name.

For a Local Element Type, its global name is generated according to the following rules:

1. If the corresponding local <xs:element> definition is based entirely on a certain global complexType/simpleType and looks like:

   <xs:element name="name" type="typeName"/>

   the Element Type's global name will be produced as the following:

   name%typeName

2. If the local <xs:element> contains a definition of an embedded type, which may look like this:

   <xs:element name="name">
   <xs:complexType> ... </xs:complexType>
</xs:element>

   the global name of the corresponding Element Type will be generated according to where that entire definition is located:
   1. When it is nested within a certain global <xs:complexType> with the name 'typeName', the Element Type's global name will be this:

      %typeName$name

   2. When it is nested within a certain global <xs:group> with the name 'groupName', the Element Type's global name will be this:

      !groupName$name

   3. At last, when the local <xs:element> definition is nested within another <xs:element> definition whose corresponding Element Type has the global name 'parentGlobalName', then the global name of the given local Element Type will be produced as:

      parentGlobalName$name

      That is, it will be represented as the full paths formed from names of nested schema components separated with '$' starting from a certain global component until the given local <xs:element> definition. For example:

      SalesExport$Purchase$CustomerData$RegName

See also XSDDoc | Documenting Local Elements, which is related to this topic.

Declaring Namespaces

1. Namespace URI
2. Prefix
3. Local Name

Instead of URIs, in XML documents, the namespace prefixes are used. Now, an XML name should be written in the following form:

Prefix:LocalName

Each Prefix is simply a shortcut to a particular namespace URI. Namespace prefixes are specified in XML documents locally and may vary from one XML to another. For instance, one XML document may contain <xsd:complexType> element tags, whereas other document will call the same things as <xs:complexType>.

Because namespaces were introduced above the initial XML 1.0 standard, all possible XML documents now are subdivided into namespace-aware and namespace-unaware ones.

When an XML document is namespace-unaware, nothing prevents it to use the XML names looking as prefix:name. However, in that case, the whole such a name will be considered as a local one (no binding to a namespace URI occurs). DTDs are namespace-unaware by default (however, they may still define XML names with prefixes which can be treated as references to actual namespaces in the XML documents).

DocFlex/XML handles namespaces in the following way.

By default, any XML Type is namespace-unaware. That means, any XML files will be parsed in namespace-unaware mode and any XML names will be treated exactly as they are written.

To make an XML Type namespace-aware, you should declare certain namespaces associated with it. Each namespace should be declared with the following settings:

• ns.<n>.uri
• ns.<n>.prefix
• ns.<n>.default

<typeId>.ns.<n>.uri=<URI>

Specifies the namespace URI.

<typeId>.ns.<n>.prefix=<prefix1>;<prefix2>;...

Specifies one or more prefixes associated with this namespace.

Like XML documents, DocFlex/XML also needs some shortcuts to refer to particular namespaces. The first prefix specified with this setting (prefix1) will be used as the one. That prefix will appear in the Template Designer and will be stored in DocFlex templates (as part of qualified names).

Each namespace's URI, on the contrary, is specified only once in the XML Types config file and never stored anywhere else. The binding between prefixes and URIs occurs dynamically.

That system makes your templates absolutely independent on anything. You may use different namespace prefixes in your XML Schema files (or DTD) assigned to this XML Type. And you may quickly change any namespace URI itself without changing any templates.

Other prefixes specified with this property are used only together with DTDs (see Assigning DTD).

Actually, nothing prevents you from using namespace prefixes in your DTD (so that XML names will look as qualified ones). But since DTDs are namespace-unaware, XML parser will not recognize those prefixes and bind them automatically to the particular URIs. However, DocFlex/XML can do this for you. The only what you need is to specify with the ns.<n>.prefix property all possible prefixes used in your DTD which you want to bind to the specified URI.

<typeId>.ns.<n>.default=<true | false>

If true, indicates that this is the default namespace for the given XML Type.

When a namespace is declared as default, any XML names associated with it will be used in templates (and shown in the Template Designer) without namespace prefixes. You may use this setting to quickly transform your namespace-unaware templates into namespace-aware ones. Just specify in your XML Type the default namespace, and your templates will be ready to process the namespace-aware XML files.

By default, this setting is false.

Let's suppose your XML files will be starting from something like this:

<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/elements/1.1/"
  xmlns="http://purl.org/rss/1.0/"
>
...

rss.name = My RSS
rss.xsd.files = C:/xsd/rss-1_0.xsd;C:/xsd/rdf.xsd;C:/xsd/dc.xsd
rss.ns.1.uri = http://purl.org/rss/1.0/
rss.ns.1.default = true
rss.ns.2.uri = http://www.w3.org/1999/02/22-rdf-syntax-ns\#
rss.ns.2.prefix = rdf
rss.ns.3.uri = http://purl.org/dc/elements/1.1/
rss.ns.3.prefix = dc

Pseudo-elements

The DOM is basically a tree whose nodes represent everything contained in the source XML file. Most of those nodes are just dedicated to XML elements and their attributes. However, some of DOM nodes represent other things contained in the XML document, such as Text, Comments, Processing Instructions and so on.

The DOM tree starts from a special root node called Document node. This node represents the whole XML document. The Document node, among other things, always contains the Document Element node which represents the root element of the XML document.

DocFlex/XML provides access to almost all types of DOM nodes. It does this by representing the original XML DOM in a bit extended form called XML DSM (Data Source Model). Each XML DSM is linked to the original DOM provided by the XML parser. It maps all XML element into DSM elements and all XML attributes into DSM attributes.

Besides this, the XML DSM maps all other (non-element/attribute) DOM nodes into DSM elements of special Pseudo-Element Types. We shall call those extra elements simply pseudo-elements.

All pseudo-elements have their names started with '#'.

Each Pseudo-Element Type is linked to a certain type of non-element/attribute DOM nodes. Depending on that type, a pseudo-element may contain specific DSM attributes representing the original node's properties. Some pseudo-elements may also have children (which can be both pseudo-elements and normal ones) and be children themselves of normal XML elements.

DocFlex/XML treats pseudo-elements in the same way as the normal XML elements. You can organize iterations by pseudo-elements, access their attributes, reference to them within Location Paths and do anything else. As an example of an application where pseudo-elements are heavily used, see XMLDoc.

Currently, DocFlex/XML supports the following types of pseudo-elements:

• #CDATA
• #COMMENT
• #DOCTYPE
• #DOCUMENT
• #DOCUMENTS
• #NAMESPACE
• #PI
• #STUB
• #TEXT

<typeId>.pseudo-elements.all=<true | false>

If true, enables all Pseudo-Element Types at once.

<typeId>.pseudo-elements.<NAME>=<true | false>

Enables/disables an individual Pseudo-Element Type with the name #NAME. This setting overrides the pseudo-elements.all property.

<typeId>.defaultRootElement=<DocumentElement | Document | Documents>

Specifies from which element the generator starts processing an XML document (that is, which element will be used as the root element for a template processing the whole XML document):

DocumentElement

This is the default setting. The Document Element becomes the template's root element.

Document

The template's root element is the #DOCUMENT pseudo-element. Use this settings when you need to process all nodes of a single XML document.

Documents

This setting allows processing multiple XML files in a single pass so as to generate a single documentation from all of them.

In that case, the main template will receive will be the #DOCUMENTS pseudo-element as its root element. This pseudo-element represents the list of all XML files specified to process by the generator (i.e. in the “XML File(s)” field of the generator dialog or on the command line).

For more information about processing multiple XML files, see description for #DOCUMENTS pseudo-element and XMLDoc | Templates as an example of using it.

Example:

The following settings enable all pseudo-elements except the #CDATA ones and tell the generator to start the processing of an XML document from the #DOCUMENT pseudo-element:

my_xml.pseudo-elements.all=true
my_xml.pseudo-elements.CDATA=false
my_xml.defaultRootElement=Document

This table provides details about all Pseudo-Element Types:

Pseudo-Element	Description
#CDATA	Represents CDATA sections of the XML document. CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup. By default, CDATA sections are parsed into the normal TEXT nodes. However, when #CDATA pseudo-elements are enabled, the CDATA sections will be recognized separately and produce #CDATA pseudo-elements. This feature may rarely be used, mostly when you need to reproduce the original content of an XML file (see XMLDoc | Templates as example). Value: Content of the CDATA section. Note: When an XML element (i.e. its data type) has a declared value, that value is produced from the content of all element's child TEXT and CDATA nodes merged together. This, however, does not affect the appearance of those TEXT and CDATA nodes as the element's children of #TEXT and #CDATA types. Example: The following CDATA section in an XML file: <![CDATA[ write '<' instead of '&lt;' here ]]> will produce a #CDATA pseudo-element with the value: "write '<' instead of '&lt;' here"
#COMMENT	Represents a COMMENT node. If enabled, #COMMENT pseudo-elements may appear as children of any normal XML elements as well as within the pseudo-element #DOCUMENT. Value: Content of the comment. Example: The following comments in an XML file: <!-- my comments --> will produce a #COMMENT pseudo-element with the value "my comments".
#DOCTYPE	This pseudo-element represents the <!DOCTYPE> instruction of the XML file. If enabled, it may appear only as a child of the #DOCUMENT pseudo-element. Attributes:  internalSubset  -  The internal subset as a string.  name  -  The name of the DTD; i.e., the name immediately following the DOCTYPE keyword.  publicId  -  The public identifier of the external subset.  systemId  -  The system identifier of the external subset.
#DOCUMENT	This pseudo-element is linked to the DOM Document node and represents the whole XML document (therefore, only one instance of it may exist). If you need to process all possible nodes in the XML document, you should start from this pseudo-element. See <typeId>.defaultRootElement setting for more details. Attributes:  xmlName  -  The name of the XML file (e.g. 'sales.xml').  xmlURI  -  The URI where the XML file is located (this may be a URL or an absolute pathname on the local system).  xmlDecl  -  The text of the XML declaration from which the XML document starts (e.g. '<?xml version="1.0" encoding="UTF-8"?>').  namespaces  -  This attribute provides all namespace bindings declared in the given XML document. The attribute value is an array containing the unique identifier of #NAMESPACE pseudo-elements representing all namespace bindings. Children:  Document Element,  #DOCTYPE,  #COMMENTs,  #PIs
#DOCUMENTS	This pseudo-element represents the list of all open XML documents. When <typeId>.defaultRootElement property of XML Type config is set to 'Documents', all XML files specified to process by the generator are passed to the main template as children of #DOCUMENTS pseudo-element, which the template receives as its root element. Every XML file will be open, parsed and represented as #DOCUMENT child element. Further, within the template's root block, you can organize iteration by such children and process every XML document as you need. Function loadXMLDocument(), which opens an XML document dynamically from within a template by a specified URI, alters the list of open XML documents and adds a new document to the list of the #DOCUMENTS element's children. All open XML documents together constitute a single DSM (Data Source Model). This allows processing everything as a single "meta" XML document. In particular, you can iterate and access elements and attribute contained in different XML documents simultaneously within the same iterators and other template components. The identifier of each XML element will be unique for the whole DSM (see GOMElement.id). See XMLDoc | Templates as an example of this kind of processing. Children:  #DOCUMENT
#NAMESPACE	Represents a namespace binding specified in an XML element. If this pseudo-element type is enabled, each namespace binding specified in an element with one of xmlns        = "..." xmlns:prefix = "..." declarations will produce a #NAMESPACE pseudo-element describing this binding. That element will be added to the children of the given XML element. If an XML element contains several namespace binding declarations, there will be as many #NAMESPACE pseudo-elements added to the element's real children. All namespace bindings declared in an XML document can be obtained via namespaces attribute of #DOCUMENT pseudo-element. As an example of using #NAMESPACE pseudo-elements, see XMLDoc | Templates | xmlns-bindings.tpl template. Attributes:  elementId  -  The unique identifier of the XML element where this namespace binding is declared.  namespaceURI  -  The namespace URI of the binding.  prefix  -  The namespace prefix to which the namespace is bound. If the namespace binding was declared as xmlns="...", the value of this attribute is an empty string.
#PI	Represents a Processing Instruction. If enabled, #PI pseudo-elements may appear as children of any normal XML elements as well as within the pseudo-element #DOCUMENT. Value: The content of this Processing Instruction. Attribute:  target - The target of this processing instruction. Example: The following Processing Instruction in an XML file: <?php include("header.php");?> will produce a #PI pseudo-element which, if it was a normal XML element, would be written as the following: <#PI target="php">include("header.php");</#PI>
#STUB	Represents a custom pseudo-element. Here is how it can be used. Let's suppose you have some XML elements connected in a chain. Each next element is produced from the previous one by certain reference information contained in it. You may want to print something about each element, possibly using some complex formatting, in the order the elements appear in the chain. To do this, you may construct an Element Iterator, specify iterating by elements from that chain, and specify some processing within the iterator's body to display information about each particular element. Now, you may discover, that the last element in the chain may also have some reference looking quite the same, but by that reference no element in the open XML documents can be found. Such a situation may be quite legitimate, because something related to the referenced non-existing element may well exist within something the whole your documentation describes (e.g. some predefined element known to always exist within some libraries). Because of this, you may want to display some information about that "external" element quite the same way as about the existing ones. Everything you need may be already present in the reference (e.g. the element's name). How can you do that? DocFlex is able to iterate only by elements! You would obviously need to program processing of that special situation outside the iterator's body and repeat almost everything you did for a normal element. Actually, you don't need to do so! You may process that special situation inside the same iterator's body. To do that, for such an external element, within the iterator's settings producing the element chain, you should create a #STUB pseudo-element, that will represent the referenced real one, using StubXMLElement() function. Then, using setXMLAttribute() function, you can fill that stub pseudo-element with certain attributes, which may convey the information about the real element you found in the reference. Then, that stub element should be passed to the iterator as a normal one and can be further processed within the iterator's body. If you need to program a certain modification of the general processing related to such a special situation, you may always distinguish the stub pseudo-element just by its #STUB type. See Also: StubXMLElement(), setXMLAttribute()
#TEXT	Represents a TEXT node. If enabled, #TEXT pseudo-elements may appear as one or multiple children of any normal XML element. Value: The text contained in the node. Notes: When an XML element (i.e. its data type) has a declared value, that value is produced from the content of all element's child TEXT and CDATA nodes merged together. This, however, does not affect the appearance of those TEXT and CDATA nodes as the element's children of #TEXT and #CDATA types. When the parent XML element has mixed model (that is, it contains both text and other XML elements), several #TEXT pseudo-elements will appear as its children. Example: The following piece of an XML: <par>text one<nl/>text two</par> will produce a single 'par' element with the three children: #TEXT('text one'); nl; #TEXT('text two')

Using Macros

For example, in Samples | Sales Report, you can see the following definition of the XML Type used there:

sales.name = Sales
sales.xsd.files = %DFH%/samples/sales/sales.xsd

sales.xsd.files = C:/docflex-xml/samples/sales/sales.xsd

There are two predefined macros that you can use in your XML Type Configuration File:

Macro	Description
DFH	The pathname of the DocFlex/XML home directory. The initial value of this macro is the absolute pathname of the directory containing the DocFlex/XML Java library 'docflex-xml.jar' (the exact name depends on the edition). However, a different directory pathname can be assigned in docflex.config file. (Actually, this is done in the default docflex.config provided with the most editions, so as to make the 'DocFlex/XML home directory' to be the one that is the parent of the 'lib' directory containing 'docflex-xml.jar'.) Such an arrangement is intended to allow easy distribution of the specific files needed for running DocFlex/XML so as their locations would better fit for your entire project.
THIS_DIR	This macro is expanded into the absolute pathname of the directory containing the given file (where the macro is used). The macro value is calculated dynamically and may not be redefined. You may use this macro, for instance, in your XML Type Configuration File to specify an XML schema file located in the same directory. For example: my_xml.name = My XML Files my_xml.xsd.files = %THIS_DIR%/myxml.xsd

You may also use your own macros, which you can define in two places:

1. In the main configuration file of DocFlex/XML (docflex.config).
2. Using -M option on the generator command line.

When a macro name is unknown, the macro call is remained as is (e.g. '%blah-blah%' will be expanded into '%blah-blah%').

2.  Running Template Designer

Here is the exact command line to launch the Template Designer:

java <class_path> <designer_class> [options] [template files]

where

• java is the Java Interpreter located at 'bin' directory of JDK/JRE installed on your system.
• <class_path> is the DocFlex/XML class path which should be the following:
  

  -cp lib\xml-apis.jar;lib\xercesImpl.jar;lib\docflex-xml.jar

• <designer_class> is com.docflex.xml.Designer
• [options] are the Template Designer command line options
• [template files] are the pathnames of template files to open; if you specify several template files, all of them will be open in separate designer windows.

By default, Template Designer starts according to the settings contained in designer.config file. The last edited template will be open automatically.

Command Line Options

-docflexconfig <file>

Specifies an alternative path to the DocFlex/XML main configuration file (docflex.config).

-xmltype <files>  or  -xmlconfig <files>

Specifies the locations of one or many XML Type Configuration Files.

The option value may include multiple file pathnames, which should be separated with the OS-specific path-separator character (e.g. ';' under MS Windows or ':' under Linux). Alternatively, you can specify different config files with any number of -xmltype options on the command line.

All XML Type Configuration Files specified with the -xmltype options are loaded in addition to those assigned statically in the docflex.config. However, when an XML Type happens to be defined simultaneously in several files, the definition contained in a file directly specified on the command line will be used the first.

-config <file>

Specifies an alternative designer configuration file (designer.config) which is used instead of the one specified in the docflex.config.

-updatetemplates <dir>

Updates all DocFlex templates contained in the specified directory. You may use this option to upgrade your old (existing) templates according to a new DocFlex/XML version, new edition or new license you are using now. When this option specified, the designer works only in command mode and no GUI is started.

-r

Recurse subdirectories. This option works only in conjunction with -updatetemplates option.

Creating a New Template

Run designer.bat and select in the main menu “File | New Template” item. You will see the following dialog:

You should select the XML Type on which your template will be based. (If the list does not include the necessary XML Type, you can load its definition from the corresponding XML Type Configuration File by clicking the “Add” button.)

Each template is always linked to a certain XML Type. That means, the template is programmed to process only those XML files which comply with that XML Type. The XML Type's identifier is stored in the template. So, each time the template is loaded in the Template Designer or processed by the generator, the corresponding XML Type is dynamically bound to the template so as to provide the data type information necessary for the template processing.

To provide all the information required for the designing or processing of the template, the XML Type needs to be initialized first. This happens when the XML Type is accessed for the first time. Any DTD or XSD files assigned to it are loaded and parsed. If during this an error occurs, the template will not be loaded! Another problem may happen when since the last modification of the template, the data type information specified in the XML Type, on which the template is based, was changed. In that case, the template will still be loaded in the Template Designer, however some settings specified in it may become incorrect. Such settings need to be fixed. Otherwise, the template may cause errors during processing by the generator.

In the “Template Type” panel, you should select which type of the template is to be created. The template type determines how the template is processed and what is generated by it (as well as some additional features related to this). Currently, there are three template types:

1. Document Template generates a single document file (in any of the supported formats) or a part of the document file.
2. Frameset Template generates a multi-file framed HTML documentation. This template normally calls from itself many other document templates (subtemplates), which generate particular HTML files to be loaded in the frames. This template also contains the definition of the HTML frameset, by which the index.html is generated.
3. Procedure Template does not generate any output. Instead, such templates are called normally only once from the main templates to create specific global data structures (e.g. element maps) to be used further throughout the whole template set. In a procedure template, the data query capabilities of the template components (such as Element Iterator) are are employed to collect the specific information and represent it internally in a way convenient for a faster access later.

After selecting the template type, click “OK” button and an empty template will be created:

What exactly you should do the next is a topic vast enough to be discussed here. We refer you to the general DocFlex Technology Documentation.

Also, it is very much useful to investigate the Flash tutorials created specifically for DocFlex/XML to show in every detail the whole process of designing a sample template.

Invoking Generator from Template Designer

To invoke the generator, just select the “Tools | Generator” item in the Template Designer main menu. You will see the Generator Dialog as shown on the following screenshot:

Note:  Another possibility that may greatly help you when debugging your templates is the echo() function, which you can use in FlexQuery-expressions within your templates. This function effectively does nothing, but it prints everything passed through it to the Java console window (i.e. Java System.out stream). This may help you to track how particular template components and settings are interpreted by the generator.