NAME
    HTML::DWT - DreamWeaver HTML Template Module

INSTALLATION
  Unzip/tar the archive:

      tar xvfz HTML-DWT-2.07

  Create the makefile

      perl Makefile.PL

  Make the module (must have root access to install)

      make
      make test
      make install

SYNOPSIS
      use HTML::DWT;
      
      $template = new HTML::DWT(filename => "file.dwt");    
      %dataHash = (
                    doctitle => 'DWT Generated',
                    leftcont => 'some HTML content here'    
                    );  
      $html = $template->fill(\%dataHash);
      
      or
      
      use HTML::DWT qw(:Template);
      
      $template = new HTML::DWT(filename => "file.dwt");
      $template->param(
                       doctitle => '<title>DWT Generated</title>',
                       leftcont => 'Some HTML content here'
                       );
      $html = $template->output();

DESCRIPTION
    A perl module designed to parse a simple HTML template file
    generated by Macromedia Dreamweaver and replace fields in the
    template with values from a CGI script.

METHODS
  Options

      use HTML::DWT qw(:Template);

    Using the Template option allows for built in support in
    HTML::DWT for the HTML::Template invocation syntax (param(),
    output() etc.) See HTML::Template for more details. It is best
    to require a version of 2.05 for HTML::DWT to support this
    option.

  new()

      new HTML::DWT("file.dwt");

      new HTML::DWT(
                    filename => "file.dwt",
                    associate => $q,
                    case_sensitive => 1,
                    no_includes => 1,
                    );

    Creates and returns a new HTML::DWT object based on the
    Dreamweaver template 'file.dwt' (can specify a relative or
    absolute path). The Second instance is recommended, although the
    first style is still supported for backwards compatability with
    versions before 2.05.

    The associate option allows the template to inherit parameter
    values from other objects. The object associated with the
    template must have a param() method which works like HTML::DWT's
    param(). Both CGI and HTML::Template fit this profile. To
    associate another object, create it and pass the reference
    scalar to HTML::DWT's new() method under the associate option
    (see above).

    The case_sensitive option allows HTML::DWT to treat template
    fields in a case-sensitive manner. HTML::DWT's default behavior
    is to match all fields in a case-insensitive manner (i.e.
    doctitle is considered the same as DOCTITLE or DocTitle). Set
    case_sensitive to 1 to over- ride this default behavior.

    HTML::DWT will by default look for any included Dreamweaver
    library item files (.lbi files) that may be specified in the
    template using the <!-- #BeginLibraryItem "file.lbi" -> field.
    The module will open the specified library file and will include
    the file's contents in the generated HTML. Setting no_includes
    to 1 will over-ride this default behavior.

    Additional options may be passed to the constructor to emulate
    HTML::Template behavior (see that module's documentation)
    although only filename, associate, case_sensitive and
    no_includes are supported as of HTML::DWT version 2.07.

  fill()

      $template->fill(\%dataHash);

      $template->fillTemplate(\%dataHash);

    Takes a hash reference where the keys are the named areas of the
    template and the associated values are HTML content for those
    areas. This method returns a complete HTML document, which can
    then be sent to STDOUT (the browser). The fill() method is the
    prefered means of accessing this functionality; fillTemplate()
    is implemented only to support versions of HTML::DWT earlier
    than version 2.05.

  param()

      $template->param();

      $template->param('doctitle');

      $template->param(
                      doctitle => '<title>DWT Generated</title>',
                      leftcont => 'Some HTML content here'
                      );

    Takes a hash of one or more key/value pairs, where each key is a
    named area of the template, and the associated value is the HTML
    content for that area. This method returns void (HTML
    substitiutions are stored within the object awaiting output()).

    If called with a single paramter--this parameter must be a valid
    field name--param() returns the value currently set for the
    field, or undef if no value has been set.

    If called with no parameters, param() returns a list of all
    field names.

    NOTE: All Dreamweaver templates store the HTML page's title in a
    field named 'doctitle'. HTML::DWT will accept a raw title
    (without <title> tags) and will add the appropriate tags if the
    content of the 'doctitle' field should require them.

    This is a HTML::Template compatible method.

  clear_params()

      $template->clear_params();

    Clears all field values from the template's parameter list and
    sets each parameter to an undefined value.

    This is a HTML::Template compatible method.

  output()

      $template->output();
      
      $template->output(print_to => \*STDOUT);

    Returns the parsed template and its substituted HTML for output.
    The template must be filled using either fill() or param()
    before calling output().

    Alternativly, by passing a filehandle reference to output()'s
    print_to option you may output the template content directly to
    that filehandle. In this case output() returns an undefined
    value.

    This is a HTML::Template compatible method.

  export()

      $template->export(
                        type  => 'dw',
                        output => 'file',
                        filename => 'dwt.xml',
                        print_to => \*STDOUT
                        );

    This method exports the filled template data to an XML file
    format. Dreamweaver supports two XML styles for templates, the
    Dreamweaver style, and another standardized style. 'dw', the
    type flag for the Dreamweaver style is the default setting for
    export(), although you may change that by using the type option
    and passing it either 'dw' or 'er'.

    If no output style is indicated, export() will return the XML
    document. Output may be sent to a file, in which case the output
    option is passed the value 'file', or output may be sent to an
    open filehandle, in which case output is passed a 'FH' value.

    If sending output to a file, the filename option musst be
    included with a valid filename (absolute or relative paths are
    acceptable). Export will return the filename, or undefined on an
    error. Error messages are stored in $HTML::DWT::errmsg.

    If sending output to a filehandle instead of using the filename
    option , pass a reference to a filehandle to the print_to
    option. For convienience of use with CGI scripts, export() will
    include a 'Content-type: text/xml' header before the XML
    document when outputting to a filehandle. When sending output to
    a filehandle export() returns undefined.

  query()

      $template->query();

      $template->query('doctitle');

      $template->query(name => 'doctitle');

    Returns the 'type' of the template field specified. For all
    HTML::DWT fields the type is 'VAR' (HTML::DWT doesn't support
    HTML::Template's idea of LOOPs or IFs). If called with no
    parameters, query() returns a list of all field names.

    This is a HTML::Template compatible method.

DIAGNOSTICS
    Template File $file not opened:
        (F) The template file was not opened properly. This message
        is stored in $HTML::DWT::errmsg

BUGS
    No known bugs, but if you find any please contact the author.

COMPATABILITY NOTES
    HTML:DWT is moving towards supporting much, if not all of the
    functionality of HTML::Template for Dreamweaver templates. Not
    All HTML::Template functionality is fully supported yet, and
    while the HTML::Template documentation should be the reference
    source for all HTML::Template compatible methods and functions,
    only those methods documented as being supported, and the manner
    of their support as documented in HTML::DWT are actually
    supported by this module.

    In plain english--RT(HTML:DWT)M and use it. :)

    If you would like to assist in the development of this module,
    please contact the author.

AUTHOR
    S.D. Campbell, whytwolf@spots.ab.ca

SEE ALSO
    perl(1), HTML::Template, HTML::LBI.

LICENSE
    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation; either version 2 of
    the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public
    License along with this program; if not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
    USA.