## Using GXML: Templates

by Josh Carter < josh@multipart-mixed.com >
May 10, 2001

## Template Basics

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.

## Nested Templates

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.

## Variable Rules With Templates

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.

## Variables Within Template Names

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.

## The Special _BODY_ Variable

You may have noticed I used a weird looking variable in that last example. There's a special variable for the text enclosed by an entity: `_BODY_`. In the example above, using `_BODY_` in the document template meant "give me all the content of the 'document' entity." Let's take a simpler example. Say we want the concept of a hyperlink with description, written in our document as follows:

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

On to Commands!

Back to the GXML Guide

Back to the gxml2html Guide

Copyright (c) 2001-2002 Josh Carter