NAME
HTML::EP - a system for embedding Perl into HTML
SYNOPSIS
CGI-Env
This is an HTML document. You see. Perhaps you wonder about
the unknown HTML tags like ep-comment above? They are part
of the EP system. For example, this comment section will
be removed and you won't see it in your browser.
# This is an example of embedding Perl into the page.
# We create a variable called env, containing our environment
# variables. This variable will be used below.
my $self = $_;
my $env = [];
my($var, $val);
while (($var, $val) = each %ENV) {
push(@$env, { var => $var, val => $val });
}
$self->{env} = {%ENV};
'';
Your CGI environment
Your CGI environment looks as follows:
Variable | Value |
$e->var$ | $e->val$ |
---|
WARNING
THIS IS ALPHA SOFTWARE. It is *only* 'Alpha' because the interface (API)
is not finalised. The Alpha status does not reflect code quality or
stability. In particular the following things might change without
further notice:
The way of passing variables as attributes. For example, currently
one can use
to pass the form variable *email* into method calls. I consider
changing this to
or whatever. The decision mainly depends on performance
considerations and readability. See the section on "Variables"
below.
The C interface of introducing own methods. This depends on whether
I need changes for inserting the module into mod_perl. See the
section on "TODO" below.
DESCRIPTION
Have you ever written a CGI binary? Easy thing, isn't it? Was just fun!
Have you written two CGI binaries? Even easier, but not so much fun.
How about the third, fourth or fifth tool? Sometimes you notice that you
are always doing the same:
Reading and parsing variables
Formatting output, in particular building tables
Sending mail out from the page
Building a database connection, passing CGI input to the database and
vice versa
Talking to HTML designers about realizing their wishes
You see, it's soon to become a pain. Of course there are lots of little
helpers around, for example the CGI module, the mod_perl suite and lots
of it more. Using them make live a lot easier, but not so much as you
like. the CGI(3) manpage. the mod_perl(3) manpage.
On the other hand, there are tools like PHP/FI or WebHTML. Incredibly
easy to use, but not as powerfull as Perl. Why not get the best from
both worlds? This is what EP wants to give you, similar to ePerl or
HTML::EmbPerl. I personally believe that EP is simpler and better
extendible than the latter two. the ePerl(1) manpage. the
HTML::EmbPerm(3) manpage.
In short, it's a single, but extensible program, that scans an HTML
document for certain special HTML tags. These tags are replaced by
appropriate output generated by the EP. What remains is passed to the
browser. Its just like writing HTML for an enhanced browser!
Prerequisites
As far as I know EP depends on no system dependent features. However, it
relies on some other Perl modules:
CGI The CGI module should be a part of your Perl core's
installation. If not, you should definitely upgrade to Perl
5.004. :-) My thanks to Lincoln D. Stein
.
HTML::Parser
This module is used for parsing the HTML templates. My
thanks to Gisle Aas .
libwww The LWP library contains a lot of utility functions, for example
HTML and URL encoding and decoding. Again, my thanks to
Gisle Aas . :-)
Perl itself and the above modules are available from any CPAN mirror,
for example
ftp://ftp.funet.fi/pub/languages/perl/CPAN/modules/by-module
Installation
Installing this module (and the prerequisites from above) is quite
simple. You just fetch the archive, extract it with
gzip -cd HTML-EP-0.1000.tar.gz | tar xf -
(this is for Unix users, Windows users would prefer WinZip or something
similar) and then enter the following:
cd HTML-EP-0.1000
perl Makefile.PL
make
make test
If any tests fail, let me know. Otherwise go on with
make install
This will put the required Perl modules into a destination where Perl
finds it by default. Additionally it will install a single CGI binary,
called `ep.cgi'.
The docs are available online with
perldoc HTML::EP
If you prefer an HTML version of the docs, try
pod2html lib/HTML/EP.pm
in the source directory.
Using the CGI binary
I suggest that you choose an extension and configure your WWW server for
feeding files with this extension into `ep.cgi'. For example, with
Apache, you can add the following lines to your `srm.conf':
ScriptAlias /cgi-bin/ep.cgi /usr/bin/ep.cgi
AddHandler x-ep-script .ep
Action x-ep-script /cgi-bin/ep.cgi
This tells Apache that files with extension ep.cgi are handled by the
CGI binary `/usr/bin/ep.cgi'. Make sure, that the ScriptAlias line is
entered *before* any other ScriptAlias instruction!
From now on your server will never return files with extension .ep
directly! Verify your installation by creating the following file:
print "content-type: text/plain\n\n";
print "It worked! Your EP system is up and running.\n";
Store it as `/test.ep' on your web server and retrieve the file via your
Web server. You should neither see the `ep-perl' not the `print'
instructions.
Available methods
All EP tags are starting with the prefix *ep-*. Some available tags are:
ep-comment
This is a multi-line tag for embedding comments into your HTML page.
But why use this tag, instead of the usual HTML comment, `
This is another comment, but you won't see it
in your browser. The HTML editor will show it
to you, however!