11.9 What We Didn t Talk About

11.9 What We Didn't Talk About

As with many of the other topics in this book, we could write another volume describing all the features of Mason; we have only scratched the surface here (the 80/20 rule). Although it's not essential, you may want to explore the following topics as you learn more about how you can develop web sites with Mason.

11.9.1 Tags for Initialization and Cleanup

Mason provides tags that contain blocks of Perl code to be executed at specific times. For details, see www.masonhq.com/docs/manual/ Devel .html#initialization_and_cleanup.

The <%cleanup> Tag

The <%cleanup> ... </%cleanup> tag defines a block of code that is executed just before the component exits. For example:

 <%cleanup>  $dbh->disconnect();  </%cleanup> 

This is equivalent to having a <%perl> ... </%perl> tag at the end of the file.

The <%shared> Tag

The <%shared> ... </%shared> tag is similar to <%once> in that all variables declared within it can be seen in the entire component, but <%shared> , unlike <%once> , is executed for each request.

11.9.2 Session Handling

The hash %session is a global variable that can contain the session information for the current user . If you assign a value to %session , asession is created for this user (the Apache::Session module must be installed for this to work).

A session ID is a commonly used value placed in the %session hash and then accessed on the user's next visit. You can ensure that the user has a session ID with code like this:

 unless ($session{session_id}) {      $session{session_id} = generate_new_session_id();  } 

11.9.3 Request API

Mason provides an extensive API for the Mason Request object. This API allows you to access and change cache information, examine the component call stack, call components directly (for example, $m->comp() ), use the long version of the <& ... &> , and much more. For details, www.masonhq.com/docs/manual/Request.html.

11.9.4 Component Class API

Mason provides methods to examine and report on the components that are used in the generation of the web page. See www.masonhq.com/docs/manual/Component.html for details.

11.9.5 Top-Level Components

Mason has a feature that enables a web page to be created even though the requested page, or even the directory, does not exist. In other words, let's say the user requests www.example.com/ reports /2002/March/ . Under normal conditions, Apache would serve up the file index.html under the directory reports/2002/March/ . However, in this example, the directory 2002 doesn't exist. Moreover, neither does March . So, what happens?

Mason, properly configured, searches for the index.html and if it is not found, it then begins to search for dhandlers, or default handles, in the desired directory and up the directory tree. For instance, with the preceding request, Mason looks for, in order, the following:

 /reports/2002/March/index.html  /reports/2002/dhandler  /reports/dhandler  /dhandler 

The first file found is the one used. Let's say that the files /reports/2002/March/index.html and /reports/2002/dhandler are not found, and the first file found is /reports/dhandler . That file is used to generate the HTML. Its contents could be this:

 <& _header &>  <h1>Report for <% $month %>, <% $year %></h1>  <% $report_contents %>  <& _footer &>  <%init>  # get the path, or the stuff asked for  my $arg = $m->dhandler_arg;  # split on the /, getting the year and the month  my($year,$month) = split("/",$arg); # split out pieces  # do whatever is necessary to get the report content,  # perhaps reading from a database, assign it to $report_contents  my $report_contents = All the good content of the report;  </%init> 

The <%init> section, the first code executed, grabs the contents of the path below /reports/ ”in this case, 2002/March . This text is stored in $arg , which is then split on the slash and stored in $year and $month . Then, by some means (perhaps a database is queried or a text file is read), the contents of the March 2002 report are read and stored in $report_contents .

Then, at the top of the file, we call the _header component to build the header; then we create an <h1> tag with the month and year in question. The contents of the report are included with <% $report_contents %> , followed by the _footer component.

As this example shows, depending on the report contents read, we can have the same default handler take care of all the following URLs and then some:

 http://www.example.com/reports/2002/March/  http://www.example.com/reports/2002/February/  http://www.example.com/reports/2002/January/  http://www.example.com/reports/2001/December/  http://www.example.com/reports/2001/November/ 

Formore information on default handlers, see the Mason documents at www.masonhq.com/docs/manual/Bevel.html/top_level_components.