Preface

Mason is a tool for embedding the Perl programming language into text, in order to create text dynamically, most often in HTML. But Mason does not simply stop at HTML. It can just as easily create XML, WML, POD, configuration files, or the complete works of Shakespeare.

Mason was originally written by Jonathan Swartz, with the help of the rest of the CMP development team at CMP Media in 1996, and in its earliest incarnations it was known as Scribe.

Mason was first made publicly available as Version 0.1 in August of 1998. Since that time, Jonathan Swartz has invited your humble authors to participate in the further development of Mason. Mason has been expanded, and rewritten and is much changed from those early days. This book covers Version 1.12 of Mason.

Intended Audience

This book assumes that the reader is familiar with Perl at an intermediate level and that common Perl idioms don't stop you in your tracks. While you need not have written your own modules previously, familiarity with Perl's object-oriented syntax will be helpful.

Since Mason is most often used in the generation of web sites, this book frequently presents its example in terms of generating HTML pages. You definitely do not need to be an HTML expert to read this book, but a passing familiarity with HTML will be helpful in understanding what the output is intended to look like.

As previously mentioned, Mason is well-suited for the generation of any sort of dynamic text, including markup languages such as XML, as well as configuration files, email bodies (think mail merge, perhaps), or even code.

Finally, experience with mod_perl and Apache will be helpful for Chapter 7 and Chapter 9, which discuss integrating Mason with mod_perl and CGI, respectively, though the rest of the book should be easily comprehensible regardless of your familiarity with those particular topics.

Requirements

As of Version 1.12, Mason requires Perl Version 5.00503 or later, as well as the following modules available from CPAN: Class::Container 0.07+, File::Spec 0.8+, Params::Validate 0.24+, Exception::Class 1.01+, and Cache::Cache 1.00+.

If you want to run Mason under mod_perl, you will need to have at least Version 1.22 of mod_perl installed (although installing the very latest version in the 1.x series is highly recommended). You'll also probably want Apache::Request 0.31+, though this is not strictly required.

Some of the examples are designed to work in a web server context and may require either CGI or mod_perl capabilities. For the CGI examples, any CGI-capable web server is sufficient, though our configuration examples always assume Apache.

Mason itself is designed to be platform-agnostic. Any behavior to the contrary should be considered a bug in Mason, and bug reports are always welcome.

In writing this book, we did our testing with Perl 5.6.1 and mod_perl 1.25, with Apache 1.3.22, so it is possible that something shown here may not work as expected with other versions of these pieces of software. If you find this to be the case, please let us know and we'll either fix the example or make a note of the dependencies.

How to Read This Book

This book is not a reference manual. While certain chapters, notably Chapter 4, are reference-like in nature, the book as a whole builds chapter upon chapter and often refers to material covered earlier. Nonetheless, some readers may prefer to look at Chapter 8 early, so an alternate path through the book might be to read that chapter right after Chapter 1.

Once you become more familiar with Mason, we expect that much of the book will still be useful as a reference, particularly Chapter 4, Chapter 5, Chapter 6, and Chapter 7.

Appendix A and Appendix B present much of the same material as those chapters in a more streamlined reference style, and should also be useful long after you have become a Mason guru. Appendix C is a short discussion of editors you can use with Mason, and Appendix D covers Bricolage, a content management system based on Mason.

Finally, the book includes a short glossary for those of you who are new to Mason and its terminology.

Overview

Chapter 1

This chapter goes into more detail on what Mason is, highlights a few of its most notable features, and also discusses some alternatives to Mason.
Chapter 2

Components are the basic building block in Mason. This chapter covers component syntax and how components can call one another, much like Perl subroutines.
Chapter 3

The topic of this chapter is dhandlers and autohandlers, two features unique to Mason that really can help you maximize code reuse.
Chapter 4

This chapter is a bit more of a reference than those before it, as it has a lot of ground to cover. We cover the APIs of various objects that you might want to access from your components, primarily the Mason request object.
Chapter 5

Now that you know about component syntax, dhandlers, autohandlers, and a good chunk of the Mason API, it's time to learn about some of Mason's more complex features, like component methods and attributes, components that filter content, and Mason subrequests.
Chapter 6

These objects form the core of Mason itself, and their constructor parameters and object APIs let you customize the way Mason handles requests.
Chapter 7

Mason and mod_perl are designed to play nice together, and this chapter shows you how to make this happen.
Chapter 8

The obligatory sample site. See Mason at work on a real, live, on-the-Internet, usable-by-you web site.
Chapter 9

If you can't use mod_perl, you may still want to use Mason to generate web pages via CGI scripts.
Chapter 10

Mason is cool, but it's not magic. You still need to think about architecture and design when designing a Mason-based application. We try to give you a few things to think about here.
Chapter 11

This chapter demonstrates a number of different uses of Mason in order to stimulate your thinking, as well as provide some easily customized example code.
Chapter 12

A how-to on creating your own customized Mason subclasses.
Appendix A

All the APIs we covered earlier, in a more concise form.
Appendix B

A spiffy table of constructor parameters.
Appendix C

Information on using Emacs and Vim to edit Mason components.
Appendix D

David Wheeler explains how to use Bricolage, a content management system built with Mason that can use Mason to generate web pages.

Other Resources

The most important online resource for Mason is the Mason HQ site located at http://www.masonhq.com/. This site includes an online copy of the documentation, a Frequently Asked Questions database, news, user-contributed code and documentation, and much more. The bug tracker on Mason HQ is kept up-to-date, and it is a good source of information about limitations in certain versions of Mason. There is also a to-do list that can give you insights on future directions planned by the Mason developers.

Mason HQ also provides information on subscribing to the various Mason mailing lists, of which the most important is the mason-users list. See http://www.masonhq.com/resources/mailing_lists.html for more details.

This book's web site, at http://www.masonbook.com/, will always contain the latest digital version of the book, freely available. In addition, we will make sure to report any errata found in the published edition(s), as well as providing downloadable versions of all of the source code found in the book.

Typographic Conventions

Constant width

is used for literal text, module names, function names, method names, and keywords
Italics

is used for filenames, components, commands, URLs, emphasis, and terms when they are first introduced

We'd Like to Hear from You

Please send comments and questions concerning this book to the publisher at the following address:

O'Reilly & Associates, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
(800) 998-9938 (in the United States or Canada)
(707) 829-0515 (international or local)
(707) 829-0104 (fax)

We have a web page for this book, where we list errata, examples, or any additional information. You can access this page at:

http://www.oreilly.com/catalog/perlhtmlmason

To comment or ask technical questions about this book, send email to:

bookquestions@oreilly.com

For more information about our books, conferences, Resource Centers, and the O'Reilly Network, see our web site at:

http://www.oreilly.com

Open Publication License

This book is published under the Open Publication License (OPL), as follows:

Open Publication License Draft v1.0, 8 June 1999

I. REQUIREMENTS ON BOTH UNMODIFIED AND MODIFIED VERSIONS

The Open Publication works may be reproduced and distributed in whole or in part, in any medium physical or electronic, provided that the terms of this license are adhered to, and that this license or an incorporation of it by reference (with any options elected by the author(s) and/or publisher) is displayed in the reproduction.

Proper form for an incorporation by reference is as follows: Copyright (c) 2003 by O'Reilly & Associates, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/). Commercial redistribution of Open Publication-licensed material is permitted.

Any publication in standard (paper) book form shall require the citation of the original publisher and author. The publisher and author's names shall appear on all outer surfaces of the book. On all outer surfaces of the book the original publisher's name shall be as large as the title of the work and cited as possessive with respect to the title.

OPTION B: Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder.

II. COPYRIGHT

The copyright to each Open Publication is owned by its author(s) or designee.

III. SCOPE OF LICENSE

The following license terms apply to all Open Publication works, unless otherwise explicitly stated in the document. Mere aggregation of Open Publication works or a portion of an Open Publication work with other works or programs on the same media shall not cause this license to apply to those other works. The aggregate work shall contain a notice specifying the inclusion of the Open Publication material and appropriate copyright notice.

SEVERABILITY. If any part of this license is found to be unenforceable in any jurisdiction, the remaining portions of the license remain in force.

NO WARRANTY. Open Publication works are licensed and provided "as is" without warranty of any kind, express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose or a warranty of non-infringement.

IV. REQUIREMENTS ON MODIFIED WORKS

All modified versions of documents covered by this license, including translations, anthologies, compilations and partial documents, must meet the following requirements:

The modified version must be labeled as such.

The person making the modifications must be identified and the modifications dated.

Acknowledgement of the original author and publisher if applicable must be retained according to normal academic citation practices.

The location of the original unmodified document must be identified.

The original author's (or authors') name(s) may not be used to assert or imply endorsement of the resulting document without the original author's (or authors') permission.

V. GOOD-PRACTICE RECOMMENDATIONS

In addition to the requirements of this license, it is requested from and strongly recommended of redistributors that:

If you are distributing Open Publication works on hardcopy or CD-ROM, you provide email notification to the authors of your intent to redistribute at least thirty days before your manuscript or media freeze, to give the authors time to provide updated documents. This notification should describe modifications, if any, made to the document.

All substantive modifications (including deletions) be either clearly marked up in the document or else described in an attachment to the document.

Finally, while it is not mandatory under this license, it is considered good form to offer a free copy of any hardcopy and CD-ROM expression of an Open Publication-licensed work to its author(s).

For more information about the Open Publication License, visit the Open Content web site at http://www.opencontent.org/openpub.

Acknowledgments

Ken would like to thank Dunn Brothers Coffee in St. Paul, Minnesota, where huge chunks of this book were written over steamy mochas in between crossword puzzle sessions. He would like to thank Apple Computer for creating the iBook, Cyclic Software for creating the CVS revision control system, and Larry Wall for creating the much-overstressed POD markup language, all of which were essential tools in the creation of this book. He'd like to thank Helen Plotkin and the rest of the Math Forum for turning a naive young mathematician into a salty programmer of the world. He'd like to thank his friends and family for not asking too many questions about what he does all day. Most importantly, he would like to thank Sheri Schechinger for being proud of a lowly open source programmer, for asking questions about what he does all day, and for giving him something so wonderful to come home to.

Dave would first and foremost like to thank his wife, Huey-Ling Chen, for her support and humor, particularly the "juice guy" incident (he'd explain, but then he'd have to juice you). He also wants to thank DoTheGood, Inc., in particular Gabriel Cheifetz, for providing such a great place to work while at the same time giving him enough free time to actually write this thing. Jonathan Swartz deserves thanks and sympathy for letting Dave muck up his code in such a cruel and twisted manner. Jon will no doubt get over the shock one day. Finally, Dave wants to thank any friend or family member who had the good grace not to cruelly mock him when they asked "when will the book be out?" and he responded with something like "oh, it's almost done, it should be out in a few months." How wrong he was!

Both authors would like to thank our unshockable editor, Linda Mui, and our crack team of technical reviewers: Alex Edelman, Jules Cook Graybill, Joe Johnston, Mike Stok, Jonathan Swartz, David Wheeler, and John Williams. David Wheeler in particular needs to be singled out for praise, not only for his excellent appendix on Bricolage (Appendix D), but also for his careful, detailed review. If his review comments were printed in the same typeface as this book, they would be about 100 pages long! Without his comments, and those of our other reviewers, this book would pretty much suck.

Joshua Chamas, Mark-Jason Dominus, Gerald Richter, and Sam Tregar provided invaluable feedback on the comparisons to other templating systems, in many cases defending their own systems from the ham-handed errors we made in describing them.

The entire group of overseers is responsible for transforming a disorganized and error-ridden draft into what we hope is a useful resource for billions and billions of Mason users. Or at least a few dozen.

These HTML pages were created by running this script against the pseudo-POD source.