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.


Mason from 10,000 Feet

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.


Core Concepts

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.


Basic Component Syntax

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).