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 time, containing the current
# time. This variable will be used below.
my $self = $_;
$self->{'time'} = localtime(time());
''; # Return an empty string; result becomes embedded into the
# HTML page

The current time

Your HTML::EP system is up and running: The current time is $time$.
NEWS
HTML::EP does now have a homepage, a CVS repository and a bug tracking
system. Try
http://html-ep.sourceforge.net/
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 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 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::EmbPerl(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
. Note, you need a late version,
including the CGI::Cookie module.
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 . :-)
Mail::Internet
Graham Barr wrote the MailTools package.
Some parts of it, in particular the Mail::Internet module is
used for sending mail from within the HTML page. Thank very
much, Graham!
Storable Raphael Manfredi's
excellent Storable module is used for storing sessions. I
owe him much, as Storable is usefull in a lot of other
modules.
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
Note that you don't need to install these manually, the CPAN module will
help you. See the the section on "Automatic Installation" below.
Automatic Installation
Installing this module (and the prerequisites from above) is quite
simple, if you have the CPAN module available and network access, you
might try an automatic installation:
perl -MCPAN -e shell
If the CPAN prompt appears, asking you for commands, enter
install Bundle::HTML::EP
Automatic installation typically doesn't work on Windows, due to a
missing C development environment. However, you might try
ppm install http://www.cpan.org/authors/id/J/JW/JWIED/HTML-EP.ppd
Manual Installation
If automatic installation doesn't work, you just fetch the archive,
extract it with
gzip -cd HTML-EP-0.1125.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.1125
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
You have different options for integrating EP into your WWW server,
depending on which server you are using and the permissions you have.
The simplest possibility is running an external CGI binary. Another
option is to use mod_perl with Apache, see the section on "Using
mod_perl" below.
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
AddType 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'. On Windows, you should replace ep.cgi with
ep.cgi.bat. Make sure, that the ScriptAlias line is entered *before* any
other ScriptAlias instruction! In particular, the following would be
wrong:
ScriptAlias /cgi-bin/ /home/httpd/cgi-bin/
...
ScriptAlias /cgi-bin/ep.cgi /usr/bin/ep.cgi
The first rule would be applied before our rule, so that it could never
match.
From now on your server will never return files with extension .ep
directly! Verify your installation by creating the following file:
Local time
The current time is:
scalar(localtime(time))
(Note that this is a much shorter version of the example in the
synopsis.) Store it as `/test.ep' on your web server and retrieve the
file via your Web server. If you see the time displayed, you are up and
running.
Using mod_perl
The EP package can be integrated into mod_perl, for example by using the
following commands in `srm.conf':
PerlModule Apache::EP
SetHandler perl-script
PerlHandler Apache::EP->handler
Options ExecCGI
Keep in mind, that mod_perl differs in many details from programming CGI
binaries. In particular you might need to restart Apache for loading
changes in modules.
Using the Internet Information Server
I am sure there is a better way of installation, in the sense of
mod_perl, however, I am no IIS expert. I can only recommend using Perl
as an external binary, in the sense of CGI.
The idea is to advice the IIS, that files with extension .ep have to be
executed by running
C:\Perl\bin\perl.exe c:\Perl\bin\ep.cgi %s%s
with %s%s being the path to the EP document. (Of course the paths have
to be adjusted to your local Perl.) This can be done by creating a new
extension in the window "Base directory/Configure". (Window name
translated from the german IIS, itīs "Basisverzeichnis / Konfigurieren"
here and might be different in english.)
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, ` HTML::EP::Session ---isa---> HTML::EP
We start writing our Shop extension like any other Perl package:
package Shop;
@Shop::ISA = qw(HTML::EP::Session); # HTML::EP::Session inherits
# from HTML::EP
sub _ep_shop_session {
my($self, $attr) = @_;
# Initialize the session
...
'';
}
sub init {
my $self = shift;
if (!$self->{'_ep_shop_initialized'}) {
$self->{'_ep_shop_initialized'} = 1;
$self->SUPER::init();
# Do something here
...
}
}
In the HTML page we load this package as follows:
This will do a require Shop, bless the object $self into the class
*Shop* and call $self-init()>. Note that we allow the init method to be
called more than once, this is important for stacking packages.
By default packages are loaded from Perl's system directories. You can
use the attribute *lib* to add private directories to the library search
path. This can be relative to the servers document root, as in
Inheriting from multiple extensions
You may use multiple ep-package statements, as in
Your object will be blessed into a new class, that inherits from both.
However, note that the order is reversed: In the above example, your
object will be an instance of class HTML::EP::PACK2 and
HTML::EP::PACK2::ISA will be set to
qw(HTML::EP::Session HTML::EP::Locale)
CHANGES
This section describes user visible changes against previous versions.
For details and other modifications see the `ChangeLog' file, that is
part of the distribution.
epparse
epperl In previous versions it was not possible to include EP variables
or Perl code in attributes of EP commands, unless using a prefix
`epparse-' or `epperl-', as in
This is no longer the case, because the package now autodetects
whether you are using such constructs. (At least it should. :-)
The obvious disadvantage is an incompatibility, but the new
version is much better readable and surprisingly even (much!)
faster, because only hash values are modified and not hash
structures.
TODO
Create an EP server that is accessible via a small C wrapper
Add a preprocessor, that creates Perl code as output.
AUTHOR AND COPYRIGHT
This module is
Copyright (C) 1998-1999 Jochen Wiedmann
Am Eisteich 9
72555 Metzingen
Germany
Phone: +49 7123 14887
Email: joe@ispsoft.de
All rights reserved.
You may distribute this module under the terms of either the GNU General
Public License or the Artistic License, as specified in the Perl README
file.
SEE ALSO
the DBI(3) manpage, the CGI(3) manpage, the HTML::Parser(3) manpage