1HTML::Mason::FAQ(3) User Contributed Perl Documentation HTML::Mason::FAQ(3)
2
6 HTML::Mason::FAQ - Frequently asked questions
7
9 Can I set a page's inheritance dynamically at request time (e.g. based on
10 URL arguments)?
11 No. Inheritance is a fixed property of a component, determined once
12 when the component is loaded. Dynamic inheritance is on the todo list.
13 How can I tell Mason to use autohandlers or dhandlers when calling one
15 component from another component (i.e. internal redirect)?
16 Usually this situation arises when a top-level component makes a run-
17 time decision to use a second component as the "real" page, and calls
18 it via <& &> or $m->comp.
19 Autohandlers and dhandlers are only triggered for the top-level
21 component of a request. In 1.1, you can use an Apache internal redirect
22 or a Mason subrequest ($m->subexec) to solve the problem.
23 I added a simple autohandler to a directory and now my pages don't appear.
25 Make sure to include a call to $m->call_next somewhere in the
26 autohandler.
27 Where does a dhandler inherit from? Can I change it to inherit based on the
29 URL path?
30 A dhandler's inheritance is determined by its location in the
31 hierarchy, not by the URL that invoked it.
32 Consider a site with the following components:
34 /autohandler
36 /dhandler
37 /products/autohandler
38 and suppose a request comes in for /products/index.html. /dhandler will
40 handle the request but will still inherit from /autohandler.
41 This is not always the desired behavior, but there is no easy way to
43 change it. If you want /products/* requests to use
44 /products/autohandler, you'll need to create /products/dhandler as
45 well.
46 Can I change the value of an attribute dynamically, based on the request?
48 No, attributes are static. The closest thing to a dynamic attribute is
49 a method. If you've been using an attribute widely and don't want to
50 change it to a method everywhere, consider using an attribute/method
51 combination. Suppose your attribute is called 'bgcolor'. Create a
52 default method called 'bgcolor' in the autohandler:
53 <%method bgcolor>
55 <%init>
56 return $m->base_comp->attr('bgcolor');
57 <%init>
58 </%method>
59 Then replace every other
61 $m->base_comp->attr('bgcolor');
63 with
65 $m->base_comp->call_method('bgcolor')
67 or
69 <& SELF:bgcolor &>
71 Now you can leave the attribute definitions alone, but define a method
73 if and when you need a dynamically computed value.
74 When using multiple component roots and autohandlers, does every
76 autohandler in every root get called, and in what or
77 Mason will try each autohandler path in turn, e.g.
78 /foo/bar/baz/autohandler
80 /foo/bar/autohandler
81 /foo/autohandler
82 /autohandler
83 For each path, it will search all of the component roots, and only run
85 the *first* autohandler found. Some of the autohandlers might come from
86 one root and some from another. However, there is no way that multiple
87 autohandlers would be run for the same path (/foo/autohandler, for
88 example.) There is also no way for /foo/autohandler in root 1 to
89 explicitly call /foo/autohandler in root 2.
90 People sometimes ask for this behavior to be changed. We feel it's a
92 bad idea because multiple component roots, right now, are very clean in
93 both behavior and implementation. Trying to run multiple autohandlers
94 for the same path would require a complex set of precedence rules that
95 would almost certainly lead to unpredictable behavior. (Think about
96 multiple versions of multiple autohandlers at different directory
97 levels, and trying to predict which order they'd run in.)
98
100 When I change a component I don't always see the results in the output. How
101 do I invalidate Mason code caches?
102 Mason employs two kinds of code caching. First, Mason caches loaded
103 components in memory. Second, Mason keeps an object file (a compiled
104 version of the component) for every loaded component under
105 data_root/obj.
106 Before executing a memory-cached component, Mason compares the stored
108 timestamp with the timestamp of the source file. If the source file has
109 a later timestamp, Mason will load the component from the filesystem.
110 Similarly, before using an object file, Mason compares the modified
112 timestamp of the source and object files. If the source file has a
113 later timestamp, then it is reparsed and the object file is
114 overwritten.
115 The system is designed so that you will immediately see the effects of
117 source file changes. There are several ways for this system to
118 breakdown; most are easy to avoid once you know about them.
119 * If you copy or move in a component source file from elsewhere, it
121 will retain the original file's timestamp, which may be earlier than
122 the object file.
123 * If you use tar, rsync, rdist or similar programs to transfer
125 components, the timestamps of the created files may not be updated to
126 the current time. Check the program's documentation for timestamp-
127 related options.
128 * If you use a shared file system like NFS, the timestamps of locally
130 created files may not jibe with timestamps of NFS files due to
131 differences in machine clocks.
132 * If you ftp files onto a running server, Mason may read the file while
134 it is incomplete. If the ftp then completes within the same second,
135 Mason will not notice the change, and won't ever read the complete
136 file.
137 When in doubt, touching the source files (with the Unix touch command,
139 or by re-saving in an editor) should force Mason to reload the
140 component. If that does not work, try removing the object files and/or
141 restarting the server to clear the memory cache. However, these
142 remedies should be necessary only to diagnose the caching problem, not
143 for normal Mason operation. On a normal Mason system cache expiration
144 should just work "as expected".
145 Mason code caching breaks down often in my situation. Couldn't you do
147 something smarter than just comparing the timestamps?
148 When coming up with invalidation schemes, we must consider efficiency
149 as well as failure predictability. The current scheme does fail in
150 certain situations, but those situations are very predictable. If you
151 incorrectly use tar or copy or another technique mentioned above,
152 you'll see the cache invalidation failure very quickly.
153 Some alternatives that have been suggested:
155 * Compare the sizes of the files as well as timestamps, or use the more
157 liberal "source timestamp != object timestamp". This would indeed
158 increase the chance of catching a change. But it would still fail
159 occasionally (e.g. when changing a single character, or when copying an
160 old-timestamp file that just happens to match the current timestamp),
161 resulting in intermittent, head-scratching errors. In our opinion, it
162 is better to fail miserably up front and be forced to fix your system
163 than to have a mostly-working system that fails once a week. This is
164 especially true when you are relying on Mason's cache invalidation on a
165 production system.
166 * Comparing MD5 or other signatures of the content. This would be very
168 accurate, but would require reading and processing the source file
169 instead of just performing a stat. This extra expense reduces the
170 effectiveness of the cache.
171 The bottom line: If you are relying on Mason's cache invalidation on a
173 production system, you should take the time and build in the
174 appropriate infrastructure to ensure that source file timestamps are
175 always up-to-date after they are copied/untarred into place.
176 When I change code in a library file I don't see the results. How can I get
178 Mason to reread the library files?
179 mod_perl processes, in general, do not automatically reread your
180 library files. You either have to stop and start the server whenever
181 you change a library file, or install something like Apache::Reload
182 which will automate their reloading. However, see ApacheReload for
183 important usage information.
184 Once I've made an error in a component, the error keeps appearing in the
186 logs, no matter how many times I fix it and reload!
187 Are you using Apache::Reload in its default (!ReloadAll) mode? If so,
188 see ApacheReload for details.
189 Do data cache files expire automatically when a component or its
191 dependencies change?
192 Unfortunately they do not. This is on the to-do list.
193 With Mason 1.1x and beyond, you can use the following idiom to say
195 ``expire when my component source file changes'':
196 $m->cache(...,
198 expire_if=>sub {
199 (stat($m->current_comp->source_file))[9] > $_[0]->get_created_at
200 } )
201 With Mason <= 1.05, the idiom looks like:
203 $m->cache(...,
205 expire_if=>sub {
206 (stat($m->current_comp->source_file))[9] > $_[0]
207 } )
208
210 What is a component?
211 A component is a file that contains some combination of text (typically
212 HTML), perl code and HTML::Mason directives.
213 Some components are accessed directly by web browsers. These are called
215 top-level components. A top-level component might consist purely of
216 static HTML.
217 Other components are support components, which are called by top-level
219 components or other support components. These components are analogous
220 to perl subroutines -- they allow you to create small packages of code
221 that you can reuse throughout your project.
222 How do components communicate with each other?
224 Components can return values to their callers, just like subroutines.
225 Some components may have very simple return values. As an example,
227 consider a component called isNetscape which returns a true value when
228 the client's browser is Netscape and undef when it is not. The
229 isNetscape component could then be used easily in an if() or other
230 control statement.
231 Of course, components can also return strings of text, arrays, hashes
233 or other arbitrarily complex perl data structures.
234 How do I use modules in components?
236 Technically you can just say "use module-name" at the beginning of a
237 component. The disadvantages of this method are that:
238 * the module will be used separately by every httpd child process,
240 costing both time and memory.
241 * it is difficult to keep track of all the modules being used on a
243 site.
244 A more efficient method is to put the use line in the handler.pl or use
246 the PerlModule directive. If you want components to be able to refer to
247 symbols exported by the module, you need to use the module inside the
248 HTML::Mason::Commands package. See the "External modules" section of
249 the Administrator's Guide:
250 Can I define subroutines in components?
252 Defining a named subroutine in a <%perl> or <%init> section does not
253 work reliably because such a definition would end up residing inside
254 another subroutine, and Perl doesn't like that.
255 You can technically define named subroutines inside the <%once> section
257 of any component, but we highly discourage this, because all components
258 are executed in the same namespace. This makes it easy to create two
259 subroutines with the same name in two different components.
260 Consider the following options:
262 * If the routine is going to display HTML, use a separate component or
264 a <%def> subcomponent.
265 * If the subroutine is only of use in your component, use an anonymous
267 subroutine defined in <%once>. Even though you could define the
268 anonymous subroutine in any section, a <%once> is recommended, both for
269 performance and to avoid nested-anonymous-subroutine leaks in Perl
270 <=5.6. Example:
271 <%once>
273 my $foo = sub {
274 ...
275 };
276 </%once>
277 ...
279 % $foo->()
281 * If the subroutine is of interest to more than just your component,
283 have you considered putting it in a module?
284 Note that calling a component, while reasonably fast, is about an order
286 of magnitude slower than calling an equivalent subroutine. So if you're
287 going to call the routine many times in a loop, you may wish to use the
288 anonymous subroutine for performance reasons. Benchmark for yourself.
289 Does Mason set the current working directory (".") for me?
291 Mason does not touch the working directory, as this would entail an
292 unnecessary performance hit for the majority of users that don't need
293 it.
294 In an Apache environment, the working directory will be set in a more-
296 or-less random way, depending on such seemingly irrelevant factors as
297 whether you started the server in single-process mode or not. In a non-
298 Apache environment the working directory will be whatever it was before
299 Mason started executing.
300 Often people expect the working directory to be the directory of the
302 current component. You can, instead, get that directory manually with
303 $m->current_comp->source_dir
305 How do I exit from all components including the ones that called me?
307 Use $m->abort, documented in the Request manual:
308 Why does my output have extra newlines/whitespace and how can I get rid of
310 it?
311 Any newlines that are not either inside a tag or on a %-line will
312 become part of the output. Since browsers ignore extra whitespace this
313 is not generally a problem, but there are situations where it matters,
314 e.g. within <pre> tags.
315 First, for components that only return a value and shouldn't output
317 *any* content, you should always use <%init>:
318 <%args>
320 $foo
321 </%args>
322 This content will be ignored.
324 <%init>
326 my $bar = $dbh->selectrow_array("SELECT bar FROM t WHERE foo=?", $foo);
327 return $bar;
328 </%init>
329 In components that do display content, there are various strategies. To
331 eliminate selected newlines, use the backslash. For example,
332 <PRE>
334 foo\
335 % if (1) {
336 bar\
337 % }
338 baz
339 </PRE>
340 outputs "foobarbaz" with no newlines.
342 To prevent a component from outputting any newlines, use a filter:
344 <%filter>
346 s/\n//g;
347 </%filter>
348 To emit binary data without the risk of inserting extra whitespace,
350 surround your code with $m->clear_buffer and $m->abort, to suppress any
351 preceding and following content:
352 <%init>
354 $m->clear_buffer;
355 my $fh = IO::File->new('< binary_file') or die $!;
356 my $buffer;
357 while (read $fh, $buffer, 8192) {
358 $m->print($buffer);
359 }
360 $m->abort;
361 </%init>
362 At some point Mason will probably offer a "reasonable" whitespace
364 removal feature, controlled by parameter.
365 I'm trying to generate an image or other binary file, but it seems to be
367 getting corrup
368 This is almost always caused by unwanted whitespace at the beginning or
369 end of your binary data. Put a $m->clear_buffer before, and an
370 $m->abort after, your code. See the last part of the answer above.
371 In Apache 1.0 a real working example looks like this:
373 my $fh;
375 my $fileName = '/tmp/mypic.jpg';
376 open ( $fh, $fileName ) or die $!;
377 $m->clear_buffer();
379 $r->content_type( 'image/jpeg' ); # set mime-type
380 $r->send_http_header;
381 $r->send_fd ( $fh );
382 close ( $fh );
383 In Apache 2.0 use:
385 use Apache2::Const qw(HTTP_OK)
387 my $fileName = 'someimage.jpg';
389 $m->clear_buffer();
390 $r->content_type( 'image/jpeg' );
391 $r->sendfile( $fileName )
392 $r->abort( Apache2::Const::HTTP_OK );
393 How do I put comments in components?
395 * Put general comments in the <%doc> section.
396 * In the <%init> and <%cleanup> sections, and in a <%perl> block, use
398 standard Perl comments ('#').
399 * In Mason 1.3 and beyond, use <%# %> for single or multi-line comments
401 anywhere outside of Perl sections. Before 1.3, this syntax isn't
402 guaranteed to work; one alternative is to begin a line with %#.
403 * If you are producing HTML, you can use standard HTML comments
405 delimited by <!-- -->. The difference is that these comments will
406 appear in the final output.
407 What's a good way to temporarily comment out code in a component?
409 For HTML, you might be tempted to surround the section with <!-- -->.
410 But be careful! Any code inside the section will still execute. Here's
411 a example of commenting out a call to an ad server:
412 <!-- temporarily comment out
414 <& FetchAd &>
415 -->
416 The ad will still be fetched and counted, but not displayed!
418 A better way to block out a section is if (0):
420 % if (0) {
422 ...
423 % }
424 Code blocked out in this way will neither be executed nor displayed,
426 and multiple if (0) blocks can be nested inside each other (unlike HTML
427 comments).
428 Another way to block out code is with a <%doc> tag or a <%# %> comment,
430 although these not cannot be nested.
431 How can I capture the output of a component (and modify it, etc.) instead
433 of having it automatically output?
434 Use $m->scomp, documented in the Request manual:
435 Can I use globals in components?
437 All HTML::Mason components run in the same package
438 (HTML::Mason::Commands), so if you set a global variable in one you'll
439 be able to read it in all the others. The only problem is that Mason by
440 default parses components with strict mode on, so you'll get a warning
441 about the global (and Mason considers all such warnings fatal). To
442 avoid errors, simply declare your globals via the MasonAllowGlobals
443 parameter.
444 PerlSetVar MasonAllowGlobals $dbh
446 PerlAddVar MasonAllowGlobals $user
447 If you have a handler.pl file, you can also declare global variables in
449 the handler() subroutine as long as you explicitly put them in the
450 HTML::Mason::Commands package.
451 package HTML::Mason::Commands;
453 use vars qw(...);
454 or use the Parser allow_globals parameter.
456 Alternatively you can turn off strict entirely by passing:
458 use_strict => 0
460 when you create the Parser object. Then you can use all the globals you
462 want. Doing this is terribly silly, however, and is bound to get you in
463 trouble down the road.
464 How do I share variables between components?
466 First, you can pass variables from one component to another.
467 Second, you can use globals. All components run in the same package
469 (HTML::Mason::Commands as of this writing), so globals in this package
470 are visible to all components. See the previous question.
471 There is no way to share a variable between just a few components; this
473 is a limitation of Perl's scoping rules. You can make a variable
474 /visible/ to only certain components using 'our' declarations:
475 <%once>
477 our ($shared_var);
478 </%once>
479 See the Perl documentation on 'our' to make sure you understand what
481 this is doing.
482 The <%shared> section is /not/ for sharing variables among different
484 file components. It is for sharing variables among the subcomponents
485 and methods of a single file component.
486 Why does the order of output get mixed up when I use print or $r->print?
488 This should no longer happen with Mason 1.10+. For those users still
489 using older versions of Mason, read the following:
490 Since your server is most likely in batch mode, all Mason output gets
492 buffered til the end of the request. print and $r->print circumvent the
493 buffer and thus come out before other Mason output.
494 Solution: don't use print or $r->print. Use $m->out if you must output
496 inside a Perl section. See the section on output mode in the
497 Administrator's Guide.
498 and the section on $m->out in the Request manual.
500 Why doesn't my <%cleanup> code run every time the component runs?
502 A <%cleanup> block is equivalent to a "<%perl>" block at the end of the
503 component. This means it will NOT execute if the component explicitly
504 returns, or if an abort or error occurs in that component or one of its
505 children.
506 If you need code that is guaranteed to run when the component or
508 request exits, consider using a mod_perl cleanup handler, or creating a
509 custom class with a DESTROY method.
510 Is <%args> exactly like %ARGS, and do I need to worry about it?
512 Mason allows you to predeclare arguments to components by specifying
513 variables to hold those arguments in an <%args></%args> section.
514 Because these are perl variables that you are predeclaring, they must
515 have legal perl identifier names -- they can't, for example, contain
516 periods.
517 If you want to pass arguments that are not identified with legal perl
519 names, you must manually pull those arguments out of the %ARGS hash
520 that mod_perl sets up for you. Why would you want to name your
521 arguments un-legally, you ask? Well, just for starters, the form input
522 element <input type="image" name="clickable"> will pass arguments
523 clickable.x and clickable.y to the action url automatically. If you
524 want to access these, you'd have to use $ARGS{clickable.x} and
525 $ARGS{clickable.y} rather than trying to declare them in <%args>.
526 Why does Mason display the wrong line numbers in errors?
528 Due to limitations in the 1.0x parser, Mason can only display line
529 numbers relative to object files.
530 In 1.1 and on, error line numbers correctly reflect the component
532 source.
533 How can I get a list of components matching a path pattern?
535 Use the resolver's glob_path method:
536 my @paths = $m->interp->resolver->glob_path('/some/comp/path/*');
538 This will work even with multiple component roots; you'll get a
540 combined list of all matching component paths in all component roots.
541 Can I access $m (the request object) from outside a component, e.g. inside
543 a subroutine?
544 In 1.1x and on, use
545 my $m = HTML::Mason::Request->instance;
547 Before 1.1x, use
549 my $m = HTML::Mason::Commands::m;
551 How can I make the |h escape flag work with my
553 Russian/Japanese/other-non-western encoding?
554 The |h flag is implemented with [=HTML::Entities::encode_html]. This
555 function, by default, escapes control chars and high-bit chars as well
556 as <, >, &, and ". This works well for ISO-8559-1 encoding but not with
557 other encodings.
558 To make |h escape just <, >, &, and ", which is often what people want,
560 put the following in your Apache configuration:
561 PerlSetVar MasonEscapeFlags "h => \&HTML::Mason::Escapes::basic_html_escape"
563 Or, in a top-level autohandler:
565 $m->interp->set_escape( h => \&HTML::Mason::Escapes::basic_html_escape );
567 When using multiple component roots, is there a way to explicitly call a
569 component in a specific root?
570 Multiple component roots were designed to work just like Perl's @INC.
571 A given component path matches exactly one file, the first file found
572 in an ordered search through the roots. There is no way to explicitly
573 ask for a file in a specific root.
574 People sometimes ask for the ability to do this. We feel it's a bad
576 idea because it would endanger the cleanliness of multiple component
577 roots in both behavior and implementation. As it stands now, the rules
578 are very easy to understand and the implementation is very clean and
579 isolated; only the resolver really needs know about multiple component
580 roots.
581 If you want to be able to explicitly refer to components in a given
583 root, put an extra subdirectory between the root and the components.
584 e.g. put your components in
585 /usr/local/htdocs/global/global/...
587 then add the root as
589 ['global', '/usr/local/htdocs/global']
591 Now you can prefix a path with /global to refer to any component in
593 that root.
594 Alternatively,
596 [http://search.cpan.org/dist/MasonX-Request-ExtendedCompRoot
597 MasonX::Request::ExtendedCompRoot] is a subclass of Mason that does
598 allow you to call components in a specific component root.
599 Is there a syntax checker like perl -c for components?
601 It is impossible to write a truly generic standalone script to syntax
602 check components, because components rely on certain globals and
603 modules to be present in their environment. Mason may report compile
604 errors from such a script even though they would not occur in your
605 normal web environment.
606 The best you can do is write a standalone script that mimics your web
608 environment as much as possible - in particular, declaring the same
609 globals and loading the same modules. Instead of actually executing
610 components, your script need only load them with $interp->load(). This
611 method will throw a fatal error if a component fails to load.
612
614 How do I access GET or POST arguments?
615 GET and POST arguments are automatically parsed and placed into named
616 component arguments just as if you had called the component with <& &>
617 or $m->comp. So you can get at GET/POST data by pre-declaring argument
618 names and/or using the %ARGS hash which is always available.
619 How can I access the raw content of a POST in a Mason component?
621 It depends on your environment as to what you can do.
622 Apache/mod_perl has an easier way of doing it than CGI/FCGi, which uses
624 FakeApache. As you can see from the comment, since FakeApache
625 implements read, I couldn't get it to be completely dynamic:
626 my $inputText;
628 # FakeApache implements read, so we can't automatically tell
629 # if we're in mod_perl or FCGI
630 if (0 && $r->can('read')){
631 $r->read( $inputText, $r->headers_in->{'Content-length'} );
632 }
633 else {
634 my %params = $r->params;
635 my $posted_content = $params{POSTDATA} || $params{keywords};
636 $posted_content ||= join '', %params if ($r->method eq 'POST');
637 $posted_content = join '', @$posted_content if (ref $posted_content eq 'ARRAY');
638 $inputText = $posted_content
639 }
640 -- Gareth Kirwan
642 Probably $r->params does not work. there is no such method in 'man
644 Apache'
645 -- Rajesh Kumar Mallah.
647 What happens if I include query args in a POST?
649 As of Mason 1.01, query string and POST arguments are always combined.
650 Should I use CGI.pm to read GET/POST arguments?
652 No! HTML::Mason automatically parses GET/POST arguments and places them
653 in declared component arguments and %ARGS (see previous question). If
654 you create a CGI object in the usual way for a POST request, it will
655 hang the process trying to read $r->content a second time.
656 Can I use CGI.pm to output HTML constructs?
658 Yes. To get a new CGI object, use
659 my $query = new CGI('');
661 You have to give the empty string argument or CGI will try to read
663 GET/POST arguments.
664 To print HTML constructs returned by CGI functions, just enclose them
666 in <%%>, e.g.
667 <% $query->radio_group(...) %>
669 How do I modify the outgoing HTTP headers?
671 Use the usual Apache.pm functions, such as $r->header_out. See the
672 "Sending HTTP Headers" section in the Component Developer's Guide.
673 How do I do an external redirect?
675 In Mason 1.0x, use code like this:
676 $m->clear_buffer;
678 # The next two lines are necessary to stop Apache from re-reading
679 # POSTed data.
680 $r->method('GET');
681 $r->headers_in->unset('Content-length');
682 $r->content_type('text/html');
683 $r->header_out('Location' => $location);
684 $m->abort(301);
685 In Mason 1.1x, use the [=$m->redirect] method.
687 See the next question if your redirect isn't producing the right status
689 code.
690 When trying to use $m->redirect I get 'Can't locate object method
692 "redirect" via package "HTML::Mason::!ApacheHandler"'.
693 $m->redirect is supported only in Mason 1.1x and on. Check your Mason
694 version by putting
695 Version = <% $HTML::Mason::VERSION %>
697 in a component.
699 Why isn't my status code reaching users' browsers?
701 If you are using a handler.pl, your handler() routine should always
702 return the error code that handle_request($r) produces. Otherwise,
703 things like $m->abort() will not work correctly. So a very, very simple
704 handler() routine would look like this:
705 sub handler {
707 my $r = shift;
708 $ah->handle_request($r);
709 }
710 If you are using $m->abort or $m->redirect and there is an eval()
712 wrapped directly or indirectly around the call, you must take care to
713 propagate abort exceptions after the eval(). This looks like:
714 eval { $m->comp('...') };
716 if ($@) {
717 if ($m->aborted) {
718 die $@;
719 } else {
720 # deal with non-abort exceptions
721 }
722 }
723 How can I handle file uploads under Mason?
725 The basic HTML for an upload form looks like:
726 <form action="..." method="post" enctype="multipart/form-data">
728 Upload new file:
729 <input name="userfile" type="file" class="button">
730 <input type="submit" value="Upload">
731 The way you handle the submission depends on which args method you
733 chose for the !ApacheHandler class.
734 Under the 'CGI' method (default for 1.0x), you can use the
736 [=$m->cgi_object] method to retrieve a CGI.pm object which can be used
737 to retrieve the uploaded file. Here is an example using the 'CGI'
738 method:
739 <%init>
741 my $query = $m->cgi_object;
742 # get a filehandle for the uploaded file
744 my $fh = $query->upload('userfile');
745 # print out the contents of the uploaded file
747 while (<$fh>) {
748 print;
749 }
750 close($fh);
751 </%init>
752 Please see the [CGI.pm
754 http://search.cpan.org/~lds/CGI.pm-3.05/CGI.pm#CREATING_A_FILE_UPLOAD_FIELD
755 documentation] for more details.
756 Under the 'mod_perl' method (default for 1.1x), the request object
758 available as [=$r] in your components will be an object in the
759 Apache::Request class (as opposed to the Apache class). This object is
760 capable of returning Apache::Upload objects for parameters which were
761 file uploads. Please see the [Apache::Request
762 http://search.cpan.org/~joesuf/libapreq-1.3/Request/Request.pm#Apache%3A%3AUpload_METHODS
763 documentation] for more details. Here is an example using the
764 'mod_perl' method:
765 <%init>
767 # NOTE: If you are using libapreq2 + mod_perl2 + Apache 2,
769 # you will need to uncomment the following line:
770 # use Apache::Upload;
771 # you can store the file's contents in a scalar
773 my $file_contents;
774 # create an Apache::Upload object
776 my $upload = $r->upload;
777 # get a filehandle for the uploaded file
779 my $upload_fh = $upload->fh;
780 while(<$upload_fh>) {
782 # loop through the file and copy each line to $file_contents
783 $file_contents .= $_;
784 }
785 close($upload_fh);
786 </%init>
787 For more information on how to manually set the args method, see the
789 !ApacheHandler documentation.
790 If you are using CGI.pm, there are some configuration issues to be
792 aware of. CGI.pm needs a tmp directory, and you probably want to be
793 able to specify what that directory is.
794 Try doing this in your httpd.conf or handler.pl:
796 <Perl>
798 use CGI qw(-private_tempfiles);
799 </Perl>
800 You must do this _before_ you load either the HTML::Mason or
802 HTML::Mason::!ApacheHandler modules.
803 That may change which directories CGI tries to use.
805 You could also try
807 $CGI::TempFile::TMPDIRECTORY = '/tmp';
809 during startup, either in your httpd.conf or handler.pl
811 The root of the problem is probably that the temp directory is being
813 chosen when the module loads uring server startup while its still root.
814 It sees it can write to /usr/tmp and is happy. Then when actually
815 running as nobody it dies.
816 I bet Lincoln would welcome a patch (hint, hint). One solution would be
818 to check if you're running under mod_perl and you're root. If so, then
819 check Apache->server->uid and see if that id can write to the temp
820 directory too.
821 How can I redirect the current request to be a file download?
823 A detailed explanation is provided in ForceFileDownload.
824 How can I manipulate cookies?
826 You can use the helpful modules Apache::Cookie and CGI::Cookie. It's
827 also fairly easy to roll your own cookie-manipulation functions, using
828 the methods provided by the $r global.
829 One thing to avoid: the combination of CGI::Cookie, Apache::Request,
831 and POST requests has caused people problems. It seems that
832 Apache::Cookie and Apache::Request make a better pair.
833 How can I populate form values automatically?
835 Several CPAN modules provide form-filling capabilities.
836 HTML::!FillInForm is one good choice and works well with Mason. Here's
837 a sample code snippet:
838 <%filter>
840 $_ = HTML::FillInForm->new->fill(scalarref => \$_, fdat => \%ARGS );
841 </%filter>
842 This will work for any component that contains a complete form in its
844 output.
845 If you are using Apache::Request to process incoming arguments under
847 mod_perl (the default as of 1.10), then you can also do this:
848 <%filter>
850 use HTML::FillInForm;
851 $_ = HTML::FillInForm->new->fill(scalarref => \$_, fobject => $r );
852 </%filter>
853 These two examples are slightly different from each other, in that each
855 makes a different set of parameters available to HTML::!FillInForm. In
856 the first example, the arguments used are those that were explicitly
857 passed to the component. In the second example, the arguments are those
858 that were passed in the initial HTTP request. Of course, variations on
859 this are possible by mixing and matching %ARGS, $m->request_args,
860 $m->caller_args, and so on.
861
863 What else do I need to use Mason?
864 If you are planning on using Mason in a web environment with the Apache
865 webserver, you'll need a working copy of Apache and mod_perl installed.
866 Make sure that your mod_perl installation works correctly before trying
867 to get Mason working. Also, if you are running RedHat Linux, beware the
868 mod_perl RPMs that ship with RedHat. They were unreliable for a very
869 long time, and their current state is still murky.
870 What platforms does Mason run on?
872 Because Mason consists of only Perl code, it should work anywhere Perl
873 runs (including most Unix and Win32 variants). If it doesn't work on
874 your operating system, let us know.
875 Can I run Mason outside a web server?
877 Yes, in fact Mason can be useful for generating a set of web pages
878 offline, as a general templating tool, or even as a code generator for
879 another language. See the "Standalone Mode" section of the Interpreter
880 manual.
881 Can I run Mason via CGI?
883 Yes. See "Using Mason from a CGI script" in the Interpreter manual.
884 The examples in the docs requires that you have Mason 1.10+ installed.
886 Note that running Mason under CGI (or other non-persistent
888 environments) will entail a substantial performance hit, since the perl
889 interpreter will have to load, load up Mason and its supporting modules
890 for every CGI execution. Using mod_perl or similar persistent
891 environments (SpeedyCGI, FastCGI, etc.) avoids this performance
892 bottleneck.
893 Can I use Mason with Apache/mod_perl 2.0?
895 Yes, as of Mason 1.27 (released 10/28/2004), there is support for
896 Apache/mod_perl 2.0 in the core Mason code. You may find other hints at
897 ApacheModPerl2.
898 Where can I find a web host supporting Mason?
900 Please check the [Hosting] page for a list of hosting providers
901 supporting HTML::Mason. You may also be interested in the list of
902 [http://perl.apache.org/help/isps.html ISPs supporting mod_perl],
903 however, there are reports that this document has not been maintained
904 in several years.
905 What does the error "Can't locate object method 'TIEHASH' via package
907 'Apache::Table'" mean?
908 It means that Mason is trying to use some of mod_perl's "table"
909 interface methods, like $r->dir_config->get('key') or the like. It's
910 failing because your mod_perl server wasn't compiled with support for
911 Apache's Table API.
912 To fix the problem, you'll have to recompile your server, adding the
914 PERL_TABLE_API=1 flag (or EVERYTHING=1).
915 If you can't recompile your server, you can edit the Mason source code.
917 Find a line in ApacheHandler.pm that looks like this (it's line 365 in
918 Mason 1.04):
919 my @val = $mod_perl::VERSION < 1.24 ? $c->dir_config($p) :
921 $c->dir_config->get($p);
922 and change it to:
924 my @val = Apache::perl_hook('TableApi') ? $c->dir_config->get($p) :
926 $c->dir_config($p);
927 Recent versions of Mason use that, or a variant of it.
929 What does the error "Can't locate Apache/Request.pm in @INC" m
931 You are using the default !ApacheHandler args_method ('mod_perl'),
932 which requires that you have installed the Apache::Request package
933 (libapreq).
934 You can either install libapreq, or change args_method to 'CGI'. The
936 latter is a bit slower and uses more memory.
937 Why am I getting segmentation faults (or silently failing on startup)?
939 There are a few known mod_perl issues that cause segmentation faults or
940 a silent failure on the part of Apache to start itself up. Though not
941 specific to Mason, they are worth keeping in mind:
942 * Are you using a dynamically-linked mod_perl? DSO mod_perl builds were
944 unstable for a long time, although they might finally be getting
945 better. Rebuild Apache with mod_perl linked statically and see if the
946 problem goes away. Also see
947 http://perl.apache.org/docs/1.0/guide/install.html#When_DSO_can_be_Used.
948 * Earlier versions of XML::Parser and Apache could conflict, because
950 both would statically compile in expat for XML parsing. This was fixed
951 as of Apache version 1.3.20 and XML::Parser 2.30, both of which can be
952 compiled against the same shared libexpat. You can also build Apache
953 with '--disable-rule=EXPAT'. Matthew Kennedy points out that 'If
954 "strings `which httpd` | grep -i xml" returns anything, you have this
955 problem.'
956 * Are you using Perl 5.6.0? Though not widespread, Perl 5.6.0 can
958 generate sporadic segmentation faults at runtime for some Perl code.
959 Specifically, evals of moderate complexity appear problematic. And,
960 since Mason uses lots of evals of moderate complexity, you can't avoid
961 them. If the two suggestions above don't solve your segfault problem
962 and you are running Perl 5.6.0, try upgrading to Perl 5.6.1.
963 MISCELLANEOUS
965 Where did the name come from?
967 It was inspired by a recent reading of Ken Follett's "The Pillars Of
968 The Earth." The book centered around the life of a mason, a builder of
969 great churches and buildings.
970 PERFORMANCE
972 Is Mason fast?
974 It is typically more than fast enough. 50-100 requests per second for a
975 simple component is typical for a reasonably modern Linux system. Some
976 simple benchmarking indicates that a Mason component is typically about
977 two to three times slower than an equivalent, hand-coded mod_perl
978 module.
979 Although benchmarks on [http://chamas.com/bench/ Apache Hello World!
981 benchmarks] site shows that Mason code is five (simple Hello World
982 page, [=hello.mas]) to ten (heavyweight template, [=h2000.mas]) times
983 slower than mod_perl solution.
984 Beware of "Hello World!" and other simple benchmarks. While these
986 benchmarks do a good job of measuring the setup and initialization time
987 for a package, they are typically not good measures of how a package
988 will perform in a complex, real-world application. As with any program,
989 the only way to know if it meets your requirements is to test it
990 yourself.
991 In general, however, if your application is fast enough in pure
993 mod_perl, it will most likely be fast enough under HTML::Mason as well.
994 How can I make my Mason application run faster?
996 The first thing you can do to optimize Mason performance is to optimize
997 your mod_perl installation. Consider implementing some of the tuning
998 tips recommended in mod_perl_tuning, which ships with every copy of
999 mod_perl.
1000 If your application still needs to run faster, consider using Mason's
1002 caching methods ($m->cache and $m->cache_self) to avoid regenerating
1003 dynamic content unnecessarily.
1004 Does Mason leak memory?
1006 Mason 1.10 and 1.11 do have a memory leak. This is fixed with 1.12.
1007 Earlier versions of Mason may leak some memory when using the
1008 "mod_perl" args_method, due to what is arguably a bug in
1009 Apache::Request.
1010 If you do find other memory leaks that are traceable to Mason, please
1012 check the known bugs list to make sure it hasn't already been reported.
1013 If it hasn't, simplify your handler.pl (if you have one) and the
1014 offending component as much as possible, and post your findings to the
1015 mason-users mailing list.
1016 Of course it is always possible for your own component code to leak,
1018 e.g. by creating and not cleaning up global variables. And mod_perl
1019 processes do tend to grow as they run because of "copy-on-write"
1020 shared-memory management. The mod_perl documentation and performance
1021 faq make good bedtime reading.
1022 If you are using RedHat's mod_perl RPM, or another DSO mod_perl
1024 installation, you will leak memory and should switch to a statically
1025 compiled mod_perl.
1026 SERVER CONFIGURATION
1028 Why are my config file changes not taking effect?
1030 1. After changing an httpd.conf or handler.pl or other server
1031 configuration file, make sure to do a FULL stop and start of the
1032 server. By default, the server will not reread Perl scripts or
1033 configuration when using "apachectl restart" or when sending a HUP or
1034 USR1 signal to the server.
1035 For more details see "Server Stopping and Restarting" in the mod_perl
1037 guide.
1038 2. Note that you cannot use Mason httpd parameters (MasonCompRoot,
1040 MasonErrorMode, etc.) and a handler.pl script that creates an
1041 ApacheHandler object at the same time. Depending on how you declare
1042 your PerlHandler, one or the other will always take precedence and the
1043 other will be ignored. For more details see "Site Configuration
1044 Methods" in the Admin manual.
1045 What filename extensions should I use for Mason components?
1047 Unlike many templating systems, Mason comes with no obvious filenaming
1048 standards. While this flexibility was initially considered an
1049 advantage, in retrospect it has led to the proliferation of a million
1050 different component extensions (.m, .mc, .mhtml, .mcomp, ...) and has
1051 made it more difficult for users to share components and configuration.
1052 The Mason team now recommends a filenaming scheme with extensions like
1054 .html, .txt, .pl for top-level components, and .mhtml, .mtxt, .mpl for
1055 internal (non-top-level) components.
1056 Whatever naming scheme you choose should ideally accomplish three
1058 things:
1059 * Distinguish top-level from internal components. This is obviously
1061 crucial for security.
1062 * Distinguish output components from those that compute and return
1064 values. This improves clarity, and forces the component writer to
1065 decide between outputting and returning, as it is bad style to do both.
1066 * Indicate the type of output of a component: text, html, xml, etc.
1068 This improves clarity, and helps browsers that ignore content-type
1069 headers (such as IE) process non-HTML pages correctly.
1070 Can I serve images through a HTML::Mason server?
1072 If you put images in the same directories as components, you need to
1073 make sure that the images don't get handled through HTML::Mason. The
1074 reason is that HTML::Mason will try to parse the images and may
1075 inadvertently find HTML::Mason syntax (e.g. "<%"). Most images will
1076 probably pass through successfully but a few will cause HTML::Mason
1077 errors.
1078 The simplest remedy is to have HTML::Mason decline image and other non-
1080 HTML requests, thus letting Apache serve them in the normal way.
1081 Another solution is to put all images in a separate directory; it is
1083 then easier to tell Apache to serve them in the normal way. See the
1084 next question.
1085 For performance reasons you should consider serving images from a
1087 completely separate (non-HTML::Mason) server. This will save a lot of
1088 memory as most requests will go to a thin image server instead of a
1089 large mod_perl server. See Stas Bekman's mod_perl guide and Vivek
1090 Khera's performance FAQ for a more detailed explanation. Both are
1091 available at http://perl.apache.org/
1092 How can I prevent a particular subdirectory from being handled by
1094 HTML::Mason?
1095 Suppose you have a directory under your document root, "/plain", and
1096 you would like to serve these files normally instead of using the
1097 HTML::Mason handler. Use a Location directive like:
1098 <Location /plain>
1100 SetHandler default-handler
1101 </Location>
1102 Or suppose you have a "/cgi-bin" that you want to process via CGI:
1104 <Location /cgi-bin>
1106 SetHandler cgi-script
1107 </Location>
1108 When you have multiple Location directives, the latest ones in the
1110 configuration have the highest precedence. So to combine the previous
1111 directive with a typical Mason directive:
1112 <Location />
1114 SetHandler perl-script
1115 PerlHandler HTML::Mason
1116 </Location>
1117 <Location /cgi-bin>
1119 SetHandler cgi-script
1120 </Location>
1121 More generally, you can use various Apache configuration methods to
1123 control which handlers are called for a given request. Ken Williams
1124 uses a FilesMatch directive to invoke Mason only on requests for
1125 ".html" files:
1126 <FilesMatch "\.html$">
1128 SetHandler perl-script
1129 PerlHandler HTML::Mason
1130 </FilesMatch>
1131 Or you could reverse this logic, and write FilesMatch directives just
1133 for gifs and jpegs, or whatever.
1134 If you are using a handler.pl, you can put the abort decision in your
1136 handler() routine. For example, a line like the following will produce
1137 the same end result as the <Location /plain> directive, above.
1138 return -1 if $r->uri() =~ m|^/plain|;
1140 However, performance will not be as good as the all-Apache
1142 configuration.
1143 Why am I getting 404 errors for pages that clearly exist?
1145 The filename that Apache has resolved to may not fall underneath the
1146 component root you specified when you created the interpreter in
1147 handler.pl. HTML::Mason requires the file to fall under the component
1148 root so that it can call it as a top-level component. (For various
1149 reasons, such as object file creation, HTML::Mason cannot treat files
1150 outside the component root as a component.)
1151 If you believe the file is in fact inside the component root and
1153 HTML::Mason is in error, it may be because you're referring to the
1154 Apache document root or the HTML::Mason component root through a
1155 symbolic link. The symbolic link may confuse HTML::Mason into thinking
1156 that two directories are different when they are in fact the same. This
1157 is a known "bug", but there is no obvious fix at this time. For now,
1158 you must refrain from using symbolic links in either of these
1159 configuration items.
1160 The same thing could also happen in any context with more than one way
1162 to specify a canonical filename. For example, on Windows, if your
1163 document root starts with "C:" and your component root starts with
1164 "c:", you might have this problem even though both paths should resolve
1165 to the same file.
1166 With Mason 0.895 and above, if you set Apache's LogLevel to warn, you
1168 will get appropriate warnings for these Mason-related 404s.
1169 Some of my pages are being served with a content type other than text/html.
1171 How do I get HTML::Mason to properly set the content type?
1172 HTML::Mason doesn't actually touch the content type -- it relies on
1173 Apache to set it correctly. You can affect how Apache sets your content
1174 type in the configuration files (e.g. srm.conf). The most common change
1175 you'll want to make is to add the line
1176 DefaultType text/html
1178 This indicates that files with no extension and files with an unknown
1180 extension should be treated as text/html. By default, Apache would
1181 treat them as text/plain.
1182 Microsoft Internet Explorer displays my page just fine, but Netscape or
1184 other browsers just display the raw HTML code.
1185 The most common cause of this is an incorrect content-type. All
1186 browsers are supposed to honor content-type, but MSIE tries to be smart
1187 and assumes content-type of text/html based on filename extension or
1188 page content.
1189 The solution is to set your default content-type to text/html. See
1191 previous question.
1192 My configuration prevents HTML::Mason from processing anything but html and
1194 text extensions, but I want to generate a dynamic image using
1195 HTML::Mason. How can I get HTML::Mason to set the correct MIME type?
1196 Use mod_perl's $r->content_type function to set the appropriate MIME
1197 type. This will allow you to output, for example, a GIF file, even if
1198 your component is called dynamicImage.html. However there's no
1199 guarantee that every browser (e.g. Internet Explorer) will respect your
1200 MIME type rather than your file extension. Make sure to test on
1201 multiple browsers.
1202 How do I bring in external modules?
1204 Use the PerlModule directive in your httpd.conf, or if you have a
1205 startup.pl file, put the 'use module' in there. If you want components
1206 to be able to refer to symbols exported by the module, however, you'll
1207 need to use the module inside the HTML::Mason::Commands package. See
1208 the "External modules" section of the Administrator's Guide.
1209 How do I adjust Perl's INC path so it can find my modules?
1211 You can do this:
1212 <Perl>
1214 use lib ...
1215 </Perl>
1216 or this:
1218 PerlSetEnv PERL5LIB /path/one:/path/two:...
1220 How do I use Mason in conjunction with UserDir to support Mason in user's
1222 home directories?
1223 The idea is to create one ApacheHandler for each user, dynamically. You
1224 will need to use a handler.pl or other wrapper code (see "Writing a
1225 Wrapper" in the Adminstrator's Manual).
1226 Outside your handler subroutine:
1228 # $user_regexp: a regexp that matches the root directory of Mason.
1230 # Make sure there is one arg in parens that represents
1231 # the actual username--the handler uses this.
1232 my $user_regexp = qr'/Users/([^/]*)/(?:public_html|Sites)';
1233 my %user_handlers;
1234 # Create base ApacheHandler object at startup.
1236 my $base_ah = new HTML::Mason::ApacheHandler( comp_root => $comp_root,
1237 data_dir => $data_dir );
1238 Inside your handler subroutine:
1240 sub handler
1242 {
1243 my $r=$_[0];
1244 ...
1245 #
1246 # Have a different handler for each home directory
1247 #
1248 my $curr_ah;
1249 my $filename = $r->filename();
1250 if($filename =~ m!$user_regexp!) {
1251 my $user_name = $1;
1252 $curr_ah = $user_handlers{$user_name};
1253 if(!$curr_ah) {
1254 $filename =~ m!($user_regexp)!;
1255 my $user_dir = $1;
1256 $curr_ah = new HTML::Mason::ApacheHandler(comp_root=>[[$user_name => $user_dir]],
1257 data_dir=>$data_dir);
1258 $user_handlers{$1} = $curr_ah;
1259 }
1260 } else {
1261 $curr_ah = $base_ah;
1262 }
1263 my $status = $curr_ah->handle_request($r);
1264 return $status;
1266 }
1267 How do I connect to a database from Mason?
1269 The short answer is that most any perl code that works outside Mason,
1270 for connecting to a database, should work inside a component. I
1271 sometimes do draft development and quick debugging with something like:
1272 <%once>
1274 use DBI;
1275 </%once>
1276 <%init>
1278 my $dbh = DBI->connect ( blah, blah );
1279 ...
1280 </%init>
1281 The long answer is, of course, longer. A good deal of thought should be
1283 put into how a web application talks to databases that it depends on,
1284 as these interconnections can easily be both performance bottlenecks
1285 and very un-robust.
1286 Most people use some sort of connection pooling -- opening and then re-
1288 using a limited number of database connections. The Apache::DBI module
1289 provides connection pooling that is reliable and nearly painless. If
1290 Apache::DBI has been use'd, DBI->connect() will transparently reuse an
1291 already open connections, if it can.
1292 The "right" place to ask Apache::DBI for database handles is often in a
1294 top level autohandler.
1295 For example:
1297 <%init>
1299 my $dbh = DBI->connect('dbi:mysq:somedb', 'user', 'pw');
1300 ... # other processing
1301 $m->call_next( %ARGS, dbh => $dbh );
1302 </%init>
1303 Alternately, $dbh could be a global variable which you set via
1305 MasonAllowGlobals.
1306 You can use Apache::DBI in your httpd.conf file quite easily simply by
1308 adding:
1309 PerlModule Apache::DBI
1311 If you want to do more with Apache::DBI, like call connect_on_init, you
1313 can use a <Perl> section
1314 <Perl>
1316 use Apache::DBI;
1317 Apache::DBI->connect_on_init('dbi:mysql:somedb', 'user', 'pw');
1318 Apache::DBI->setPingTimeOut('dbi:mysql:somedb', 0);
1319 </Perl>
1320 Others may simply use a handler.pl file. Georgiou Kiriakos writes:
1322 You can connect in the handler.pl - I find it convenient to setup a
1324 global $dbh in it. You just need to make sure you connect inside
1325 the handler subroutine (using Apache::DBI of course). This way a)
1326 each httpd gets it's own connection and b) each httpd reconnects if
1327 the database is recycled.
1328 Regardless of whether you set up global $dbh variables in handler.pl,
1330 the static sections of handler.pl should set up Apache::DBI stuff:
1331 # List of modules that you want to use from components (see Admin
1333 # manual for details)
1334 {
1335 package HTML::Mason::Commands;
1336 use Apache::DBI;
1337 # use'ing Apache::DBI here lets us connect from inside components
1338 # if we need to.
1339 # --
1340 # declare global variables, like $dbh, here as well.
1341 }
1342 # Configure database connection stuff
1344 my $datasource = "DBI:blah:blah";
1345 my $username = "user";
1346 my $password = "pass";
1347 my $attr = { RaiseError=>1 ,AutoCommit=>1 };
1348 Apache::DBI->connect_on_init($datasource, $username, $password, $attr);
1349 Apache::DBI->setPingTimeOut($datasource, 0);
1350 How come a certain piece of Perl code runs fine under "regular" perl, but
1352 fails under Mason?
1353 Mason is usually a red herring in this situation. Mason IS "regular"
1354 perl, with a very simple system to translate Mason component syntax to
1355 Perl code. You can look at the object files Mason creates for your
1356 components (in the obj/ subdirectory of the Mason data directory) to
1357 see the actual Perl code Mason generates.
1358 If something suddenly stops working when you place it in a Mason
1360 environment, the problem is far more likely to rest with the following
1361 environmental changes than with Mason itself:
1362 * With mod_perl, the server is running under a different user/group and
1364 thus has different permissions for the resource you're trying to access
1365 * With mod_perl, code can stay resident in the perl interpreter for a
1367 long time.
1368 * Your headers may be sent differently under mod_perl than under your
1370 previous CGI situation (or whatever it was)
1371 Mason does not have anything to do with sending mail, or accessing a
1373 database, or maintaining user accounts, or server authentication, so if
1374 your problems are in areas like these, your time will be better spent
1375 looking at other environmental changes like the ones mentioned above.
1376 I'm using HTML::Mason::!ApacheHandler and I have decline_dirs disabled and
1378 am using a dhandler to handle directory requests. But when a request
1379 comes in without the final slash after the directory name, relative
1380 links are broken. What gives?
1381 Mason has always incorrectly handled such directory requests; this
1382 issue will be resolved in the 1.3 release. The reason it will only be
1383 fixed in the next major version is that some folks may have come to
1384 rely on this functionality. So it's considered breaking backwards
1385 compatibility. But if you need it to do the right thing now, fear not!
1386 There are a number of workarounds to ensure that Apache adds a slash
1387 and redirects the browser to the appropriate URL. See
1388 HandlingDirectoriesWithDhandlers for all the juicy details.
1389 UPGRADING TO 1.1x
1391 After upgrading, I see this error whenever I load a page: "The following
1393 parameter was passed in the call to
1394 HTML::Mason::Component::FileBased->new() but was not listed in the
1395 validation options: create_time"
1396 Delete all of your object files.
1397 When I try to start my server I see an error like: "The resolver class your
1399 Interp object uses does not implement the apache_request_to_comp_path'
1400 method.
1401 This means that ApacheHandler cannot resolve requests.
1402 Are you using a handler.pl file created before version 1.10? Please
1404 see the handler.pl sample that comes with the latest version of Mason.
1405 You are explicitly creating an Interp object in your handler.pl and
1407 then passing that to ApacheHandler->new.
1408 Instead, simply pass all of your Interp parameters to
1410 ApacheHandler->new directly. The parameters will end up going where
1411 they belong.
1412 When I start Apache (or try to use Mason) I get an error like this: "The
1414 Parser module is no longer a part of HTML::Mason. Please see the Lexer
1415 and Compiler modules, its replacements."
1416 The Parser module is no longer used.
1417 I get an error like: "The following parameters were passed in the call to
1419 HTML::Mason::Container::new but were not listed in the validation
1420 options: error_format error_mode request_class resolver_class" when
1421 using ApacheHandler
1422 Do you have PerlFreshRestart turned on? Turn it off.
1423 See http://perl.apache.org/docs/1.0/guide/troubleshooting.html - "Evil
1425 things might happen when using PerlFreshRestart".
1426 I get an error like this: 'Can't locate object method "make_ah"
1428 package "Apache"' === We're not kidding. PerlFreshRestart is evil. Turn
1429 it off. See question above.
1430 I get: "Unknown config item 'comp_root'" or "Unknown config item
1432 'comp_root'" or something similar with ApacheHandler.
1433 Turn PerlFreshRestart off. Really.
1434 I get this with a custom handler.pl: 'Can't call method "handle_request" on
1436 an undefined value at ...'
1437 Just in case you weren't convinced that PerlFreshRestart is a bad idea,
1438 this should help convince you.
1439 After upgrading, I get this error for all my components: '<%' without
1441 matching '%>' ...
1442 The "perl_' prefix for Mason tags, like <%perl_args>, is no longer
1443 supported. Remove this prefix.
1444
1446 Where do I obtain HTML::Mason?
1447 HTML::Mason is available from CPAN (the Comprehensive Perl Archive
1448 Network). Details about CPAN are available at http://www.perl.com/. See
1449 the [FAQ:Installation] section of this document for tips on obtaining
1450 and installing Mason.
1451 Where can I ask questions about HTML::Mason?
1453 See ContactUs and MailingLists.
1454perl v5.34.0 2021-07-22 HTML::Mason::FAQ(3)