HTML-Subtext - README

HTML::Subtext Version 1.03
Sun Mar 7 14:16:53 PST 1999

This module is designed to do simple textual substitutions into an HTML template document in an "offline" process. It is not a mechanism for implementing server-side includes -- there are plenty of other perl modules that do that. There are also other modules which let you embed arbitrary perl expressions in a template. [These are quite powerful and useful, but assume a certain sophistication on the part of the template author.] HTML::Subtext doesn't do that either.

What it does do is allow you to compose an HTML document using your favorite WYSIWYG HTML editor, include place-holder strings in it like "Customer's name here", and then turn those place holders into a substitution field by making the text a link to a special 'subtext:' URI. This approach has the following advantages:

Any Web server can display the finished documents -- you don't need special support for server-side includes, or active server pages, or anything beyond plain vanilla HTML. (Of course it is still possible to use those features if you have and want them.)
The templates are easy for a non-technical user to prepare (in particular a non-perl-literate user).
It's possible to view the template in its unprocessed form, in a regular Web browser, and to see where the substituted strings will be placed and approximately what your finished document will look like.
The substitution mechanism is robust against errors in the template specification. That is, the output is still a valid HTML document even if some of the substitution field names are misspelled or invalid.

In short, the idea is to make things as simple and convenient as possible from the perspective of the template author. I looked through a lot of HTML manipulation packages on CPAN, but none of them struck me as having quite this goal in mind. [Perhaps this is because the very idea of using a template is that you only have to get it right once, so power and versatility are more important than convenience. But for the particular application I was building at the time, there were a number of templates to be built, and they were to be tweaked fairly regularly.]

INSTALLATION

Installation is accomplished in the usual manner-- unpacking the tar archive should create a directory called HTML-Subtext-1.03/. cd into this directory and issue the following commands:

      perl Makefile.PL
      make
      make test

Assuming all the tests succeed, you may require root or administrator privledges on your system for the final step:

make install

It's possible to make use of the module without installing it. See the perl documentation on @INC for details.

ACKNOWLEDGEMENTS

The implementation of this module was almost trivially simple, thanks to the excellent work of Gisle Aas (and others) on the HTML::Parser and URI modules.

NAME

HTML::Subtext - Perform text substitutions on an HTML template

SYNOPSIS

      use HTML::Subtext;
      %context = ( ... ); # Hash of names to substitution text
      $p = HTML::Subtext->new('CONTEXT' => \%context);
      $p->parse_file("template.html");

DESCRIPTION

`HTML::Subtext' is a package for performing text substitutions on a specially formatted HTML template. The template uses normal HTML markup, but includes links of the form:

<a href="subtext:foo/bar">This text will be replaced</a>

The URI in this link tells `HTML::Subtext' to check in the provided hash `'CONTEXT'' for a key named `'foo/bar''. If this lookup succeeds in producing a string value, the text in the body of the link is replaced by that value.

EXAMPLES

This example performs substitutions into a template embedded into the Perl code as a here-document.

use HTML::Subtext;

      %context = (
        'author/name' => 'Kaelin Colclasure',
        'author/email' => '<a href="mailto:kaelin@acm.org">kaelin@acm.org</a>'
      );
      
      $p = HTML::Subtext->new('CONTEXT' => \%context);
      $p->parse(<<EOT);
      <html><head><title>example</title></head><body>
      <a href=\"subtext:author/name\">Author's name here</a>
      <a href=\"subtext:author/email\">mailto: link here</a>
      </body></html>
      EOT

When run, the example produces the following output:

      <html><head><title>example</title></head><body>
      Kaelin Colclasure
      <a href="mailto:kaelin@acm.org">kaelin@acm.org</a>
      </body></html>

SEE ALSO

the HTML::Filter manpage, the HTML::Parser manpage

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.