<html>
<head>
<title>Apache::ASP::Style guide</title>
<style type="text/css">
<!--
td { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 14px}
font { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 14px}
.title { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 16px}
-->
</style>
</head>
<body bgcolor=black link=#063678 alink=#ff5599 vlink=#993399
marginheight=0 marginwidth=0 leftMargin=0 topMargin=0>
<center>
<table border=0 cellpadding=0 width=99% cellspacing=8>
<tr><td align=center>
<table border=0 cellpadding=3 width=100% cellspacing=0>
<tr bgcolor=#063678>
<td>
<table border=0 cellpadding=1 cellspacing=0 width=100%>
<tr>
<td><img border=0 src=asptitlelogo.gif alt="Apache::ASP" width=267 height=44 ></td>
<td align=right></td>
</tr>
</table>
</td>
</tr>
<tr>
<td bgcolor=#005196 align=center>
<b>
<font color=#ffffff><% Web Applications with Apache & mod_perl %></font>
</b>
</td>
</tr>
</table>
<table border=0 cellpadding=10 cellspacing=0 width=100% bgcolor=#005196>
<tr>
<td valign=top width=120 bgcolor=#005196>
<table cellpadding=5 cellspacing=0 border=1 bgcolor=white><tr><td>
<table border=0 cellpadding=0 cellspacing=0 width=105 bgcolor=white>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="index.html" style="text-decoration:none"><font color=#063678>INTRO</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="install.html" style="text-decoration:none"><font color=#063678>INSTALL</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="config.html" style="text-decoration:none"><font color=#063678>CONFIG</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="syntax.html" style="text-decoration:none"><font color=#063678>SYNTAX</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="events.html" style="text-decoration:none"><font color=#063678>EVENTS</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="objects.html" style="text-decoration:none"><font color=#063678>OBJECTS</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="ssi.html" style="text-decoration:none"><font color=#063678>SSI</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="sessions.html" style="text-decoration:none"><font color=#063678>SESSIONS</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="xml.html" style="text-decoration:none"><font color=#063678>XML/XSLT</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="cgi.html" style="text-decoration:none"><font color=#063678>CGI</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="perlscript.html" style="text-decoration:none"><font color=#063678>PERLSCRIPT</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr>%</nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><font color=#993399>STYLE GUIDE</font></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="faq.html" style="text-decoration:none"><font color=#063678>FAQ</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="tuning.html" style="text-decoration:none"><font color=#063678>TUNING</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="kudos.html" style="text-decoration:none"><font color=#063678>CREDITS</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="support.html" style="text-decoration:none"><font color=#063678>SUPPORT</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="sites.html" style="text-decoration:none"><font color=#063678>SITES USING</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="testimonials.html" style="text-decoration:none"><font color=#063678>TESTIMONIALS</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="resources.html" style="text-decoration:none"><font color=#063678>RESOURCES</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="todo.html" style="text-decoration:none"><font color=#063678>TODO</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="changes.html" style="text-decoration:none"><font color=#063678>CHANGES</font></a></nobr></b></font></td>
</tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="license.html" style="text-decoration:none"><font color=#063678>LICENSE</font></a></nobr></b></font></td>
</tr>
<tr><td colspan=2><hr size=1></td></tr>
<tr>
<td bgcolor=white><font size=-2 face="verdana" color=#993399><b><nobr> </nobr></b></font></td>
<td bgcolor=white ><font face="verdana,helvetica" size=-1><b><nobr><a href="eg/index.html" style="text-decoration:none"><font color=#063678>EXAMPLES</font></a></nobr></b></font></td>
</tr>
</table>
</td></tr>
</table>
<br>
<center>
<a href=http://www.apache-asp.org/><img src="powered_by_apache_asp.jpg" width="88" height="31" alt="Powered by Apache::ASP" border="0"></a>
<br>
<a href=http://perl.apache.org><img src="powered_by_modperl.gif" width="88" height="31" alt="Powered by ModPerl and Apache" border="0"></a>
<br>
<a href=http://www.perl.com><img src="rectangle_power_perl.gif" width="88" height="31" alt="Powered by Perl" border="0"></a>
</center>
</center>
</td>
<td valign=top bgcolor=white>
<font size=+0 face=verdana,arial>
<font face=verdana><font class=title size=+1 color=#555555><b>STYLE GUIDE</b></font>
<font face="courier new" size=3><pre>
</pre></font>Here are some general style guidelines. Treat these as tips for
best practices on Apache::ASP development if you will.</font>
<hr size=1>
<table width=100% border=0 cellpadding=1 cellspacing=3>
<tr>
<td valign=top><font face="lucida console" size=-1>
<tr>
<td valign=top >
<font face="lucida console" size=-1>
<a href=#UseStrict>UseStrict</a>
</font>
</td>
<td valign=top >
<font face="lucida console" size=-1>
<a href=#Use%20global.ae21f52dc>Use global.asa's Script_On* Events</a>
</font>
</td>
</tr>
<tr>
<td valign=top >
<font face="lucida console" size=-1>
<a href=#Do%20not%20definc430b103>Do not define subroutines in scripts.</a>
</font>
</td>
<td> </td>
</tr>
</table>
<hr size=1>
<p>
<p>
<a name=UseStrict></a>
<font face=verdana><font class=title size=+0 color=#555555><b>UseStrict</b></font>
<font face="courier new" size=3><pre>
</pre></font>One of perl's blessings is also its bane, variables do not need to be
declared, and are by default globally scoped. The problem with this in
<a href=http://perl.apache.org><font size=-1 face=verdana><b>mod_perl</b></font></a> is that global variables persist from one request to another
even if a different web browser is viewing a page.
<font face="courier new" size=3><pre>
</pre></font>To avoid this problem, perl programmers have often been advised to
add to the top of their perl scripts:
<font face="courier new" size=3><pre>
use strict;
</pre></font>In Apache::ASP, you can do this better by setting:
<font face="courier new" size=3><pre>
PerlSetVar UseStrict 1
</pre></font>which will cover both script & global.asa compilation and will catch
"use strict" errors correctly. For perl modules, please continue to
add "use strict" to the top of them.
<font face="courier new" size=3><pre>
</pre></font>Because its so essential in catching hard to find errors, this
configuration will likely become the default in some future release.
For now, keep setting it.</font>
<p>
<a name=Do%20not%20definc430b103></a>
<font face=verdana><font class=title size=+0 color=#555555><b>Do not define subroutines in scripts.</b></font>
<font face="courier new" size=3><pre>
</pre></font>DO NOT add subroutine declarations in scripts. Apache::ASP is optimized
by compiling a script into a subroutine for faster future invocation.
Adding a subroutine definition to a script then looks like this to
the compiler:
<font face="courier new" size=3><pre>
sub page_script_sub {
...
... some HTML ...
...
sub your_sub {
...
}
...
}
</pre></font>The biggest problem with subroutines defined in subroutines is the
side effect of creating closures, which will not behave as usually
desired in a <a href=http://perl.apache.org><font size=-1 face=verdana><b>mod_perl</b></font></a> environment. To understand more about closures,
please read up on them & "Nested Subroutines" at:
<font face="courier new" size=3><pre>
<a href=http://perl.apache.org/docs/general/perl_reference/perl_reference.html>http://perl.apache.org/docs/general/perl_reference/perl_reference.html</a>
</pre></font>Instead of defining subroutines in scripts, you may add them to your sites
global.asa, or you may create a perl package or module to share
with your scripts. For more on perl objects & modules, please see:
<font face="courier new" size=3><pre>
<a href=http://www.perldoc.com/perl5.8.0/pod/perlobj.html>http://www.perldoc.com/perl5.8.0/pod/perlobj.html</a>
</pre></font>
<p>
<a name=Use%20global.ae21f52dc></a>
<font face=verdana><font class=title size=+0 color=#555555><b>Use global.asa's Script_On* Events</b></font>
<font face="courier new" size=3><pre>
</pre></font>Chances are that you will find yourself doing the same thing repeatedly
in each of your web application's scripts. You can use Script_OnStart
and Script_OnEnd to automate these routine tasks. These events are
called before and after each script request.
<font face="courier new" size=3><pre>
</pre></font>For example, let's say you have a header & footer you would like to
include in the output of every page, then you might:
<font face="courier new" size=3><pre>
# global.asa
sub Script_OnStart {
$Response->Include('header.inc');
}
sub Script_OnEnd {
$Response->Include('footer.inc');
}
</pre></font>Or let's say you want to initialize a global database connection
for use in your scripts:
<font face="courier new" size=3><pre>
# global.asa
use Apache::DBI; # automatic persistent database connections
use DBI;
use vars qw($dbh); # declare global $dbh
sub Script_OnStart {
# initialize $dbh
$dbh = DBI->connect(...);
# force you to explicitly commit when you want to save data
$Server->RegisterCleanup(sub { $dbh->rollback; });
}
sub Script_OnEnd {
# not really necessary when using persistent connections, but
# will free this one object reference at least
$dbh = undef;
}
</pre></font>
</font>
</td>
<td bgcolor=white valign=top>
</td>
</tr>
<tr bgcolor=#063678>
<td colspan=3 align=center width=80%>
<font face=verdana color=white size=-1>
Copyright © 1998-2008,
<a href=http://www.chamas.com><font color=white>Chamas Enterprises Inc.</font></a>
</font>
</td>
</tr>
</table>
</td></tr>
</table>
</center>
</body>
</html>