ch06_04.htm

用perl编写CGI的好书。本书从解释CGI和底层HTTP协议如何工作开始

<a name="INDEX-1459" />text area tags with Embperl is similar to
outputting these tags with CGI.pm: if you create an element with a
name matching an existing parameter, the value of the parameter is
filled in by default. When an element is created, Embperl checks
whether the name of that element exists within the
<tt class="literal">%fdat</tt> hash (see below); if it does, then its value
is automatically filled in. Also, as HTML elements are generated,
Embperl adds the name-value (if given) to <tt class="literal">%idat</tt>.</p>
</div>
</div>




<a name="ch06-15817" /><div class="sect2">
<h3 class="sect2">6.4.4. Global Variables</h3>


<p>
<a name="INDEX-1460" />
<a name="INDEX-1461" />Embperl
defines a number of <a name="INDEX-1462" /> <a name="INDEX-1,463" /> <a name="INDEX-1,464" />global variables that you can use
within your templates. Here is a list of the primary variables:</p>


<dl>
<dt><b><tt class="literal">%ENV</tt></b></dt>
<dd><p>This should look familiar. Embperl sets your environment variables to
match standard CGI environment variables when running under
<em class="emphasis">mod_perl</em>.</p></dd>


<dt><b><tt class="literal">%fdat</tt></b></dt>
<dd><p>This contains the name and value of all form fields that have been
passed to your CGI script. Embperl, like CGI.pm, does not distinguish
between GET and POST requests and loads parameters from either the
query string or the body of the request as appropriate. If an element
has multiple values, these values are separated by tabs.</p></dd>


<dt><b><tt class="literal">%idat</tt></b></dt>
<dd><p>This contains the name and value of the form fields that have been
created on the current page.</p></dd>


<dt><b><tt class="literal">%mdat</tt></b></dt>
<dd><p>This is only available when running under
<em class="emphasis">mod_perl</em> with the Apache::Session module. You
can use this hash to store anything and it will be available to every
future request for the same page, even if those requests are to
different <tt class="command">httpd</tt> child processes.</p></dd>


<dt><b><tt class="literal">%udat</tt></b></dt>
<dd><p>This is only available when running under
<em class="emphasis">mod_perl</em> with the Apache::Session module. You
can use this hash to store anything and it will be available to any
future request made by the same user. This sends a HTTP cookie to the
user, but no cookies are sent if this hash is not used in your code.
See <a href="ch11_03.htm#ch11-29714">Section 11.3, "Client-Side Cookies"</a>.</p></dd>


<dt><b><tt class="literal">@param</tt></b></dt>
<dd><p>If you use the <em class="emphasis">Execute</em> function to invoke
Embperl pages, the parameters you supply are available to your page
via this variable.</p></dd>

</dl>
</div>




<a name="ch06-20-fm2xml" /><div class="sect2">
<h3 class="sect2">6.4.5. Example</h3>


<p>Let's look at an example of using <a name="INDEX-1465" /> <a name="INDEX-1,466" />Embperl.
For our example, we will create a basic "What's
New" section that displays the headlines of recent stories. If
users click on a headline, they will be able to read the story. This
in itself isn't that impressive, but we will create
administrative pages that make it very simple for someone
administering the site to add, delete, and edit news stories.</p>


<p>There are a total of four pages to our application, the
"What's New" page that displays current headlines;
an article page where users can read a story; a main administrative
page that lists the current headlines and provides buttons for
adding, deleting, and editing stories; and an administrative page
that provides a form for entering a headline and article body, which
is used for both editing existing stories as well as creating new
stories. These pages are shown later in <a href="ch06_04.htm#ch06-31772">Figure 6-3</a>
through <a href="ch06_04.htm#ch06-86259">Figure 6-6</a>.</p>


<a name="ch06-21-fm2xml" /><div class="sect3">
<h3 class="sect3">6.4.5.1. Embperl handler</h3>


<p>Traditional Embperl solutions use
<em class="filename">.epl</em>
<a name="INDEX-1467" />
<a name="INDEX-1468" /> files as the target of our requests.
This example will work either via <em class="emphasis">mod_perl</em> or
<em class="filename">embpcgi.pl</em>.</p>


<p>Let's look at the main "What's New" page
first. The code for <em class="filename">news.epl</em> is shown in <a href="ch06_04.htm#ch06-59372">Example 6-11</a>.</p>



<a name="ch06-59372" /><div class="example">
<h4 class="objtitle">Example 6-11. news.epl </h4>

<blockquote><pre class="code">&lt;HTML&gt;

[!
  use lib "/usr/local/apache/lib-perl";
  use News;
!]
[- @stories = News::get_stories(  ) -]

&lt;HEAD&gt;
  &lt;TITLE&gt;What's New&lt;/TITLE&gt;
&lt;/HEAD&gt;

&lt;BODY BGCOLOR="white"&gt;
&lt;H2&gt;What's New&lt;/H2&gt;

&lt;P&gt;Here's the latest news of all that's happening around here.
  Be sure to check back often to keep up with all the changes!&lt;/P&gt;

&lt;HR&gt;

&lt;UL&gt;
  &lt;LI&gt;
    [- ( $story, $headline, $date ) = @{ $stories[$row] } if $stories[$row] -]
    &lt;A HREF="article.epl?story=[+ $story +]"&gt;[+ $headline +]&lt;/A&gt;
    &lt;I&gt;[+ $date +]&lt;/I&gt;
  &lt;/LI&gt;
&lt;/UL&gt;
  
[$ if ( !@stories ) $]
  &lt;P&gt;Sorry, there aren't any articles available now. Please check
    back later!&lt;/P&gt;
[$ endif $]

&lt;/BODY&gt;
&lt;/HTML&gt;</pre></blockquote>
</div>


<p>The result looks like <a href="ch06_04.htm#ch06-31772">Figure 6-3</a>.</p>


<a name="ch06-31772" /><div class="figure"><img width="473" src="figs/cgi2.0603.gif" height="199" alt="Figure 6-3" /></div><h4 class="objtitle">Figure 6-3. The main "What's New" page presented to users</h4>

<p>Embperl programs are much easier to read and maintain if you reduce
the amount of Perl that is included in the HTML. We do this by moving
much of our code into a common module, News.pm, which we place in
<em class="filename">/usr/local/apache/perl-lib</em>.</p>


<p>We'll look at the News module in a moment, but let's
finish looking at <em class="filename">news.epl</em> first. We call the
News module's <tt class="function">get_stories</tt> function. This
returns an array of stories with each element of the array containing
a reference to an array of the story number, its headline, and the
date it was written.</p>


<p>Thus, within our unordered list later in the file, we loop over each
story using Embperl's special <tt class="literal">$row</tt> variable
and extract these elements of each story to the
<tt class="literal">$story</tt>, <tt class="literal">$headline</tt>, and
<tt class="literal">$date</tt> variables. Embperl will loop and create a
list item until the expression containing <tt class="literal">$row</tt>
evaluates to an undefined value. We then use these variables to build
a link to a story as a list element.</p>


<p>If there are no stories, then we print a message telling the user
this. That's all there is to this file. <a href="ch06_04.htm#ch06-33311">Example 6-12</a> shows a relevant section of the
<a name="INDEX-1469" />News
module.</p>



<a name="ch06-33311" /><div class="example">
<h4 class="objtitle">Example 6-12. News.pm (part 1 of 3) </h4>

<blockquote><pre class="code">#!/usr/bin/perl -wT

package News;
use strict;

use Fcntl qw( :flock );

my $NEWS_DIR = "/usr/local/apache/data/news";

1;


sub get_stories {
    my @stories = (  );
    local( *DIR, *STORY );
    
    opendir DIR, $NEWS_DIR or die "Cannot open $NEWS_DIR: $!";
    while ( defined( my $file = readdir DIR ) ) {
        next if $file =~ /^\./;       # skip . and ..
        open STORY, "$NEWS_DIR/$file" or next;
        flock STORY, LOCK_SH;
        my $headline = &lt;STORY&gt;;
        close STORY;
        chomp $headline;
        push @stories, [ $file, $headline, get_date( $file ) ];
    }
    closedir DIR;
    return sort { $b-&gt;[0] &lt;=&gt; $a-&gt;[0] } @stories;
}


# Returns standard Unix timestamp without the time, just the date
sub get_date {
    my $filename = shift;
    ( my $date = localtime $filename ) =~ s/ +\d+:\d+:\d+/,/;
    return $date;
}</pre></blockquote>
</div>


<p>We store the path to the news directory in
<tt class="literal">$NEWS_DIR</tt>. Note that we use a lexical variable
here instead of a constant because if this script is used with
<em class="emphasis">mod_perl</em>, as is often the case with Embperl,
using constants can generate extra messages in the log file.
We'll discuss why this happens in <a href="ch17_03.htm#ch17-15286">Section 17.3, "mod_perl"</a>.</p>


<p>The format for our article files is rather basic. The first line is
the headline, and all following lines are the body of the article,
which should contain HTML formatting. The files are named according
to the time that they are saved, using the result of Perl's
<tt class="function">time</tt> function -- the number of seconds after
the epoch.</p>


<p>For the sake of this example we will assume that there is only one
administrator who has access to create and edit files. If this were
not the case, we would need to create a more elaborate way to name
the files to prevent two people from creating stories at the same
second. Plus, we would need to create a system to avoid having two
administrators edit the same file at the same time; one way to do
this would be to have the edit page retrieve the current time into a
hidden field when it loads a file for editing, which could then be
compared against the last modification time of the file when the file
is saved. If the file has been modified since it was loaded, a new
form would need to be presented to the administrator showing both
sets of changes so they can be reconciled.</p>


<p>The <tt class="function">get_stories</tt> function opens this news
directory and loops through each file. It skips any files starting
with a dot, including the current and parent directories. If we
encounter any system errors reading directories we die; if we have
problems reading a file, we skip it. Filesystem errors are not
common, but they can happen; if you wish to generate a more friendly
response to the user than a cryptic <em class="emphasis">500 Internet Service
Error</em>, use <a name="INDEX-1470" /> <a name="INDEX-1,471" /> <a name="INDEX-1,472" />
<a name="INDEX-1473" />CGI::Carp with
<em class="emphasis">fatalsToBrowser</em> to catch any
<tt class="function">die</tt> calls.</p>


<p>We get a shared <a name="INDEX-1474" />
<a name="INDEX-1475" />lock
on the file to make sure that we are not reading a file that is in
the process of being written by the administrator. Then we read the
story's headline and add the story's file number,
headline, and date created to our list of stories. The
<tt class="function">get_date</tt> function simply generates a Unix
timestamp from the file number via Perl's
<em class="emphasis">localtime</em> function. That looks like this:</p>


<blockquote><pre class="code">Sun Feb 13 17:35:00 2000</pre></blockquote>


<p>It then replaces the time with a comma in order to get a basic date
that looks like this:</p>


<blockquote><pre class="code">Sun Feb 13, 2000</pre></blockquote>


<p>Finally, we sort the list of stories from largest to smallest
according to the article number. Because this is the same as the date
the file was created, newest headlines will always appear at the
beginning of the list.</p>


<p>When the user selects a headline from the list, the application
fetches the corresponding article. <a href="ch06_04.htm#ch06-87045">Example 6-13</a> shows
the page that displays the articles.</p>



<a name="ch06-87045" /><div class="example">
<h4 class="objtitle">Example 6-13. article.epl </h4>

<blockquote><pre class="code">&lt;HTML&gt;

[!
  use lib "/usr/local/apache/lib-perl";
  use News;
!]
[- ( $headline, $article, $date ) = News::get_story( $fdat{story} ) -]

&lt;HEAD&gt;
  &lt;TITLE&gt;[+ $headline +]&lt;/TITLE&gt;
&lt;/HEAD&gt;

&lt;BODY BGCOLOR="white"&gt;
  &lt;H2&gt;[+ $headline +]&lt;/H2&gt;
  &lt;P&gt;&lt;I&gt;[+ $date +]&lt;/I&gt;&lt;/P&gt;
  [+ local $escmode = 0; $article +]
  
  &lt;HR&gt;
  &lt;P&gt;Return to &lt;A HREF="news.epl"&gt;What's New&lt;/A&gt;.&lt;/P&gt;

&lt;/BODY&gt;
&lt;/HTML&gt;</pre></blockquote>
</div>


<p>The result looks like <a href="ch06_04.htm#ch06-97278">Figure 6-4</a>.</p>


<a name="ch06-97278" /><div class="figure"><img width="473" src="figs/cgi2.0604.gif" height="218" alt="Figure 6-4" /></div><h4 class="objtitle">Figure 6-4. A sample story</h4>

<p>Because most of the work is done by the News module, this file is
also quite simple. The links to this page from the main
"What's New" page include a query string that
specifies the number of the story to view. We use Embperl's
special <tt class="literal">%fdat</tt> hash to retrieve the number of the
story and pass it to the
<em class="emphasis">News</em>::<tt class="function">get_story</tt> function,
which gives us the headline, article contents, and date of the
article.</p>


<p>Then we simply need to include tags for these variables in our
document where we want to display the data.
<tt class="literal">$article</tt> requires some extra consideration. The
body of the article contains HTML, but by default
<a name="INDEX-1476" />
<a name="INDEX-1477" />Embperl escapes any HTML
generated by your Perl blocks, so for example, &lt;P&gt; will be
converted to <tt class="literal">&amp;lt;P&amp;gt;</tt>. In order to
disable this, we set Embperl's special
<tt class="literal">$escmode</tt> variable to <tt class="literal">0</tt>, and
because we provide a <tt class="function">local</tt> scope to the
variable, this change only lasts for the current block and the former
value of <tt class="literal">$escmode</tt> is reset after the article is
output.</p>