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

NAME

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

VERSION

9       version 1.59
10

SYNOPSIS

12           PerlModule HTML::Mason::ApacheHandler
13
14           <Location />
15               SetHandler perl-script
16               PerlHandler HTML::Mason::ApacheHandler
17           </Location>
18

DESCRIPTION

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
24       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
29       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
38       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
46       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
51       Consider this simple Mason component:
52
53           % my $noun = 'World';
54           Hello <% $noun %>!
55           How are ya?
56
57       The output of this component is:
58
59           Hello World!
60           How are ya?
61
62       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
67       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

MAINTENANCE HELP NEEDED

73       I (Dave Rolsky) am no longer using HTML::Mason and I would love to find
74       some co-maintainers to help. Specifically, I'd like people to review
75       issues and PRs, create new PRs, and ultimately take on the task of
76       uploading new releases to CPAN. If you're interested the best way to
77       start is to fix one or more of the issues in the issue tracker
78       <https://github.com/houseabsolute/HTML-
79       Mason/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc>.
80

WAIT - HAVE YOU SEEN MASON 2?

82       Version 1 of Mason (this distribution) -- has been around since 1998,
83       is in wide use, and is very stable. However it has not changed much in
84       years and is no longer actively developed.
85
86       Version 2 of Mason -- Mason -- was released in February of 2011. It
87       offers a new syntax as well as a number of other features. See
88       <https://metacpan.org/pod/distribution/Mason/lib/Mason/Manual/UpgradingFromMason1.pod>
89       for details of the differences between the two.
90

INSTALLATION

92       Mason has been tested under Linux, FreeBSD, Solaris, HPUX, and Win32.
93       As an all-Perl solution, it should work on any machine that has working
94       versions of Perl 5.00503+, mod_perl, and the required CPAN modules.
95
96       Mason has a standard MakeMaker-driven installation. See the README file
97       for details.
98

CONFIGURING MASON

100       This section assumes that you are able to install and configure a
101       mod_perl server. Relevant documentation is available at
102       http://www.apache.org (Apache) and http://perl.apache.org (mod_perl).
103       The mod_perl mailing list, archive, and guide are also great resources.
104
105       The simplest configuration of Mason requires a few lines in your
106       httpd.conf:
107
108           PerlModule HTML::Mason::ApacheHandler
109
110           <Location />
111               SetHandler perl-script
112               PerlHandler HTML::Mason::ApacheHandler
113           </Location>
114
115       The PerlModule directive simply ensures that the Mason code is loaded
116       in the parent process before forking, which can save some memory when
117       running mod_perl.
118
119       The <Location> section routes all requests to the Mason handler, which
120       is a simple way to try out Mason. A more refined setup is discussed in
121       the Controlling Access via Filename Extension section of the
122       administrator's manual.
123
124       Once you have added the configuration directives, restart the server.
125       First, go to a standard URL on your site to make sure you haven't
126       broken anything. If all goes well you should see the same page as
127       before. If not, recheck your Apache config files and also tail your
128       server's error log.
129
130       If you are getting "404 Not Found" errors even when the files clearly
131       exist, Mason may be having trouble with your document root. One
132       situation that will unfortunately confuse Mason is if your document
133       root goes through a symbolic link. Try expressing your document root in
134       terms of the true filesystem path.
135
136       Next, try adding the tag <% 2+2 %> at the top of some HTML file. If you
137       reload this page and see a "4", Mason is working!
138

DOCUMENTATION ROADMAP

140       Once Mason is on its feet, the next step is to write a component or
141       two. The Mason Developer's Manual is a complete tutorial for writing,
142       using, and debugging components. A reference companion to the
143       Developer's Manual is the Request API documentation,
144       HTML::Mason::Request.
145
146       Whoever is responsible for setting up and tuning Mason should read the
147       Administrator's Manual, though developers will also benefit from
148       reading it as well. This document covers more advanced configuration
149       scenarios and performance optimization. The reference companion to the
150       Administrator's manual is the Parameters Reference, which describes all
151       the parameters you can use to configure Mason.
152
153       Most of this documentation assumes that you're running Mason on top of
154       mod_perl, since that is the most common configuration.  If you would
155       like to run Mason via a CGI script, refer to the
156       HTML::Mason::CGIHandler documentation.  If you are using Mason from a
157       standalone program, refer to the Using Mason from a Standalone Script
158       section of the administrator's manual.
159
160       There is also a book about Mason, Embedding Perl in HTML with Mason, by
161       Dave Rolsky and Ken Williams, published by O'Reilly and Associates.
162       The book's website is at http://www.masonbook.com/.  This book goes
163       into detail on a number of topics, and includes a chapter of recipes as
164       well as a sample Mason-based website.
165

GETTING HELP AND SOURCES

167       Questions and feedback are welcome, and should be directed to the Mason
168       mailing list. You must be subscribed to post.
169
170           https://lists.sourceforge.net/lists/listinfo/mason-users
171
172       You can also visit us at "#mason" on <irc://irc.perl.org/#mason>.
173
174       Bugs and feature requests will be tracked at RT:
175
176           http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-Mason
177           bug-html-mason@rt.cpan.org
178

SUPPORT

180       Bugs may be submitted at
181       <https://github.com/houseabsolute/HTML-Mason/issues>.
182
183       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
184

SOURCE

186       The source code repository for HTML-Mason can be found at
187       <https://github.com/houseabsolute/HTML-Mason>.
188

AUTHORS

190       ·   Jonathan Swartz <swartz@pobox.com>
191
192       ·   Dave Rolsky <autarch@urth.org>
193
194       ·   Ken Williams <ken@mathforum.org>
195

CONTRIBUTORS

197       ·   Ævar Arnfjörð Bjarmason <avarab@gmail.com>
198
199       ·   Alex Balhatchet <kaoru@slackwise.net>
200
201       ·   Alex Vandiver <alex@chmrr.net>
202
203       ·   Florian Schlichting <fsfs@debian.org>
204
205       ·   John Williams <jwilliams@cpan.org>
206
207       ·   Kent Fredric <kentnl@gentoo.org>
208
209       ·   Kevin Falcone <falcone@bestpractical.com>
210
211       ·   Patrick Kane <modus-cpan@pr.es.to>
212
213       ·   Ricardo Signes <rjbs@cpan.org>
214
215       ·   Shlomi Fish <shlomif@shlomifish.org>
216
218       This software is copyright (c) 1998 - 2020 by Jonathan Swartz.
219
220       This is free software; you can redistribute it and/or modify it under
221       the same terms as the Perl 5 programming language system itself.
222
223       The full text of the license can be found in the LICENSE file included
224       with this distribution.
225
226
227
228perl v5.32.0                      2020-07-28                    HTML::Mason(3)
Impressum