## Using GXML: Object API

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

## Basics

First, install GXML. See the README document in your distribution.

Here's a simple, but typical, example of using GXML:

        use GXML;

        # Create new object
        my $gxml = new XML::GXML();

        # Process a file, return a scalar containing new stuff
        print $gxml->ProcessFile('my-xml-file.xml');

You can pass parameters to the GXML new() method using a hash. The parameters it takes are:

- templateDir: directory to find templates in. Defaults to "./templates".
- remappings: hash reference containing tag remappings. See the "other features" page for more info on using remappings.
- addlTemplate: subroutine ref to code you provide which will serve extra templates. (This is an esoteric feature which most people won't use.)
- addlTemplateExists: subroutine ref to code you provide which tells GXML if you will serve a given template.
- callbacks: hash ref to callbacks table. See "other features."
- html: converts output into HTML syntax instead of XML syntax. Set to "on" to enable. See "other features."
- dashConvert: converts double-dash in source to emdashes. Set to "on" to enable.

Here's an example of creating a GXML object with some parameters:

    use GXML;

    my $gxml = new XML::GXML({'templateDir' => '/my/path/to/templates/',
                              'html'         => 'on',
                              'dashConvert'  => 'on'});

## Processing stuff

You can feed XML data to GXML using a scalar or a file. It can return the processed stuff in either way, too. Here are examples:

        use GXML;

        my $gxml = new XML::GXML();

        # Take a scalar, return a scalar
        my $xml = '<basetag>hi there</basetag>';
        my $new = $gxml->Process($xml);

        # Take a file, return a scalar
        print $gxml->ProcessFile('my-xml-file.xml');

        # Take a file, output to another file
        $gxml->ProcessFile('source.xml', 'dest.xml');

That's all there is to it! The more advanced API features will be covered later. Now let's go to what the "processing" does, starting with attributes and variables.

On to Variables!

Back to the GXML Guide

Copyright (c) 2001-2002 Josh Carter