1HTML::Mason(3) User Contributed Perl Documentation HTML::Mason(3)
2
6 HTML::Mason - High-performance, dynamic web site authoring system
7
9 version 1.58
10
12 PerlModule HTML::Mason::ApacheHandler
13 <Location />
15 SetHandler perl-script
16 PerlHandler HTML::Mason::ApacheHandler
17 </Location>
18
20 Mason is a tool for building, serving and managing large web sites. Its
21 features make it an ideal backend for high load sites serving dynamic
22 content, such as online newspapers or database driven e-commerce sites.
23 Actually, Mason can be used to generate any sort of text, whether for a
25 web site or not. But it was originally built for web sites and since
26 that's why most people are interested in it, that is the focus of this
27 documentation.
28 Mason's various pieces revolve around the notion of "components''. A
30 component is a mix of HTML, Perl, and special Mason commands, one
31 component per file. So-called "top-level" components represent entire
32 web-pages, while smaller components typically return HTML snippets for
33 embedding in top-level components. This object-like architecture
34 greatly simplifies site maintenance: change a shared component, and you
35 instantly changed all dependent pages that refer to it across a site
36 (or across many virtual sites).
37 Mason's component syntax lets designers separate a web page into
39 programmatic and design elements. This means the esoteric Perl bits can
40 be hidden near the bottom of a component, preloading simple variables
41 for use above in the HTML. In our own experience, this frees content
42 managers (i.e., non-programmers) to work on the layout without getting
43 mired in programming details. Techies, however, still enjoy the full
44 power of Perl.
45 Mason works by intercepting innocent-looking requests (say,
47 http://www.yoursite.com/index.html) and mapping them to requests for
48 Mason components. Mason then compiles the component, runs it, and
49 feeds the output back to the client.
50 Consider this simple Mason component:
52 % my $noun = 'World';
54 Hello <% $noun %>!
55 How are ya?
56 The output of this component is:
58 Hello World!
60 How are ya?
61 In this component you see a mix of standard HTML and Mason elements.
63 The bare '%' prefixing the first line tells Mason that this is a line
64 of Perl code. One line below, the embedded <% ... %> tag gets replaced
65 with the return value of its contents, evaluated as a Perl expression.
66 Beyond this trivial example, components can also embed serious chunks
68 of Perl code (say, to pull records from a database). They can also call
69 other components, cache results for later reuse, and perform all the
70 tricks you expect from a regular Perl program.
71
73 Version 1 of Mason (this distribution) -- has been around since 1998,
74 is in wide use, and is very stable. However it has not changed much in
75 years and is no longer actively developed.
76 Version 2 of Mason -- Mason -- was released in February of 2011. It
78 offers a new syntax as well as a number of other features. See
79 <https://metacpan.org/pod/distribution/Mason/lib/Mason/Manual/UpgradingFromMason1.pod>
80 for details of the differences between the two.
81
83 Mason has been tested under Linux, FreeBSD, Solaris, HPUX, and Win32.
84 As an all-Perl solution, it should work on any machine that has working
85 versions of Perl 5.00503+, mod_perl, and the required CPAN modules.
86 Mason has a standard MakeMaker-driven installation. See the README file
88 for details.
89
91 This section assumes that you are able to install and configure a
92 mod_perl server. Relevant documentation is available at
93 http://www.apache.org (Apache) and http://perl.apache.org (mod_perl).
94 The mod_perl mailing list, archive, and guide are also great resources.
95 The simplest configuration of Mason requires a few lines in your
97 httpd.conf:
98 PerlModule HTML::Mason::ApacheHandler
100 <Location />
102 SetHandler perl-script
103 PerlHandler HTML::Mason::ApacheHandler
104 </Location>
105 The PerlModule directive simply ensures that the Mason code is loaded
107 in the parent process before forking, which can save some memory when
108 running mod_perl.
109 The <Location> section routes all requests to the Mason handler, which
111 is a simple way to try out Mason. A more refined setup is discussed in
112 the Controlling Access via Filename Extension section of the
113 administrator's manual.
114 Once you have added the configuration directives, restart the server.
116 First, go to a standard URL on your site to make sure you haven't
117 broken anything. If all goes well you should see the same page as
118 before. If not, recheck your Apache config files and also tail your
119 server's error log.
120 If you are getting "404 Not Found" errors even when the files clearly
122 exist, Mason may be having trouble with your document root. One
123 situation that will unfortunately confuse Mason is if your document
124 root goes through a symbolic link. Try expressing your document root in
125 terms of the true filesystem path.
126 Next, try adding the tag <% 2+2 %> at the top of some HTML file. If you
128 reload this page and see a "4", Mason is working!
129
131 Once Mason is on its feet, the next step is to write a component or
132 two. The Mason Developer's Manual is a complete tutorial for writing,
133 using, and debugging components. A reference companion to the
134 Developer's Manual is the Request API documentation,
135 HTML::Mason::Request.
136 Whoever is responsible for setting up and tuning Mason should read the
138 Administrator's Manual, though developers will also benefit from
139 reading it as well. This document covers more advanced configuration
140 scenarios and performance optimization. The reference companion to the
141 Administrator's manual is the Parameters Reference, which describes all
142 the parameters you can use to configure Mason.
143 Most of this documentation assumes that you're running Mason on top of
145 mod_perl, since that is the most common configuration. If you would
146 like to run Mason via a CGI script, refer to the
147 HTML::Mason::CGIHandler documentation. If you are using Mason from a
148 standalone program, refer to the Using Mason from a Standalone Script
149 section of the administrator's manual.
150 There is also a book about Mason, Embedding Perl in HTML with Mason, by
152 Dave Rolsky and Ken Williams, published by O'Reilly and Associates.
153 The book's website is at http://www.masonbook.com/. This book goes
154 into detail on a number of topics, and includes a chapter of recipes as
155 well as a sample Mason-based website.
156
158 Questions and feedback are welcome, and should be directed to the Mason
159 mailing list. You must be subscribed to post.
160 https://lists.sourceforge.net/lists/listinfo/mason-users
162 You can also visit us at "#mason" on <irc://irc.perl.org/#mason>.
164 Bugs and feature requests will be tracked at RT:
166 http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-Mason
168 bug-html-mason@rt.cpan.org
169
171 Bugs may be submitted at
172 <http://rt.cpan.org/Public/Dist/Display.html?Name=HTML-Mason> or via
173 email to bug-html-mason@rt.cpan.org <mailto:bug-html-
174 mason@rt.cpan.org>.
175 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
177
179 The source code repository for HTML-Mason can be found at
180 <https://github.com/houseabsolute/HTML-Mason>.
181
183 · Jonathan Swartz <swartz@pobox.com>
184 · Dave Rolsky <autarch@urth.org>
186 · Ken Williams <ken@mathforum.org>
188
190 · Ævar Arnfjörð Bjarmason <avarab@gmail.com>
191 · Alex Balhatchet <kaoru@slackwise.net>
193 · Alex Vandiver <alex@chmrr.net>
195 · John Williams <jwilliams@cpan.org>
197 · Kent Fredric <kentnl@gentoo.org>
199 · Kevin Falcone <falcone@bestpractical.com>
201 · Patrick Kane <modus-cpan@pr.es.to>
203 · Ricardo Signes <rjbs@cpan.org>
205 · Shlomi Fish <shlomif@shlomifish.org>
207
209 This software is copyright (c) 1998 - 2017 by Jonathan Swartz.
210 This is free software; you can redistribute it and/or modify it under
212 the same terms as the Perl 5 programming language system itself.
213 The full text of the license can be found in the LICENSE file included
215 with this distribution.
216perl v5.28.0 2017-10-29 HTML::Mason(3)