A Short Course in Embperl

For those familiar with both Perl and HTML, using Embperl is easy. Of course, the Embperl documentation lays it all out clearly. In brief, code meant for the Perl interpreter is enclosed inside specially defined square bracket tags. For instance, the [$ $] tag set encloses a Perl expression whose result is placed into the HTML page at that spot. Assume for a moment that there is a Perl variable $total within a page -- we can drop the value of total anywhere in the HTML, such as a table row:

<TR><TD>Total</TD><TD>[+ $total +]</TD></TR>

The tagset [$ $] is used to create Perl statement boundaries within which there may be a mix of HTML and Perl; for example, imagine constructing a Perl while statement that output some HTML mixed with Perl:

<TABLE>
 <TR>
  [- $counter=0 -]
  [$ while $counter<=100 $]
   <TD>[+ $counter +]</TD>
   [- $counter++ -]
  [$ endwhile $]
 </TR>
</TABLE>

Processed by Embperl, the above code would simply produce a table with one row and columns numbered 0 through 100. Notice the third important tag set, [- -], used to enclose blocks of pure Perl. We'll see more of each of these types of tags in the relevent scripts that follow.

Because embedded Perl code can be broken up into pieces amidst HTML code, the execution environment is not exactly the same as a pure Perl script. Embperl constructs scoping rules that are important to understanding how variables created in one segment of code may or may not be seen by another segment of code elsewhere in the page.

We're especially fond of using Embperl to create small "components" -- pieces of Perl code that can be imported in a number of web pages. In this article, we're going to look at a few such components specifically -- a component to require that a user has logged in prior to displaying page content and a component to create a user-sensitive control panel (or navigation bar) on our web pages.

Execute, @param, and %fdat

Embperl has some special features that aid in integrating Perl and web pages. Three of these that we rely on greatly are the Execute function, the @param array, and the %fdat hash.

The function Execute () is akin to an include on steroids. In its simplest incarnation, you can use this function to simply include the content of another HTML file:

<TABLE>
 [- Execute ("footer.html") -]
</TABLE>

Above we can imagine a file, footer.html, that contains the rows and columns that make up a page footer. Although footer.html may contain plain HTML it could, of course, contain embedded Perl itself. You can imagine that you might want to pass some values to the Perl embedded into footer.html, thereby treating the included code almost as a type of subroutine.

<TABLE>
 [- Execute ("footer.html",$total,$username) -]
</TABLE>

Again, these are fictional examples, but you can see how we might pass the values of $total and $username into footer.html, which may render those into the footer for instance. Specifically, the code inside footer.html will see these values through the @param array. Imagine now that we're inside footer.html:

<TR>
 <TD>Basket subtotal:</TD>
 <TD>[+ $param[0] +]</TD>
 <TD>[+ $param[1] +]</TD>
</TR>

The footer component above is a three column row, with the first two values passed in via @param returned in the rightmost two columns.

Finally, the hash %fdat is a special container provided by Embperl. If a page with embedded Perl is triggered by a form submission -- e.g. the page was specified in the ACTION attribute of a <FORM> tag -- the names and values of the submitted form fields are contained in %fdat. For one thing, a page could conceivably submit a form to itself, if the code for handling the form is embedded into that page. Another nifty fact is that any form fields on the page which contain names represented as keys in %fdat will have their values automatically set to the values contained in %fdat. This isn't as confusing as it sounds -- if a page submits a form to itself, or another page with correctly named fields -- those fields will already be filled out for the user. We'll see one neat use for this feature shortly.

Also, %fdat is a global hash that any code embedded into a single page can see -- so we've also taken to using this hash to store information that is not necessarily form-related but is global in nature (global to that page, at least).

Personalization Methods Part 3, Embperl
The Perl You Need to Know
Cookies from the Oven