NAME

DESCRIPTION

SUBSTITUTION TAGS

<% expr %>

Blocks of the form <% expr %> are replaced with the result of evaluating expr as a Perl expression in scalar context.

Hello, <% $name %>! The current time is <% scalar(localtime) %>.

Whitespace after '<%' and before '%>' is required. This gives us a little leeway in implementing variations on this tag in the future - it also just looks better.

<% expr | filter,filter... %>

A filter list may appear after a << | >> character in a substitution, containing one or more names separated by commas. The names are as filter methods on the current component class. The filters are applied to the result before it is output.

UNNAMED BLOCKS

Blocks that do not take a name argument.

<%class>

Contains Perl code code that executes once when the component is loaded, in the main body of the class outside of any methods. This is the place to use modules, declare attributes, and do other things on a class level.

<%class>
</%class>

<%doc>

Text in this section is treated as a comment and ignored.

<%doc>
Name: foo.mc
Purpose: ...
</%doc>

<%flags>

Specifies flags that affect the compilation of the component. Each flag is listed one per line in key => value form.

<%flags>
extends => '/foo/bar'
</%flags>

The <%flags> block is extracted in a special first pass through the component, so that it can affect the remainder of the compilation.

The built-in flags are:

extends

Declares the component's superclass (another component). The path may be absolute as shown above, or relative to the component's path. This is the only way to declare the component's superclass; using an extends keyword directly will not work reliably. If not provided, the component's superclass is determined automatically via autobase components.

Plugins may implement additional flags.

<%init>

Contains Perl code that is executed at the beginning of the current method. Equivalent to a <%perl> section at the top of the method.

CALLING COMPONENTS

<& path, args &>

path is an absolute or relative component path. If the latter, it is considered relative to the location of the current component. args is a list of one or more name/value pairs.

The path may be a literal string (quotes optional) or a Perl expression that evaluates to a string. To eliminate the need for quotes in most cases, Mason employs some magic parsing: If the first character is one of [\w/_.], comp_path is assumed to be a literal string running up to the first comma or &>. Otherwise, comp_path is evaluated as an expression.

COMMENTS

<% # comment... %>

A <% %> tag is considered a comment if all of its lines are either whitespace, or begin with a '#' optionally preceded by whitespace. For example,

<% # This is a single-line comment %>
<%
# This is a
# multi-line comment
%>

% # comment

Because a line beginning with % is treated as Perl, % # automatically works as a comment. However we prefer the <% # comment %> form over % #, because it stands out a little more as a comment and because it is more flexible with regards to preceding whitespace.

% if (0) { }

Anything between these two lines

% if (0) {
...
% }

will be skipped by Mason, including component calls. While we don't recomend this for comments per se, it is a useful notation for "commenting out" code that you don't want to run.

HTML/XML/... comments

HTML and other markup languages will have their own comment markers, for example <!-- -->. Note two important differences with these comments versus the above comments:

They will be sent to the client and appear in the source of the page.

They do not block component calls and other code from running, so don't try to use them to comment out code!

<!-- Oops, the code below will still run
<& /shared/expensive.mhtml &>
-->

WHITESPACE AND NEWLINES

Newlines between blocks

Mason will ignore a single newline between blocks, so that you can space them nicely. Additional newlines beyond that will be displayed.

Backslash at end of line

A backslash (\) at the end of a line suppresses the newline. In HTML components, this is mostly useful for fixed width areas like <pre> tags, since browsers ignore white space for the most part. An example:

<pre>
foo
% if (1) {
bar
% }
baz
</pre>

outputs

foo
bar
baz

because of the newlines on lines 2 and 4. (Lines 3 and 5 do not generate a newline because the entire line is taken by Perl.) To suppress the newlines: