Beginning Perl Web Development - From Novice To Professional (2006)
.pdf
270 C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N
Figure 13-2. The output from the <blink> tag example
As with any terse example of this nature, it only serves to show that your Mason installation is working and not much else. In addition, there are multiple ways to create the output shown in Figure 13-2. I chose one of the more verbose ways to do it, since it provides a good transition into some of the less verbose methods shown later in this section.
In this section, we’ll start off by examining components, and then we’ll move on to look at request objects, handlers, and subrequests.
Components
As mentioned previously, central to working with Mason is the component object. The Mason Developer’s Manual describes a component as “a mix of Perl and HTML” and the “basic building block and computational unit.” A component can be a portion of a page that contains Mason sections, or it can be an entire page, or it can be anything in between. Components can call other components, passing information between them and the current request.
The example shown in Listing 13-1 is itself a component. A slightly more complex example is shown in Listing 13-2.
Listing 13-2. A Slightly More Complex Mason Example
% my $time = time;
The time is <% $time %>, thanks for visiting.
The results of this example appear in Figure 13-3.
C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N |
271 |
Figure 13-3. The output from Listing 13-2, which uses a slightly more complex Mason example to process a variable
As you can see from Listing 13-2 and Figure 13-3, the variable $time is substituted at the time the template is processed. Using the browser’s Reload function shows that the time keeps changing on every refresh, unless of course you reload more than once in a second.
In Listing 13-2, you also saw another type of syntax, a single percent sign (%). A % is used to indicate a single line of Perl code within a Masonized page. We’ll cover the syntax of components in more detail in the next section, and then we’ll move on to look at the arguments of components as well as return values.
Syntax
The syntax of components is fairly simple when you consider how powerful they are. Blocks of code to be processed are indicated by a few types of delimiters, as you saw in the examples in Listings 13-1 and 13-2. Items within <%perl> and </%perl> are evaluated as blocks of Perl. This syntax is usually used when multiple lines of Perl are necessary. Items within <% and %> are evaluated as single expressions. This syntax is frequently used for interpolation of variables or single statements interspersed within the text of the web page. Finally, % is used to indicate a single line of Perl code on a page. This syntax is frequently used with conditionals and loops. Consider the example in Listing 13-3.
Listing 13-3. A Conditional Within a Mason Page
%my $name = "Steve"; Welcome to the page,
%if ($name eq "Steve") {
thank you for visiting again <% $name %>.
272 C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N
% } else {
it is nice of you to visit. % }
The output from this example is shown in Figure 13-4.
Figure 13-4. An example using a conditional
Since the variable was predefined as "Steve" in the example, the conditional in the if() statement matched. If the value of the $name variable is changed, then the else will take effect. Consider the modified code in Listing 13-4.
Listing 13-4. A Slightly Modified Conditional Within a Mason Page
%my $name = "sssSteve"; Welcome to the page,
%if ($name eq "Steve") {
thank you for visiting again <% $name %>. % } else {
it is nice of you to visit. % }
The result of this code is shown in Figure 13-5.
C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N |
273 |
Figure 13-5. The modified conditional code in action
In practice, I use either <% and %> or a single % on each line of code when I have just a few lines to process. I find it easier to type % on each line rather than the more formal <%perl> and </%perl>, unless there’s another reason for using <%perl>, an example of which you’ll see later.
Four additional types of tags are used rather frequently with Mason. These types include <& and &> to indicate another component call. Consider this akin to a function call; arguments can be carried with the call. Another type is <%init> and </%init>, which indicate a block of code to be processed before the main page is processed. The <%once> and </%once> tags are used for code that should run once at component load time, such as the use pragma to import the DBI into a namespace (use DBI;). A final type of delimiter or markup for Mason is <%args> and </%args>, which process the arguments being passed into the component.
Other types of markup are available with Mason, but the seven tag types described in this section are the ones you’ll likely encounter right away when getting to know Mason. Table 13-2 presents a recap of the seven frequently used Mason delimiters.
Table 13-2. Frequently Used Mason Delimiters
Delimiter |
Purpose |
<% ... %> |
Evaluate statements and interpolate values inline. |
% |
Execute single lines of Perl, conditionals, and loops. |
<& ... &> |
Call another component. |
<%args> ... </%args> |
Process incoming arguments to a component. |
<%init> ... </%init> |
Process prior to the main page. |
<%once> ... </%once> |
Process once at component initialization. |
|
erl. |
|
|
274 C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N
Still other tags are available for use, such as those for initialization and cleanup. Notably, the <%shared> tag is helpful when writing CGIs with Mason. Variables declared with <%shared> are initialized with every request as opposed to being initialized with each component, as you’d find with <%once>. Therefore, using <%shared> is a good approach for variable declaration within a CGI application.
For example, when a component is initialized the first time, you’ll likely want to share the DBI namespace for use across the component’s lifetime. However, any variables used within the CGI should live only on a per-request basis. The code would therefore look something like this:
<%once> use DBI; </%once> <%shared>
my $variable1;
my $othervariable; </%shared>
Arguments
When you call a component with Mason, it’s common to pass one or more arguments. For example, you might use Mason to manage common headers and footers of web pages. The header’s HTML needs to set the page title and other parameters specific to the page being built. When calling the component, you pass along arguments such as the title to the component being called.
Now that I’ve tried to explain this concept in writing (perhaps with limited success) twice, I’ll show you an example in code that may help clarify things. The example in Listing 13-5 is pulled directly from my web site’s home page, http://www.braingia.org.
Listing 13-5. Calling a Mason Component with Arguments
<& /header.mase, title=>"Braingia.org - Steve Suehring's Home Page",maintitle=> "Intarweb" &>
(HTML continues hereafter...)
From the example in Listing 13-5, you can see the opening tag for a component, <&, followed by the name of the component, in this case header.mase. Next are two arguments, title and maintitle. These arguments are then defined within the <%args> . . . </%args> section of the file header.mase.
The header.mase file begins by declaring the arguments:
<%args> $title $maintitle </%args>
The file continues with HTML and JavaScript, and eventually within the file the standard HTML <title> . . . </title> tag is used:
<title><% $title %></title>
C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N |
275 |
Somewhat later in the markup contained in header.mase, the $maintitle variable appears:
<%perl> unless ($maintitle eq "Intarweb") { </%perl>
<a href="http://www.braingia.org/">Braingia.org Home </a> / <% $maintitle %>
<%perl> } </%perl>
Since the lines wrapped in <%perl> and </%perl> contain only one line of code, they could have been written with a single %. However, the page source was indented for easier viewing; therefore, because the % needs to be placed at the beginning of the line, it would have broken the indenting. (Note that indenting is not represented in the code sample shown here.)
When this Masonized code is viewed in a web browser, it results in a page like the one shown in Figure 13-6. As you can see from the figure, the title and maintitle have been placed in the page.
Figure 13-6. The Mason page when viewed in a web browser
Return Values
Mason components can also return values when called, as opposed to the normal behavior of components to return undef. The return() function makes this possible. Using a return from a component enables code reuse by enabling you to define commonly used functions inside their own components. Having a component return a value is as simple as calling Perl’s standard return() function. Consider this example, which returns the temperature:
<%init>
my $temperature = 4; return $temperature; </%init>
Calling a component with a return value is not necessarily intuitive. Rather than calling the component with the normal <& ... &> syntax, you’re required to call it with the soon-to-be- introduced $m->comp('component_name') syntax. So, for example, to obtain the temperature
276 C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N
from the code just shown, you might save the component within a file called get_temp and then call that component from your normal Mason component:
% my $temp = $m->comp('get_temp');
At runtime, Mason will interpret this line, call the function located in the file get_temp, and place its return value into the $temp variable.
Request Objects
Two request objects are automatically provided within a Mason component: $r and $m. The $r request object is the Apache request object from mod_perl. As such, the methods available with $r when programming in a mod_perl environment are automatically sent to the component in Mason. Both $r and $m are specific to the current request being handled by Apache.
The $m object is a Mason-specific object that gives access to various Mason parameters, methods, and other components. You can control caching, read in files, and perform many advanced tasks with $m. For example, you can call other components through $m with the following syntax:
$m->comp(component_name, arguments)
When you call a component in this way, anything returned by the component is sent to the normal output stream. This is fine for cases where the component returns HTML, as in the header example shown earlier. However, when a component’s output shouldn’t be sent to the output stream, the scomp function is available. Using scomp to call a component results in its output being sent to a string as opposed to the stream:
$m->scomp(component_name, arguments)
The Mason method abort() aborts or stops the processing of a component. This can be helpful in cases where you want to immediately stop processing and throw an error if a certain condition is met—for example, if a user or IP address isn’t authorized to view a document.
$m->abort()
For more information on the abort() method, see the perldoc for HTML::Mason::Exception:: Abort. For a complete description of the Apache request object, see the perldoc for HTML::Mason:: Request and refer back to Chapters 10 and 11 of this book. Additionally, Apache::Request contains pertinent information for methods and attributes available through $r.
Handlers
Handlers are used in specific cases for executing code either prior to the component being processed or when a component cannot be found. A handler essentially takes care of special cases where you might want preprocessing for a component or you might want to dynamically load a component. The two types of handlers are dhandlers and autohandlers, both of which are discussed in the sections that follow.
C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N |
277 |
Dhandlers
You use dhandlers, or default handlers, to create or handle requests for resources that don’t actually exist and need to be created dynamically. For example, you might create a dynamic web page at http://www.example.com/products/item/01. You don’t, however, actually have a page at /products/item/01, but rather rely on a dhandler to serve the request.
When Mason receives a request for a component that doesn’t exist, it searches backward through the path of the URI looking for a component with the name dhandler. When Mason finds it, the dhandler component is processed and passed the name of the original component being called. The exact argument passed to the dhandler depends on the location where Mason finds the dhandler.
Following the example, here’s the original request, but there’s no such resource:
http://www.example.com/products/item/01
The following searches in the immediate directory:
http://www.example.com/products/item/dhandler
If no dhandler is found, go up one level and try again:
http://www.example.com/products/dhandler
If the dhandler is found, pass the argument 'item/01' to the dhandler and stop searching. The dhandler is passed its argument as $m->dhandler_arg. This means that the component 'item/01' would be passed into the dhandler and could be loaded, say, from a database or other place dynamically at runtime.
You can cascade or pass execution to the next dhandler by calling $m->decline. In addition, you can use the dhandler_name parameter to change the name of the component from the default (dhandler). Within the Apache configuration, this would be called as MasonDhandlerName and accepts a string:
MasonDhandlerName default_handler_doc
You can also disable dhandlers entirely by setting MasonDhandlerName to an empty string:
MasonDhandlerName ""
Autohandlers
Autohandlers actually get processed prior to the top-level component and are commonly used to set a common header or footer as well as global variables. The autohandler searches within the directory of the current request for a component named autohandler, which is then processed prior to processing the top-level component from the request.
Like the dhandler, the autohandler’s name can be changed from the default autohandler to another valid name using the autohandler_name parameter. In the Apache configuration, this parameter is known as MasonAutohandlerName.
There can be more than one autohandler. See the Mason Developer’s Manual at http://www.masonhq.com/docs/manual/Devel.html for more information.
278 C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N
Subrequests and More
When you call a component, it won’t normally go through the same steps as a top-level component, such as some initialization and searching for handlers. If you’d like the called component to go through those steps, you need to make it into a subrequest. Creating and executing a subrequest is a two-step process: first create the subrequest itself and then call its exec method.
Subrequests are created with the make_subrequest method of $m, for example:
<%perl>
my $subreq = $m->make_subrequest( comp => 'component_name', args => 'arguments' ); $subreq->exec;
</%perl>
In addition to subrequests, there are other features of Mason that might be helpful to you as you learn Mason and need additional functionality. See the Mason web site at http:// www.masonhq.com for more information on these other functions. The Mason site is an excellent resource for administrators and developers wishing to learn the ins and outs of Mason.
Building a Web Site with Mason
Both the amount and extent to which you use Mason for your web site will be determined by the goals you have and applications you wish to deploy on the site. For example, deploying Mason across a (mostly) static site by using common headers and footers is an excellent way to begin learning about Mason, its syntax, and its structure. Using Mason to build a full-blown application can, obviously, get more involved and require the use of more areas of Mason. This section gives some hands-on Masonized web site examples.
I do assume in this section that you’ve already set up your Mason environment with Apache. I also assume that Mason will be processing files with the .mhtml extension. This assumption is not based on preference so much as on just choosing something and running with it for the examples, so if you’re using .html or .anything as the standard extension for Mason, you shouldn’t feel the need to change it.
Building a Page
Likely the easiest place to begin is to simply create a web page, which I’ll call myfirstmason.mhtml. Inside that page, I’ll put some poorly formed HTML, place code to initialize a variable, set
a value for that variable, and output that variable to the browser along with some other text. Listing 13-6 presents the code for myfirstmason.mhtml.
Listing 13-6. A First Mason Page
<html><head><title>My First Mason</title></head>
%my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
=localtime(time);
<body>
C H A P T E R 1 3 ■ P E R L W E B S I T E S W I T H M A S O N |
279 |
today.</p>
<p>Copyright (c) <% $year+1900 %>, Steve Suehring</p>
</body>
</html>
Listing 13-6 is something you might actually see in a web page footer (and you can bet that it will show up again in this chapter). The current date and time are retrieved through the standard Perl localtime function. The next bit of Mason code shows up with the call to $year. Since localtime returns the number of years since 1900, it would return 105 normally, so
I added 1900 to the value to come up with the result 2005, as shown in Figure 13-7.
Figure 13-7. A first Mason example, printing a copyright notice of all things
Creating Headers and Footers
The code in Listing 13-6 lends itself to creating a common header and footer. For example, the copyright notice will have to be displayed on every page in the site.
For this section’s example, you’ll use three files, two of which are new. The myfirstmason. mhtml file will be edited, and a header and footer called header.mase and footer.mase, respectively, will be created. Like the .mhtml extension, the .mase extension was chosen arbitrarily, though as you’ll recall from the earlier example of my configuration, I have Apache configured to disallow any attempts to access a .mase file directly, for security reasons.
The contents of the header.mase file are as follows:
<html><head><title>My First Mason</title></head>
<body>
Notice that the Perl statement has been removed from the header. The footer.mase file contains the following code: