Templates allow you to transform an entity in your source file into something else in your output. The most common use is to apply formatting; thus your input file in raw data and our output is nicely formatted data.
Templates are kept in a separate directory from your other files, and the name of the template file indicates the tag that it'll map to. Thus, if you want to template all "person" entities, you create a file called "person.xml" in your templates directory. The person.xml file will most likely take attributes from the person entity in your data file by using variables.
Let's demonstrate. Say we have a data file as follows, and a person.xml file I'll list afterward:
<data-file> <person> <name>Bob</name> <age>42</age> </person> <person> <name>Ned</name> <age>24</age> </person> </data-file>
person.xml in your template directory contains:
<person> <p>Person name is: %%%name%%%, age is %%%age%%%</p> </person>
The output of running GXML over the data file will be:
<data-file> <person> <p>Person name is: Bob, age is 42</p> </person> <person> <p>Person name is: Ned, age is 24</p> </person> </data-file>
(Give or take some white space in the final output.) If you have HTML translation turned on, the enclosing tags for the document and templates will be stripped, producing:
<p>Person name is: Bob, age is 42</p> <p>Person name is: Ned, age is 24</p>
And now we have something useful. However your data files are created, you can create formatting templates which will produce output that looks the way you want. If you decide to change the data, no problem, just run GXML over it again and the output will be updated. Ditto changing a template. This gives you a great deal of flexibility.
GXML fully supports nested templates. That is, a template can contain entities which will get mapped into other templates. It won't take long before your project(s) get complex to need this. For example, say you have a "document" template, and a "link" template that you use for hrefs to other pages/sites. Then you add a "photo" template, and you want the caption to link to something. Go ahead and use your "link" template within the "photo" one. It'll work like you expect.
The scoping rules for variables still apply with templates, and the concept of "enclosing" attributes can span multiple templates. In the example of nested document/photo/link templates, the "link" template could have variables whose value is up in the document. No problem; the variable matching engine works seamlessly across templates.
This gets a little twisted. Let's say you have three templates for the header of your document, one for if you have a lead photo on the left, another with a lead photo centered, and another with no lead photo. (This is what I do on multipart/mixed, actually.) You can select which header template you want to use by using a variable as all or part of your template name. Here's an example, assuming you have header templates named "header-right" and "header-none":
# document source file: <document name = "Semi-annual Worm Preservation Report" author = "Bob the Man" photo-align = "right" photo-source = "worms.jpg" > (document body text here) </document> # document.xml template file: <document name-default = "Untitled Document" author-default = "Unknown Author" photo-align-default = "none" > <header-%%%photo-align%%%/> %%%_BODY_%%% </document>
Now the header template will be selected based on the "photo-align" attribute of your document, defaulting to "header-none." There are other ways to do this; you'll see that in the next section on GXML commands. Also note that defining default attribute values in your templates can be very useful.
<linkitem name="Bob's Worm Land" href="http://worms.bob/"> This site tells you everything you'd ever want to know about worms. </linkitem>
Your linkitem.xml template could look like this:
<linkitem> <p><b><a href="%%%href%%%">%%%name%%%</a>:</b> %%%_BODY_%%%</p> </linkitem>