CHP-2>
As mentioned in A<CHP-1>Chapter 1, the basic building block of Mason is called a component. A component consists of text of any sort as well as Mason-specific markup syntax. This chapter briefly introduces some core Mason concepts and then goes into the nitty-gritty of component syntax.
In this chapter we'll introduce you to the syntax of Mason components, but we won't spend much time on semantics. In most of the sections, we refer to other parts of the book where you can find out more about each concept.
CHP-2-SECT-1>
In order to put Mason into perspective, a basic understanding of how Mason;processing requests in> requests> Mason processes a request is helpful. Each request is defined by an initial component path and a set of arguments to be passed to that component.
Requests are handled by the Interpreter object. You can use it directly or its API can be called by the ApacheHandler or CGIHandler modules provided with Mason.
The Interpreter;overview> Interpreter asks the Resolver;overview> Resolver to fetch the requested component from the filesystem. Then the Interpreter asks the Compiler;overview> Compiler to create a ``compiled'' representation of the component. Mason's compilation process consists of turning Mason source code into Perl code, which is then executed in order to create an object representing the component. Mason stores this generated Perl code on disk, so that it doesn't need to go through the parsing and compilation process for every request, and stores the compiled code in an LRU (least recently used) cache> LRU (least recently used) cache in memory.
Once Mason has an object representing the initial component, it creates a request object> request object and tells it to execute that component. The initial component might call several other components during the request. Any output a component generates is sent to STDOUT, which is a reasonable default for most environments in which Mason might be used. Of course, it is possible to change this default and send output elsewhere.
Several parameters can change how elements of this process happen, and you can replace the core Mason classes with your own customized subclasses for specialized behavior. When using the ApacheHandler module, all of these parameters can be specified in the web server's configuration file.
If a fatal error occurs during any part of this process, Mason throws
an exception via Perl's built-in die(
)
die( ) function
(Perl)>
function. In a
mod_perl
or CGI environment, Mason will make sure
that this exception is handled in a reasonable way, by showing the
error in the browser and/or recording the error in the
server's error log. You can also catch exceptions in
your own code and handle them as you __FOX_NLBF__>
__FOX_NLBF__>
please.
CHP-2-SECT-2>
Before diving into component syntax, it is important to understand a few basic Mason;basic concepts> Mason concepts, with the key concepts highlighted in italics.
First there is the component components> . A component is a combination of text and Mason-specific markup. The markup sections may contain Perl code or special Mason directives. A component can correspond to a single web page, but more often a page is built up from several components. However, a component always corresponds to a single file.
A component is usually expected to generate output of some sort, whether HTML, an email message, or an image file. Components are closely analogous to Perl subroutines.
The component root component roots> is a directory or list of directories;component roots as> components;directories of> directories on the filesystem under which Mason expects to find all of your components. This is important in determining how component calls are resolved. If you ask Mason to execute the component /view/books.comp, Mason needs to know where to find such a thing. If your component root is /var/www/mason, Mason will look for a file called /var/www/mason/view/books.comp.
The process of resolving a component
path
component
path>
to a component can actually be a bit more
complex than that, because you may actually specify multiple
directories in which to search for components or use another storage
mechanism altogether. We'll leave those complexities
aside for now.N<For the curious, these issues are
covered in A<CHP-3>Chapter 3, A<CHP-5>Chapter 5, and A<CHP-12>Chapter 12.>
When running under Apache, either via mod_perl
or
CGI, Mason will default to using the
web
servers;document root>
document root> web server's document root as the component root. Mason may also be used in ways that don't require a component root at all, such as from a standalone perl script. Since the focus of this book is on building sites, we will generally assume that there is a component root unless we mention otherwise.
It is very important to understand that component paths, like URL paths, always use the forward slash (/)> / (forward slash)> forward slash (/) as their directory separator, no matter what operating system Mason is running on. In other words, a component path can be thought of as a unique identifier for a particular component, in much the same way that a URL is a unique identifier for a particular resource. Also much like a URL, a component path usually corresponds to a file on disk with a related path, but it needn't __FOX_NLBF__> necessarily.
CHP-2-SECT-3>
Mason
parsing>
components;parsing>
parses
components by taking the text of a
components;basic
syntax>
component and translating it into
actual Perl code. This Perl code, when executed, creates a new
HTML::Mason::Component
HTML::Mason::Component
object>
object. This object, in turn, can be
used to generate the text originally found in the component. In a
sense, this inverts the component, turning it from text with embedded
Perl into Perl with embedded text.
The markup language Mason;markup language> markup language> Mason uses can give certain parts of the component special semantics, just like any other markup language such as XML or HTML. In this case, the syntax is used to tell Mason that certain parts of the component's text represent either Perl code, special instructions for Mason, or in some cases both.
The markup language used for Mason components contains a simple tag to do in-place substitution of Perl expressions, a way to mark a single line as being a line of Perl, and a set of block tags, most of which contain Perl code that is given a special meaning based on the particular tag being used (see A<CHP-2-TABLE-1>Table 2-1).