head	1.5;
access;
symbols
	TIGRIS_1_1_0RC2:1.5
	TIGRIS_1_1_0RC1:1.5
	TIGRIS_1_1:1.5.0.4
	TIGRIS_1_0_8:1.5
	TIGRIS_1_0_8RC3:1.5
	TIGRIS_1_0_8RC2:1.5
	TIGRIS_1_0_8RC1:1.5
	TIGRIS_1_0_7:1.5
	TIGRIS_1_0_7RC3:1.5
	TIGRIS_1_0_7RC2:1.5
	TIGRIS_1_0_7RC1:1.5
	TIGRIS_1_0_6:1.5
	TIGRIS_1_0_6RC5:1.5
	TIGRIS_1_0_6RC4:1.5
	TIGRIS_1_0_6RC3:1.5
	TIGRIS_1_0_6RC2:1.5
	TIGRIS_1_0_6RC1:1.5
	TIGRIS_1_0_5:1.5
	TIGRIS_1_0_5RC6:1.5
	TIGRIS_1_0_5RC5:1.5
	TIGRIS_1_0_5RC4:1.5
	TIGRIS_1_0_5RC3:1.5
	TIGRIS_1_0_5RC2:1.5
	TIGRIS_1_0_5RC1:1.5
	TIGRIS_1_0_4:1.5
	TIGRIS_1_0_3:1.5
	TIGRIS_1_0_2:1.5
	TIGRIS_1_0_1:1.5
	TIGRIS_1_0:1.5.0.6
	TIGRIS_1_0_0:1.5
	TIGRIS_1_0_0_RC1:1.5.0.2;
locks; strict;
comment	@# @;


1.5
date	2001.03.13.02.09.08;	author dlr;	state Exp;
branches;
next	1.4;

1.4
date	2001.03.09.20.25.23;	author dlr;	state Exp;
branches;
next	1.3;

1.3
date	2001.03.09.20.16.59;	author dlr;	state Exp;
branches;
next	1.2;

1.2
date	2001.03.09.19.27.35;	author leonardr;	state Exp;
branches;
next	1.1;

1.1
date	2001.03.09.19.18.03;	author leonardr;	state Exp;
branches;
next	;


desc
@@


1.5
log
@Added Don Dayley's suggested link to the (now out of date) pagination HOWTO.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
 <head>
  <title>Field Guide to HelmServlet</title>
 </head>

<body>
<h1>Field Guide to HelmServlet</h1>

<p>Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
March 9, 2001<br>
<small>$Id: fieldguide-HelmServlet.html,v 1.4 2001/03/09 20:25:23 dlr Exp $</small>

<h2>Introduction</h2>

<p>Almost every servlet in Helm subclasses <a href="http://helm.tigris.org/nonav/apidocs/org/tigris/helm/security/HelmServlet.html">HelmServlet</a>.
HelmServlet does a lot of work for you by turning the <code>HTTP</code>
request into <code>WebContext</code> entries which a template can
use. In fact, HelmServlet does so much of the basic work that servlets
which are only used to display information (even complicated ones like
<cod>ProjectHome</code>) do not have to have any associated Java code
at all.

<p>Since no one likes to reinvent the wheel, you should read through
this document before writing your own Helm servlet. Also, I should
mention that there are many useful utility methods in Joist's
<code>UnsecureServlet</code> (<code>HelmServlet</code>'s superclass),
for which there is not yet a field guide. I'll mention one such method
really quickly in this space, though: <code>getAction(WebContext)</code>.

<h2>ProcessRequest Flow of Execution</h2>

<p>What follows is a summary of the flow of execution through
<code>HelmServlet.processRequest</code>. Objects placed into the
context are noted in lists, with the context key in boldface.

<ol>

<p><li>Logging in

<p>If the user is not logged in and your sandbox has
<code>ALLOW_GUESTS</code> set to true, the user is automatically
logged in as the guest user. If <code>ALLOW_GUESTS</code> is
<code>false</code> and the user are not logged in, the user is
redirected to the login screen.

<ul>
 <li><b>isLoggedIn</b> - A boolean value which is true if the user is
                         logged in (as themselves or as the guest
                         user).
</ul>

<p><li>Initial context population

<p>Every servlet you write will always have the following objects
avaliable to the template:

<ul>
 <li><b>host</b> - A <code>Host</code> object representing the
     host the request was made of. Few servlets need to make use of
     this. Access it in <code>HelmServlet</code> subclasses with
     <code>getHost(context)</code>.

 <li><b>domain</b> - A <code>Domain</code> object representing the domain which
     received the HTTP request (eg. domain.org). In
     <a href="http://www.tigris.org/">Tigris</a> 1.0 there can only be
     one <code>Domain</code> on an installation. Access it with
     <code>getCurrentDomain(context)</code>.
  
 <li><b>currentProject</b> - A <code>Project</code> object
     representing the project requested in the HTTP request; obtained
     from the hostname (project.domain.org), or, if vhosting is turned
     off, from the query string (projectID=#). If no project or a
     nonexistant project is specified, <code>HelmServlet</code> uses
     the <code>www</code> project (this default is specified in
     <code>ProjectPeer</code>). In <code>HelmServlet</code> subclasses,
     access this object with <code>getCurrentProject(context)</code>.

 <li><b>loginUser</b> - A <code>User</code> object representing the user who 
     is logged in. This may be the guest user.

 <li><b>acl</b> - The <code>AccessControlList</code> object for the logged-in
     user. You'll use this a lot to do permission checking.

</ul>

<p><li>Redirection to compulsory click-through

<p>If the zone.properties for the installation specifies a value for
"clickThroughPermission", then that permission is checked for (if it
is blank, then this entire step is skipped). If the permission check
fails, the user is redirected to a servlet which will give them a role
with that permission, once they read and agree to some
installation-specific boilerplate.

<p><li>Base permission checking

<p>For most servlets, there is a permission which the user must have
in order to see the servlet's template at all. Rather than place this
code in every servlet, the neccessary permission is placed into the
servlet's .properties file, and is loaded at this point and checked
against <b>loginUser</b>'s ACL. If the check fails, the user is
redirected to a "permission denied" screen.

<p><li>Pagination-related context population

<p>Templates may call methods which return
<a href="/docs/pagination-HOWTO.html">paginatable lists</a>. In
addition to whatever other arguments they take, such methods will want
these three arguments:

<ul>
 <li><b>itemsPerPage</b> - A servlet-specific value which determines
                           how many items should be on a
                           page. Defaults to 20.
 
 <li><b>paginated_page</b> - The number of the page to
                             display. Defaults to 1.

 <li><b>filter</b> - A Criteria object representing the filter applied
                     to the list by the user.
</ul>

<p><li>Business object context population

<p>An HTTP request for your servlet may include in its query string
IDs for the specific business objects the user wants your servlet to
manipulate or display. For instance, AuditLogEntryView takes in the
query string the ID of the specific log entry to view. These IDs take
the form "[business object]ID", eg. "auditLogEntryID". You can obtain
these objects from your servlet using a method called
getCurrent[business object](context),
eg. "getCurrentAuditLogEntry(context)", or access them from within a
template as $current[business object], eg. $currentAuditLogEntry.

<p>Variables which might be populated in this way are:

<ul>
 <li><b>currentUser</b> - Not to be confused with <b>loginUser</b>,
                          this is the user who is being viewed,
                          edited, or otherwise dealt with by the
                          servlet. If no userID is specified in the
                          HTTP request, this variable defaults to the
                          same user as <b>loginUser</b>.
 <li><b>currentUserGroup</b>
 <li><b>currentProjectGroup</b>
 <li><b>currentRole</b>
 <li><b>currentResource</b>
 <li><b>currentAuditLogEntry</b>
</ul>

<p><li>Last-minute context population

<p>Finally, some miscellaneous values are inserted into the
context. They values are used by the frame templates which include
your servlet-specific template; you shouldn't have to use them
directly

<ul>
 <li><b>pageTitle</b> - The title of the servlet, as specified in its
                        .properties file.

 <li><b>servletHelp</b> - A ServletHelp object used to provide
                          context-sensitive help.

 <li><b>currentDate</b> - A Date object representing the date and time
                          immediately before processing of the template
                          began.
</ul>

</body>
</html>@


1.4
log
@Added CODE tags to format the description of the stuff added to the
context.
@
text
@d12 1
a12 1
<small>$Id: fieldguide-HelmServlet.html,v 1.3 2001/03/09 20:16:59 dlr Exp $</small>
d107 2
a108 1
<p>Templates may call methods which return paginatable lists. In
@


1.3
log
@Added some style an links to the first couple paragraphs.
@
text
@d12 1
a12 1
<small>$Id: fieldguide-HelmServlet.html,v 1.2 2001/03/09 19:27:35 leonardr Exp $</small>
d41 5
a45 4
<p>If the user is not logged in and your sandbox has ALLOW_GUESTS set to
true, the user is automatically logged in as the guest user. If
<code>ALLOW_GUESTS</code> is <code>false</code> and the user are not
logged in, the user is redirected to the login screen.
d59 10
a68 9
 <li><b>host</b> - An object representing the host. Few servlets need
                   to make use of this. Access it in HelmServlet
                   subclasses with getHost(context).

 <li><b>domain</b> - A Domain object representing the domain which
                     received the HTTP request (eg. domain.org). In
                     Tigris 1.0 there can only be one domain on an
                     installation. Access it with
                     getCurrentDomain(context).
d70 14
a83 17
 <li><b>currentProject</b> - A Project object representing the project
                             requested in the HTTP request; obtained
                             from the hostname (project.domain.org),
                             or, if vhosting is turned off, from the
                             query string (projectID=#). If no project
                             or a nonexistant project is specified,
                             HelmServlet uses the "www" project (this
                             default is specified in ProjectPeer). In
                             HelmServlet subclasses, access this
                             object with getCurrentProject(context).

 <li><b>loginUser</b> - A User object representing the user who is logged
     in. This may be the guest user.

 <li><b>acl</b> - The AccessControlList object for the logged-in
                  user. You'll use this a lot to do permission
                  checking.
@


1.2
log
@Corrected capitalization and typos.
@
text
@d12 1
a12 1
<small>$Id: fieldguide-HelmServlet.html,v 1.1 2001/03/09 19:18:03 leonardr Exp $</small>
d16 7
a22 6
<p>Almost every servlet in Helm subclasses HelmServlet. HelmServlet
does a lot of work for you in turning the HTTP request into a
WebContext which a template can use. In fact, HelmServlet does so much
of the basic work that servlets which are only used to display
information (even complicated ones like ProjectHome) do not have to
have any associated Java code at all.
d27 3
a29 3
UnsecureServlet (HelmServlet's superclass), for which there is not yet
a field guide. I'll mention one such method really quickly in this
space, though: getAction.
d34 2
a35 2
HelmServlet.processRequest. Objects placed into the context are noted
in lists, with the context key in boldface.
d43 2
a44 2
ALLOW_GUESTS is false and the user are not logged in, the user is
redirected to the login screen.
@


1.1
log
@New doc.
@
text
@d12 1
a12 1
<small>$Id: helmservlet.html,v 1.1 2001/02/21 01:56:43 leonardr Exp $</small>
d87 1
a87 1
<p><li>Compulsory Click-through Redirection
d96 1
a96 1
<p><li>Base Permission Checking
d105 1
a105 1
<p><li>Pagination-related population
d166 1
a166 1
                          immediately before processing of the tempate
@

