Sean Campbell > HTML-DWT > HTML::DWT

Download:
HTML-DWT-2.08.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 2.08   Source  

NAME ^

HTML::DWT - DreamWeaver HTML Template Module

INSTALLATION ^

Unzip/tar the archive:

  tar xvfz HTML-DWT-2.08

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,
                path => '/var/www/html',
                xml => $xml-data,
                );

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.

associate: 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).

case_sensitive: 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.

no_includes: 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.

path: HTML::DWT will accept an array of paths under which it will look for template and library files. The module will also look in directories specified by the environment variables $HTML_TEMPLATE_ROOT and $DOCUMENT_ROOT. Absolute path names are not checked, although the pseudo-paths '/Library/' and '/Templates/' are treated as relative paths.

xml: HTML::DWT will accept a string value containing an XML document that conforms to the HTML-DWT DTD. This string may be associated with the template object through the XML option in the constructor. Each <item> tag in the XML document will have its contents loaded into a corresponding template field. A valid HTML-DWT XML document will look like this:

  <?xml version="1.0"?>
  <templateItems template="/Templates/temp.dwt">
    <item name="centercont"><![CDATA[Testing]]></item>
    <item name="doctitle"><![CDATA[<title>testing</title>]]></item>
    <item name="leftcont"><![CDATA[Testing]]></item>
    <item name="rightcont"><![CDATA[Testing]]></item>
  </templateItems>

These documents can be automaticly generated both by HTML::DWT based on template data using export(), or by Macromedia Dreamweaver.

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().

print_to: 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.

type: Dreamweaver supports two XML styles for templates, the Dreamweaver style, and another standardized style using editable region name tags. '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'.

output: 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.

filename: 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.

print_to: 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.

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, CGI.pm.

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.

syntax highlighting: