When I started writing Embperl in fall 1996, it was mostly out of my laziness. I wanted a tool that does as much work as possible for me and let me only write the absolute neccessary things. A lot of features had beed created out of this motivation and also has been proved very usefull also 3 and a half years later. Of course more guts have been added over the time and the following article is the first one of a series about HTML::Embperl, which should make you familar with these possibilities. Topics I plan to write about are:
You will see when we are moveing towards the end of this serie, while the starting point was easy and rapid websites creation, Embperl has grown up and nowadays also has rich possibilities for structured and modularized creation of great sites, were Embperl 2.0 will add a totaly new set of possibilties including handling of XML. In this way Embperl is like Perl, you can write small quick & dirty scripts and also great well structured programms.
Basicly Embperl lets you (like other modules e.g. Apache::ASP, HTML::Mason) embedd Perl code in your HTML documents. The advantage of embedding Perl code in HTML is, that you can use your favorite html editor to create the pages and more over that people without knowledge of Perl can create and edit the design of a page. Even if you prefer to write your HTML code in a normal text editor, it's much easier to write it this way around.
Embperl is a server side tool, that means it intercepts the page while it is send by the web server, interprets some special markups in it and send the result to the browser. This could be achieved by running Embperl as a CGI script, but much more powerfull is, to let Embperl work under mod_perl inside of Apache. In this case Embperl does a lot of caching which speed up things a lot. Addtionaly you are able to use the full Apache API thru mod_perl. Last but not least you can use Embperl from the command line and you are not limited to HTML files. For example the module HTML::Embperl::Mail uses Embperl to generate plain ascii mails and send them via SMTP.
So now let's start with an example. A simple document would look like the following:
<html>
<head><title>Simple Embperl Document</title></head>
<body>
[- @envkeys = sort keys %ENV -]
<table>
[$ foreach $key (@envkeys) $]
<tr>
<td> [+ $key +] </td><td> [+ $ENV{$key} +] </td>
</tr>
[$ endforeach $]
</table>
</body>
</html>
The current version of Embperl uses square brackets to delimit the Perl
code. It don't uses HTML tags to mark the Perl-code (like for example ASP,
which uses <% %>), because when I start writing Embperl, HTML editors weren't able
to handle them correctly (if they could at all). So I decided it was the
best, to put the Perl code as something in, which HTML editors treats as
normal text (and let Embperl fix the things they screw up in the Perl code
(e.g. translate < back to < inside a Perl expression)). Nowadays HTML editors are cable of handling ASP
like tags correctly and will display them as a small icon. If you preferer
to see your Perl code as text or only as small icon is a matter of taste or
the way you work, so the next version of Embperl will support both. But
let's get back to our example. The first non HTML block is [- @envkeys = sort keys %ENV -]. The [- -] delimiters tells Embperl to simply execute the Perl code inside, in
opposite to the [+ +] blocks, which causes Embperl to replace the block with the value inside the
bracktes. There is a third sort of block in our example. [$ $] is used to enclose special Embperl metacommands, which mainly controls the
order of the execution inside the page. Here we use a foreach command, which behave similar to the Perl's one. There are other types of
loops and also if/else and so on. So as you easily can see the above page
will display the whole environement in a HTML table. The output will look
someting like
<html>
<head><title>Simple Embperl Document</title></head>
<body>
<table>
<tr>
<td> SERVER_SOFTWARE </td><td> Apache/1.3.9 (Unix) DAV/0.9.14 mod_perl/1.21 </td>
<td> DOCUMENT_ROOT </td><td> /local/www/data </td>
<td> GATEWAY_INTERFACE </td><td> CGI-Perl/1.1 </td>
<td> REMOTE_ADDR </td><td> 10.11.12.10 </td>
...
</tr>
</table>
</body>
</html>
The above example shows also, there is no need to declare any variables
inside your page. Just like globals in Perl, you simply can use them.
Actually they are globals, but Embperl takes care that separate pages runs
in separate namespaces and variables are cleaned up after the request. That
is especialy important when running under mod_perl, because, in opposite to
a CGI script, the Perl interpreter does not terminate after one request and
normal globals will keep their value until the next request. So variables
you use inside a Embperl page, actually behave like if they were declared
with my, but without the need to declare them. Anyway, if you want to do so you
can use the [$ var $] metacommand to switch to strict mode and declare all your variables.
Another thing that Embperl does for you is setting up the correct http
headers, so you don't have to worry about such standard tasks, but in case
you want to add http headers, you just have to put them in the hash
%http_headers_out. While HTTP headers are send to the browser, often the
browser will send data to your page. The query string of a GET request or
the data of a POST request is placed in the hash %fdat and the
array @ffld by Embperl. While the %fdat hash
holds the name/value pairs sent to your script, the @ffld
array has all the names in the order in which they are send by the browser.
If we go back to the above example we could write:
<table>
[$ foreach $key (@ffld) $]
<tr>
<td> [+ $key +] </td><td> [+ $fdat{$key} +] </td>
</tr>
[$ endforeach $]
</table>
to display all the values that are posted to this page, for example by an
HTML form which has the url of this example in it's ACTION attribute. Suppose you have a small form like the following
<form method="get" action="example3.html">
EMail: <input type="text" name="email">
Message: <input type="text" name="msg">
</form>
were a user can enter his email adress and a message and you want to verify that the user has really enterend something in the email field. If not you want to redirect him back to the input form, if yes you simply display his input. Then you could do this with code similiar to a page which looks like the following
[-
if (!$fdat{email})
{
$http_headers_out{location} = "http://www.host.com/path/input.html"; ;
exit ;
}
-]
Your email address is: [+ $fdat{email} +] <br>
[$ if $fdat{msg} $]
You have entered the following message: : [+ $fdat{msg} +] <br>
[$else$]
You don't have entered a message <br>
[$endif$]
In the first block the code checks if the email has entered and if not sets the location header and exits the page. If the HTTP location header is set Embperl generates the appropriative status code, which causes the browser to redisplay the input form. Otherwise the page continues and first shows the email address entered by the user and, if any, the entered message from the user.
Debugging CGI applications is often a hard task, because they run in a special environement under the control of the web sever. Embperl helps you doing this job by providing a very detailed logfile of what it does while it processes the page. You can enable more or less information by setting appropriative flags. This gives you information about formdata, environement variables, http headers, executed Perl code, the result of the execution and much more. Also while developing an application, Embperl is able of creating a small link at the top of each page which leads you directly to the display of the logging information for current request. Server error pages contains the Perl and Embperl error message which gives you the line numbers of your source file and, when enabled, provide you with a direct link into the correct location of the logfile.
This first article covered the basics of Embperl, how to embedd Perl code (not only) in your HTML documents and how to get addtional information like HTTP headers and formdata from and to the browser. In the next month we will see which features Embperl has, which are specialy designed for HTML to make creation of web pages even easier. If you like to get more information download it from your favorite CPAN ftp mirror or go the Embperl Website at http://perl.apache.org/embperl/. For the few of us, like me, who are speaking german, there is a german Embperl website at http://www.ecos.de/embperl/ . These sites contains also information about the Embperl mailinglist and how to install Embperl on your computer.