 DocFlex/XML - Documentation - Designing Templates
- How to Create a Template?
- Defining XML Type
- Running Template Designer
1. How to Create a Template?
Your task is the following.
You have some XML files and now you want to produce from them some report or documentation
using DocFlex/XML. What should you do?
Here are your steps:
-
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!
-
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).
-
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.
-
After finishing the template, you can run the
generator
and process your XML files using your template.
Actually, the last two steps are a repetitive process. To help to accelerate it,
DocFlex/XML allows invoking the generator
directly from Template Designer.
So, after making any changes in your templates, you can immediately see what a result they produce.
For a detailed example of creating a sample template from scratch,
please see DocFlex/XML | Tutorials.
2. Defining XML Type
To make DocFlex/XML able to process
a certain type of XML file with a specific structure, you should define an 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 the 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
Each XML Type is defined in a special XML Type Configuration File
in the form of a number of properties.
(In fact, the file itself is an ordinary Java properties file processed with
java.util.Properties
class.)
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/
An XML Type normally should be based on some
DTD or
XSD (W3C XML Schema) files,
which is where the actual XML data structure and type information is obtained by
DocFlex/XML.
(When both DTD and XSD are specified, the XSD will have a higher priority.)
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:
Assigning DTD
An XML DTD (Document Type Definition),
which you want to use as a base for your XML Type,
should be specified with the following settings:
-
<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
Alternatively to a DTD, you may base your XML Type on a single or multiple
W3C XML Schemas
(which, in fact, would provide a lot more capabilities).
The following settings in your XML Type Configuration File
should be used in that case:
-
<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 the abstract 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
Unlike DTDs, where all defined XML elements have global scope,
XML Schemas allow defining XML elements locally within the definitions of
- any other elements (both global and local ones)
- global complex types
- 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:
-
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
-
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:
-
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
-
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
-
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
DocFlex/XML uses global (or full) names of Element Types to reference to them internally
(you can also see them in the template files).
However, you may rarely need to use such a representation.
When the context is known, local names will normally suffice.
See also
XSDDoc | Documenting Local Elements,
which is related to this topic.
Declaring Namespaces
When namespaces are used, they transform each XML name (of an XML element or attribute)
into three things:
- Namespace URI
- Prefix
- Local Name
It is the {NamespaceURI;LocalName} pare which now constitutes the real name.
But because URIs tend to be long strings (and normally contain characters prohibited in XML names),
they cannot be used in XML documents directly.
Instead of URIs, in XML documents, the namespace prefixes are used. Now, an XML name should be written in the
following form:
Prefix:LocalName
That form is called Qualified Name.
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:
Where <n> is a number identifying the namespace declaration
(which is actually used to connect the declaration's properties together).
-
<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 Type 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.
Example:
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/"
>
...
Then, to process such files with DocFlex/XML you may define the following XML Type:
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
Basing on this XML Type, your templates will be using exactly the same XML names
as contained in your XML files.
Pseudo-elements
When the DocFlex/XML XML parser
which parses it into the DOM
(Document Object Model).
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:
Since some pseudo-elements are useful only in rather special situations, by default,
not all pseudo-elements are included automatically in every XML Type.
The following XML Types config properties control pseudo-elements:
-
<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 '<' here
]]>
will produce a #CDATA pseudo-element with the value:
"write '<' instead of '<' 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.
An 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
To avoid specifying the exact pathnames in your
XML Type Configuration File,
you may use 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
Here, the 'DFH' is a predefined macro whose value is the pathname of the DocFlex/XML home directory.
So, if that value is equal to 'C:/docflex-xml',
the last setting above will be expanded into:
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-xxx.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-xxx.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:
- In the main configuration file
of DocFlex/XML (docflex.config).
-
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
To start the Template Designer, just run designer.bat found
in the DocFlex/XML root directory.
Here is the exact command line to launch the Template Designer:
java <class_path> <designer_class> [options] [template files]
where
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
The Template Designer supports a few command line options, which are all described here:
- -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
Once you have finished with defining the XML Type
(which will provide the datatype information about your XML files)
you can start designing your template.
Run designer.bat and select in the main menu
“File | New Template” item. You will see the following dialog:
The “Select DSM Types” list shows all XML Types
currently known to the Template Designer.
(The XML Types are presented by their display names specified in
the <typeId>.name property.)
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:
-
Document Template
generates a single document file (in any of the supported formats) or a part of the document file.
-
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.
-
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 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:
Now, you can start filling it with the
template components
and to program/design all the processing you need.
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 of a sample template.
Invoking Generator from Template Designer
To accelerate the processes of developing your template application,
DocFlex/XML allows launching
the template interpreter (the generator)
directly from the 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:
Click the “Run” button to start the generation.
You can immediately see the result produced by your template(s) being designed.
(DocFlex templates do not need
any compilation or preprocessing to execute them!)
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.
|
