This article was first published on www.take23.org
Enhancing your web pages with HTML::Embperl
HTML::Embperl is a flexible Perl module which gives you the ability to embed perl code in your HTML pages. It allows quick and powerful scripting of HTML, allowing you to easily like perl modules and the web. It takes advantage of mod_perl to be a fast efficent solution which requires no special configuration to make a given page dynamic, but does not require mod_perl - in fact, you can use it without a web server at all, to generate HTML content for use in email, or to automatically build static web pages to be served later.
This document describes how to install embperl, and should teach you the first steps towards making your web pages dynamic with empberl. It draws heavily on the fine documentation included with the Embperl package, and on the web site at http://perl.apache.org/embperl/.
Before you can use Embperl, you will need to install and configure it. As with all modules, you should fetch the latest release from CPAN (http://www.cpan.org/), uncompress it, and run the following commands:
perl Makefile.PL make make test
And, if all the tests pass:
make install
If you want the mod_perl support, you'll need to have your apache source tree handy, and know where it is to point HTML::Embperl at it.
Once you've got Embperl installed, you'll want to tell apache that you want certain files to be processed by Embperl - this is covered in the documentation, and one of the simplest ways to do this is:
SetEnv EMBPERL_DEBUG 2285
<Files *.epl>
SetHandler perl-script
PerlHandler HTML::Embperl
Options ExecCGI
</Files>
AddType text/html .epl
This tells apache that all files ending in the extension .epl are to be processed by the HTML::Embperl module.
Like all good languages of any kind, the first thing we'll do is write a page that prints ``Hello World'' to the browser.
Normally, we could do this with something like:
<html>
<head>
<title>Hello World!</title>
</head>
<body>
<h1>Hello World!</h1>
<p>
Hello to all the world.
</p>
</body>
</html>
And, if you try putting this content in a .epl file and viewing it from your web browser, you will get the message ``Hello World'' printed. But it's not very dynamic. Let's try another version.
[$ var $hello_object $] [- $hello_object = "World"; -]
<html>
<head>
<title>Hello [+ $hello_object +]!</title>
</head>
<body>
<h1>Hello [+ $hello_object +]!</h1>
<p>
Hello to all the [+ lc $hello_object +].
</p>
</body>
</html>
I've gone from something fairly simple - a standard HTML page, to something more flexible and dynamic - a page that knows what kind of thing it's saying hello to, and doesn't need the redundancy of repeating that all over the page. If we go through this page, we'll discover how to use certain key new ideas that'll be useful on almost every embperl page you'll ever write.
[$ var $hello_object $]
This line declares a variable global to the entire page. We could live
without it, but it's easier to find bugs in Embperl code that uses this
option. One use of [$ var $] on any page will turn on the requirement
for variables to be declared for ALL variables on that page.
We also see our first Embperl specific markup tag, and should note their general form of:
[<a character> some stuff with meaning to Embperl <a character>]
which will be a pattern consistent through the rest of the Embperl markup you'll see.
[- $hello_object = "World"; -]
This line just inserts some perl code into the page, which will be executed every time the page is viewed by a user. The syntax is:
[- some perl code -]
and again, you'll use this almost everywhere. You can't use print
to output to the page inside this kind of code block, unless you write
to the special OUT filehandle.
<html>
<head>
<title>Hello [+ $hello_object +]!</title>
This is the third kind of embperl markup - it takes a valid perl expression, and inserts whatever is returned by that expression into the page. The syntax is:
[+ some-perl-expression +]
And it's the most common way to actually get data into your HTML.
</head>
<body>
<h1>Hello [+ $hello_object +]!</h1>
<p>
Hello to all the [+ lc $hello_object +].
Taking advantage of the fact that [+ +] lets you use any perl expression,
here we generate the lowercase form of the string before printing it,
because we're not in a title.
</p>
</body>
</html>
Now, despite only covering one simple (and very traditional!) example, we've managed to cover almost half of the markup you'll need to generate useful Embperl pages.
The set of `meta-commands' available in Embperl is very powerful, and where Embperl truly comes into it's own for the flexible scripting of HTML.
Embperl meta-commands are, well, probably the clearest way to show you is to use an example, and give the input and output. The code:
[- @days = qw(Mon Tue Wed Thu Fri Sat Sun); -] <ul> [$ foreach $day (@days) $] <li>[+ $day +]</li> [$ endforeach $] </ul>
This will print out the days of the week, in an unordered HTML list. The generated HTML will look roughly as follows:
<ul> <li>Mon</li> <li>Tue</li> <li>Wed</li> <li>Thu</li> <li>Fri</li> <li>Sat</li> <li>Sun</li> </ul>
Most of the normal control flow structures you're used to from perl have Embperl equivalents, like:
if[$ if $value $] some html [$ else $] some other html [$ endif $]
while[$ while (test_func()) $] some html [$ endwhile $]
Now, we knew enough Embperl that we should be able to tackle a more complicated example. For administrative purposes, we want to be able to get a list of users currently defined on our system, and also show their recorded names. We can bring together what we've learned to do it like this:
[$ var $pw $]
[- use User::pwent; -]
<html>
<head>
<title>Users</title>
</head>
<body>
<h1>Local Users</h1>
<table>
<tr>
<th>Username</th>
<th>Real Name</th>
</tr>
[$ while ($pw = getpwent) $]
<tr>
<td>[+ $pw->name +]</td>
<td>[+ $pw->gecos +]</td>
</tr>
[$ endwhile $]
</table>
</body>
</html>
Looking at this line by line:
[$ var $pw $]
Declare the one variable we're going to use, $pw, used to hold the
password entry for a given user.
[- use User::pwent; -]
Load the User::pwent standard module, which provides utility methods
that make it easier to read the password database.
<html>
<head>
<title>Users</title>
</head>
<body>
<h1>Local Users</h1>
Standard HTML stuff to start the page.
<table>
<tr>
<th>Username</th>
<th>Real Name</th>
</tr>
The start of a table we're going to fill in the middle of with user data.
[$ while ($pw = getpwent) $]
Start a Embperl while loop, and for each loop, get a
User::pwent object into $pw. getpwent
will return one object per user for as many users as are defined on the system,
then return a false value.
<tr>
<td>[+ $pw->name +]</td>
<td>[+ $pw->gecos +]</td>
</tr>
Write out a table row, getting details from the $pw variable, which
stores a User::pwent object.
[$ endwhile $]
Finish off the while loop, to indicate exactly how much HTML to repeat.
</table>
The end of the table.
</body>
</html>
And a standard end to a HTML page.
I've not covered a very large portion of Embperl - notable omissions
are the automatic filling in of certain HTML tags, the session support,
and EmbperlObject, all of which are documented on the web site, but
already we know how to add flexible dynamic content to our web pages,
without the overhead of CGI programming, and without the inconvenience
of requiring that all HTML be embedded in code that traditional mod_perl
request handlers would require.
For more information, see the Embperl web site at http://perl.apache.org/embperl/