HTML::Mason(3pm)

1HTML::Mason(3)        User Contributed Perl Documentation       HTML::Mason(3)
2
3
4

NAME

6       Mason - High-performance, dynamic web site authoring system
7

SYNOPSIS

9           PerlModule HTML::Mason::ApacheHandler
10
11           <Location />
12               SetHandler perl-script
13               PerlHandler HTML::Mason::ApacheHandler
14           </Location>
15

DESCRIPTION

17       Mason is a tool for building, serving and managing large web sites. Its
18       features make it an ideal backend for high load sites serving dynamic
19       content, such as online newspapers or database driven e-commerce sites.
20
21       Actually, Mason can be used to generate any sort of text, whether for a
22       web site or not.  But it was originally built for web sites and since
23       that's why most people are interested in it, that is the focus of this
24       documentation.
25
26       Mason's various pieces revolve around the notion of "components''. A
27       component is a mix of HTML, Perl, and special Mason commands, one com‐
28       ponent per file. So-called "top-level" components represent entire
29       web-pages, while smaller components typically return HTML snippets for
30       embedding in top-level components. This object-like architecture
31       greatly simplifies site maintenance: change a shared component, and you
32       instantly changed all dependant pages that refer to it across a site
33       (or across many virtual sites).
34
35       Mason's component syntax lets designers separate a web page into pro‐
36       grammatic and design elements. This means the esoteric Perl bits can be
37       hidden near the bottom of a component, preloading simple variables for
38       use above in the HTML. In our own experience, this frees content man‐
39       agers (i.e., non-programmers) to work on the layout without getting
40       mired in programming details. Techies, however, still enjoy the full
41       power of Perl.
42
43       Mason works by intercepting innocent-looking requests (say,
44       http://www.yoursite.com/index.html) and mapping them to requests for
45       Mason components.  Mason then compiles the component, runs it, and
46       feeds the output back to the client.
47
48       Consider this simple Mason component:
49
50           % my $noun = 'World';
51           Hello <% $noun %>!
52           How are ya?
53
54       The output of this component is:
55
56           Hello World!
57           How are ya?
58
59       In this component you see a mix of standard HTML and Mason elements.
60       The bare '%' prefixing the first line tells Mason that this is a line
61       of Perl code. One line below, the embedded <% ... %> tag gets replaced
62       with the return value of its contents, evaluated as a Perl expression.
63
64       Beyond this trivial example, components can also embed serious chunks
65       of Perl code (say, to pull records from a database). They can also call
66       other components, cache results for later reuse, and perform all the
67       tricks you expect from a regular Perl program.
68

INSTALLATION

70       Mason has been tested under Linux, FreeBSD, Solaris, HPUX, and Win32.
71       As an all-Perl solution, it should work on any machine that has working
72       versions of Perl 5.00503+, mod_perl, and the required CPAN modules.
73
74       Mason has a standard MakeMaker-driven installation. See the README file
75       for details.
76

CONFIGURING MASON

78       This section assumes that you are able to install and configure a
79       mod_perl server. Relevant documentation is available at
80       http://www.apache.org (Apache) and http://perl.apache.org (mod_perl).
81       The mod_perl mailing list, archive, and guide are also great resources.
82
83       The simplest configuration of Mason requires a few lines in your
84       httpd.conf:
85
86           PerlModule HTML::Mason::ApacheHandler
87
88           <Location />
89               SetHandler perl-script
90               PerlHandler HTML::Mason::ApacheHandler
91           </Location>
92
93       The PerlModule directive simply ensures that the Mason code is loaded
94       in the parent process before forking, which can save some memory when
95       running mod_perl.
96
97       The <Location> section routes all requests to the Mason handler, which
98       is a simple way to try out Mason. A more refined setup is discussed in
99       the Controlling Access via Filename Extension section of the adminis‐
100       trator's manual.
101
102       Once you have added the configuration directives, restart the server.
103       First, go to a standard URL on your site to make sure you haven't bro‐
104       ken anything. If all goes well you should see the same page as before.
105       If not, recheck your Apache config files and also tail your server's
106       error log.
107
108       If you are getting "404 Not Found" errors even when the files clearly
109       exist, Mason may be having trouble with your document root. One situa‐
110       tion that will unfortunately confuse Mason is if your document root
111       goes through a symbolic link. Try expressing your document root in
112       terms of the true filesystem path.
113
114       Next, try adding the tag <% 2+2 %> at the top of some HTML file. If you
115       reload this page and see a "4", Mason is working!
116

DOCUMENTATION ROADMAP

118       Once Mason is on its feet, the next step is to write a component or
119       two. The Mason Developer's Manual is a complete tutorial for writing,
120       using, and debugging components. A reference companion to the Devel‐
121       oper's Manual is the Request API documentation, HTML::Mason::Request.
122
123       Whoever is responsible for setting up and tuning Mason should read the
124       Administrator's Manual, though developers will also benefit from read‐
125       ing it as well. This document covers more advanced configuration sce‐
126       narios and performance optimization. The reference companion to the
127       Administrator's manual is the Parameters Reference, which describes all
128       the parameters you can use to configure Mason.
129
130       Most of this documentation assumes that you're running Mason on top of
131       mod_perl, since that is the most common configuration.  If you would
132       like to run Mason via a CGI script, refer to the HTML::Mason::CGIHan‐
133       dler documentation.  If you are using Mason from a standalone program,
134       refer to the Using Mason from a Standalone Script section of the admin‐
135       istrator's manual.
136
137       There is also a book about Mason, Embedding Perl in HTML with Mason, by
138       Dave Rolsky and Ken Williams, published by O'Reilly and Associates.
139       The book's website is at http://www.masonbook.com/.  This book goes
140       into detail on a number of topics, and includes a chapter of recipes as
141       well as a sample Mason-based website.
142

AUTHORS

144       Jonathan Swartz <swartz@pobox.com>, Dave Rolsky <autarch@urth.org>, Ken
145       Williams <ken@mathforum.org>, John Williams <williams@tni.com>
146

COPYRIGHT

148       Copyright (c) 1998-2005 Jonathan Swartz.  All rights reserved.  This
149       program is free software; you can redistribute it and/or modify it
150       under the same terms as Perl itself.
151
152       The full text of the license can be found in the LICENSE file included
153       with this module.
154