<html>
<head><title>Apache::ASP Site Building</title></head>
<bgcolor=white>
<h2>Apache::ASP Site Building</h2>
<h3>By: Joshua Chamas</h3>
<i>published originally in PerlMonth.com in 1999</i>
<p>
Last month,
I gave a rough introduction of <a href=http://www.apache-asp.org/>Apache::ASP</a>,
and why you might want to use it to build your web site.
Now I get to show you Apache::ASP in action.
<h3>Requirements</h3>
First, we must decide what our site will do, or
state its requirements. As a trivial site,
we are going do build something my.*.com style, which
holds a user's favorite links, a MyBookmarks site
if you will.
<p>
This site will require a user to login
with a chosen user name for security,
and view, add, and delete their internet bookmarks.
The deletion will leave the deleted bookmark data in the form to allow
easy modification and recreation of that bookmark.
<p>
The user will also be able to logout, and the system
will auto-logout their account automatically after
15 minutes, so that if it is a public terminal, another user using the
same browser later will not be able modify the
first user's bookmarks.
<p>
<h3>Specification</h3>
Often times, there is a specification round that we
must do to pick our web application environment and
hardware, as well as supported client software, but this is a no
brainer here. We are choosing Apache::ASP because of its built
in <tt>$Session</tt> which make user logins easy, and its built
in event <tt>Session_OnEnd</tt> which will automatically destroy
the contents of <tt>$Session</tt> every <tt>SessionTimeout</tt>, which
defaults to 20 minutes.
<p>
Also, because our web application has more than one page, we
will make use of the same headers and footers for each
page, using the includes <tt><!--#include file=src.inc--></tt>
functionality to modularize the html.
<h3>Design</h3>
Before we start coding, let's take a minute to diagram
what pages and actions our MyBookmarks web application
needs to have. We have 2 pages, the intro, and the
actual bookmarks page, where we get to view, add, and
delete the bookmark entries. We have the user login to
the bookmarks, and logout, securing access for the user's
eyes only.
<p>
<center><img src=flow.gif border=0></center>
<p>
You might also design the objects, methods, and functions
that will be used for the site, but this site is so
simple, that we are going to jump into implementation.
<h3>Implementation</h3>
We start by configuring <tt>.htaccess</tt> file
of a directory in apache to allow Apache::ASP
to run <tt>.asp</tt> files, and testing the configuration
with a <tt>dummy.asp</tt> file.
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># .htaccess</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt>DirectoryIndex index.asp
<Files ~ \.asp$>
SetHandler perl-script
PerlHandler Apache::ASP
PerlSetVar Global .
PerlSetVar GlobalPackage My::Bookmarks
PerlSetVar StateDir /tmp/asp_apps_bookmarks
PerlSetVar Debug 2
PerlSetVar SessionTimeout 15
PerlSetVar StatScripts 1
PerlSetVar AllowApplicationState 1
PerlSetVar AllowSessionState 1
</Files></tt></pre></td></tr>
</table>
</center>
<p>
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># dummy.asp</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt>INTRO <%=$Session%></tt></pre></td></tr>
</table>
</center>
<p>
If the index.asp works on your server, and just prints
<tt>INTRO Apache::ASP::Session=HASH(0x??????)</tt>,
then we know Apache::ASP is working and $Sessions are
enabled.
<hr size=1>
Next, we set up the <tt>global.asa</tt> with globals and
libraries that need to be initialized for the web
application, and define the relevant event handlers.
We also set up per request globals, like the document's
title, which is something that we can do in
<tt>Script_OnStart</tt>. Finally, we use
the <tt>Script_OnStart</tt> and <tt>Script_OnEnd</tt>
events to automatically include the header and footer
for each script in our web application, and initialize
relevant globals used by the scripts.
<p>
Notice that each script can process its own <tt>Logout</tt>
request, which was a decision made after the design
because it seemed good to make the first script, <tt>index.asp</tt>,
<tt>$Session</tt> aware.
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># global.asa</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt>use File::Basename;
use DBI;
use DBD::CSV;
use vars qw( $DarkColor $Name %Titles $FontBase $Db $Title $Basename $Form $Query );
$DarkColor = '#0000aa';
$Name = "MyBookmarks";
%Titles = (
'index.asp' => 'Introduction',
'bookmarks.asp' => 'Viewer'
);
$FontBase = 'face=verdana,arial';
$Db = DBI->connect("DBI:CSV:f_dir=".Apache->dir_config('StateDir'), '', '',
{ RaiseError => 1 })
or die "Cannot connect: " . $DBI::errstr;
# setup bookmark database if first time
unless(eval { $Db->do("select bookmark_id,username,title,url from bookmarks") }) {
eval { $Db->do("drop table bookmarks"); };
$Db->do(<<CREATE) || die("can't create table $DBI::errstr");
create table bookmarks (
bookmark_id varchar(15),
username varchar(30),
title varchar(60),
url varchar(120)
)
CREATE
;
}
$Db->do("select * from bookmarks")
|| die("can't do select against bookmarks: $DBI::errstr");
sub Script_OnStart {
$Basename = basename($0);
$Title = $Name.' / '.$Titles{$Basename};
$Response->Include('header.inc');
$Form = $Request->Form();
$Query = $Request->QueryString();
$Response->Expires(0);
# a user may logout from any script, destroy session, and go
# to login / intro page
if($Form->{logout}) {
$Session->Abandon();
$Response->Redirect("index.asp?abandon=".
++$Application->{abandon});
}
}
sub Script_OnEnd {
$Response->Include('footer.inc');
}
sub Application_OnStart {
# use max_bookmark_id as a pseudo sequence
$Application->Lock();
my $sth = $Db->prepare_cached
("select bookmark_id from bookmarks order by bookmark_id desc");
$sth->execute();
$Application->{max_bookmark_id} = $sth->fetchrow_array();
$Application->UnLock();
}</tt></pre></td></tr>
</table>
</center>
<p>
<hr size=1>
Next we set up the headers and footers for each page.
One problem with <tt>HTML</tt> is that it requires you to specify
the unique titles of the document before the standard
body style for your site, so we cheated this and
created the per page titles already in the <tt>Script_OnStart</tt>
of the <tt>global.asa</tt>.
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># header.inc</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt><html>
<head><title><%=$Title%></title></head>
<body bgcolor=white link=purple alink=yellow vlink=gray>
<form src=<%=$Basename%> method=POST>
<table border=0 width=100% cellpadding=5 cellspacing=0>
<tr bgcolor=<%= $DarkColor %>>
<td>
<b><font <%=$FontBase%> size=+1 color=yellow>
<%=$Title%>
<% if($Session->{user}) { %>
for <%= $Session->{user} %>
<% } %>
</font></b>
</td>
<td align=right>
<font <%=$FontBase%>>
<% if($Session->{'user'}) { %>
<input type=submit name=logout value=Logout>
<% } else { %>
&nbsp;
<% } %>
</font>
</td>
</tr>
</form>
</table>
<table border=0 cellpadding=5 width=100% ><tr><td valign=top>
<font <%=$FontBase%> size=+0></tt></pre></td></tr>
</table>
</center>
<p>
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># footer.inc</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt></font>
</table>
<table border=0 width=100% cellpadding=5>
<tr>
<td bgcolor=yellow align=center>
<font <%=$FontBase%> size=-1 color=<%= $DarkColor %>>
<b>
My-NotExists-Bookmarks
Cool Technologies Etc., ???, &copy; <%= (localtime())[5] + 1900 %>
</b>
</font>
</td>
</tr>
</table>
</body>
</html></tt></pre></td></tr>
</table>
</center>
<p>
<hr size=1>
Doing the intro page should now be fairly easy. We
will handle the login at the intro page, and redirect
to the viewer upon success. We keep the login
processing perl code at the top so we don't print
out any <tt>HTML</tt> before the redirect is handled.
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># index.asp</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt><%
# process user login
my $error;
my $user = $Form->{'user'};
if(defined $user) {
$user =~ /^\w+$/ or $error =
"Your username must made of only letter and numbers";
length($user) > 3 or $error =
"Your username much be at least 4 character long";
unless($error) {
$Session->{user} = $user;
$Response->Redirect('bookmarks.asp');
}
}
$user ||= $Session->{user};
%>
Hello, and welcome to the MyBookmarks Apache::ASP demo application.
To begin your bookmark experience, please login now:
<center>
<% if($error) { %>
<p><b><font color=red size=-1>* <%=$error%></font></b>
<% } %>
<form src=<%=$Basename%> method=POST>
<input type=text name=user value="<%=$Server->HTMLEncode($user)%>">
<input type=submit value=Login>
</form>
</center>
This demo makes use of the Apache::ASP objects, especially
<tt>$Session</tt> and <tt>$Response</tt>, modularizes html
via SSI file includes, and uses the <tt>Script_OnStart</tt>
and <tt>Script_OnEnd</tt> event hooks to
simplify common tasks done for each script in this web
application.</tt></pre></td></tr>
</table>
</center>
<p>
<hr size=1>
The final script for the site is the <tt>bookmarks.asp</tt>
script, which is the most complex of the bunch. This
script is in charge of viewing, adding, and deleting
the user bookmarks. In order to do the bookmark
modifications, the script processes its own form input.
<p>
<center>
<table border=0 cellspacing=0 width=90% >
<tr bgcolor=gray><td><font color=white><b># bookmarks.asp</b></td></tr>
<tr bgcolor=#c0c0c0><td><pre>
<tt><%
# only a logged in user may view the bookmarks
$Session->{'user'} || $Response->Redirect('index.asp');
my $error;
if($Form->{submit} =~ /create/i) {
unless($Form->{new_url}) {
$error = "The Url must be ".
"filled in to create a new bookmark";
goto ERROR;
}
my $sth = $Db->prepare_cached(
"select url from bookmarks where username=? and url=?"
);
$sth->execute($Session->{'user'}, $Form->{new_url});
if($sth->fetchrow_array) {
$error = "You already have $Form->{new_url} ".
"for a bookmark";
goto ERROR;
} else {
$sth = $Db->prepare_cached(<<SQL);
insert into bookmarks (bookmark_id, username, url, title)
values (?,?,?,?)
SQL
;
$Application->Lock();
$sth->execute(
++$Application->{max_bookmark_id},
$Session->{'user'},
$Form->{new_url},
$Form->{new_title}
);
$Application->UnLock();
}
}
if($Query->{delete}) {
my $sth = $Db->prepare_cached(<<SQL);
select * from bookmarks
where bookmark_id = ?
and username = ?
SQL
;
$sth->execute($Query->{delete}, $Session->{user});
if(my $data = $sth->fetchrow_hashref) {
my $sth = $Db->prepare_cached(<<SQL);
delete from bookmarks
where bookmark_id = ?
and username = ?
SQL
;
$sth->execute($Query->{delete}, $Session->{user});
$Form->{new_url} = $data->{'url'};
$Form->{new_title} = $data->{'title'};
}
}
# get all the bookmarks
ERROR:
my $sth = $Db->prepare_cached(
"select * from bookmarks where username=? ".
"order by bookmark_id"
);
$sth->execute($Session->{'user'});
my @bookmarks;
while(my $bookmark = $sth->fetchrow_hashref()) {
push(@bookmarks, $bookmark);
}
%>
<% if(@bookmarks) { %>
Welcome to your bookmarks!
<% } else { %>
You don't have any bookmarks. Please feel free to
add some using the below form.
<% } %>
<center>
<% if($error) { %>
<p><b><font color=red size=-1>* <%=$error%></font></b>
<% } %>
<form src=<%=$Basename%> method=POST>
<table border=0>
<% for ('new_url', 'new_title') {
my $name = $_;
my $title = join(' ',
map { ucfirst $_ } split(/_/, $name));
%>
<tr>
<td><b><%=$title%>:</b></td>
<td><input type=text name=<%=$name%>
value="<%=$Form->{$name}%>"
size=40 maxlength=120>
</td>
</tr>
<% } %>
<tr>
<td>&nbsp;</td>
<td>
<font <%=$FontBase%>>
<input type=submit name=submit
value="Create Bookmark"></td></tr>
</font>
</td>
</form>
</table>
<% if(@bookmarks) {
my $half_index = int((@bookmarks+1)/2);
%>
<p>
<table border=0 width=80% bgcolor=<%= $DarkColor %> cellspacing=0>
<tr><td align=center>
<table border=0 width=100% cellspacing=1 cellpadding=3>
<tr bgcolor=<%= $DarkColor %>><td align=center colspan=4>
<font color=yellow><b>Bookmarks</b></font>
</td></tr>
<% for(my $i=0; $i<$half_index; $i++) { %>
<tr>
<% for($i, $i+$half_index) {
my $data = ($_ < @bookmarks) ?
$bookmarks[$_] : undef;
$data->{title} ||= $data->{'url'};
my $text = $data->{bookmark_id} ?
"<a href=$data->{'url'}
>$data->{'title'}</a>"
: "&nbsp;";
%>
<td bgcolor=#c0c0c0 width=30 align=center>
<% if($data->{bookmark_id}) { %>
<font size=-1><tt>
<a href=<%=
"$Basename?delete=$data->{bookmark_id}"
%>>[DEL]</a>
</tt></font>
<% } else { %>
&nbsp;
<% } %>
</td>
<td bgcolor=white><%= $text || '&nbsp;'%></td>
<% } %>
</tr>
<% } %>
</table>
</td></tr></table>
<br>
<% } %>
</center></tt></pre></td></tr>
</table>
</center>
<p>
<hr size=1>
That's it :) If you would like you may
view the <a href=http://www.apache-asp.org/apps/bookmarks/>
MyBookmarks web application online</a>.
Next month, we will tune the MyBookmarks web application
for maximum throughput, and minimum RAM usage.
<br>
<br>