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

NAME

6       HTML::Mason::FAQ - Frequently asked questions
7

AUTOHANDLERS, METHODS, ATTRIBUTES, INHERITANCE

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
14   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
20       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
24   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
28   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
33       Consider a site with the following components:
34
35              /autohandler
36              /dhandler
37              /products/autohandler
38
39       and suppose a request comes in for /products/index.html. /dhandler will
40       handle the request but will still inherit from /autohandler.
41
42       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
47   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
54              <%method bgcolor>
55              <%init>
56              return $m->base_comp->attr('bgcolor');
57              <%init>
58              </%method>
59
60       Then replace every other
61
62              $m->base_comp->attr('bgcolor');
63
64       with
65
66              $m->base_comp->call_method('bgcolor')
67
68       or
69
70              <& SELF:bgcolor &>
71
72       Now you can leave the attribute definitions alone, but define a method
73       if and when you need a dynamically computed value.
74
75   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
79          /foo/bar/baz/autohandler
80          /foo/bar/autohandler
81          /foo/autohandler
82          /autohandler
83
84       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
91       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

CACHING

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
107       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
111       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
116       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
120       * 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
124       * 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
129       * 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
133       * 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
138       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
146   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
154       Some alternatives that have been suggested:
155
156       * 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
167       * 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
172       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
177   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
185   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
190   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
194       With Mason 1.1x and beyond, you can use the following idiom to say
195       ``expire when my component source file changes'':
196
197             $m->cache(...,
198               expire_if=>sub {
199                     (stat($m->current_comp->source_file))[9] > $_[0]->get_created_at
200               } )
201
202       With Mason <= 1.05, the idiom looks like:
203
204             $m->cache(...,
205                expire_if=>sub {
206                     (stat($m->current_comp->source_file))[9] > $_[0]
207                } )
208

COMPONENTS

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
214       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
218       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
223   How do components communicate with each other?
224       Components can return values to their callers, just like subroutines.
225
226       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
232       Of course, components can also return strings of text, arrays, hashes
233       or other arbitrarily complex perl data structures.
234
235   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
239       * the module will be used separately by every httpd child process,
240       costing both time and memory.
241
242       * it is difficult to keep track of all the modules being used on a
243       site.
244
245       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
251   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
256       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
261       Consider the following options:
262
263       * If the routine is going to display HTML, use a separate component or
264       a <%def> subcomponent.
265
266       * 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
272             <%once>
273             my $foo = sub {
274               ...
275             };
276             </%once>
277
278             ...
279
280             % $foo->()
281
282       * If the subroutine is of interest to more than just your component,
283       have you considered putting it in a module?
284
285       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
290   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
295       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
301       Often people expect the working directory to be the directory of the
302       current component. You can, instead, get that directory manually with
303
304              $m->current_comp->source_dir
305
306   How do I exit from all components including the ones that called me?
307       Use $m->abort, documented in the Request manual:
308
309   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
316       First, for components that only return a value and shouldn't output
317       *any* content, you should always use <%init>:
318
319             <%args>
320              $foo
321             </%args>
322
323             This content will be ignored.
324
325             <%init>
326              my $bar = $dbh->selectrow_array("SELECT bar FROM t WHERE foo=?", $foo);
327              return $bar;
328             </%init>
329
330       In components that do display content, there are various strategies. To
331       eliminate selected newlines, use the backslash. For example,
332
333              <PRE>
334              foo\
335              % if (1) {
336              bar\
337              % }
338              baz
339              </PRE>
340
341       outputs "foobarbaz" with no newlines.
342
343       To prevent a component from outputting any newlines, use a filter:
344
345              <%filter>
346              s/\n//g;
347              </%filter>
348
349       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
353             <%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
363       At some point Mason will probably offer a "reasonable" whitespace
364       removal feature, controlled by parameter.
365
366   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
372       In Apache 1.0 a real working example looks like this:
373
374          my $fh;
375          my $fileName = '/tmp/mypic.jpg';
376          open ( $fh, $fileName ) or die $!;
377
378          $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
384       In Apache 2.0 use:
385
386          use Apache2::Const qw(HTTP_OK)
387
388          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
394   How do I put comments in components?
395       * Put general comments in the <%doc> section.
396
397       * In the <%init> and <%cleanup> sections, and in a <%perl> block, use
398       standard Perl comments ('#').
399
400       * 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
404       * 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
408   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
413             <!-- temporarily comment out
414             <& FetchAd &>
415             -->
416
417       The ad will still be fetched and counted, but not displayed!
418
419       A better way to block out a section is if (0):
420
421             % if (0) {
422               ...
423             % }
424
425       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
429       Another way to block out code is with a <%doc> tag or a <%# %> comment,
430       although these not cannot be nested.
431
432   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
436   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
445             PerlSetVar MasonAllowGlobals $dbh
446             PerlAddVar MasonAllowGlobals $user
447
448       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
452             package HTML::Mason::Commands;
453             use vars qw(...);
454
455       or use the Parser allow_globals parameter.
456
457       Alternatively you can turn off strict entirely by passing:
458
459             use_strict => 0
460
461       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
465   How do I share variables between components?
466       First, you can pass variables from one component to another.
467
468       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
472       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
476               <%once>
477               our ($shared_var);
478               </%once>
479
480       See the Perl documentation on 'our' to make sure you understand what
481       this is doing.
482
483       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
487   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
491       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
495       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
499       and the section on $m->out in the Request manual.
500
501   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
507       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
511   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
518       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
527   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
531       In 1.1 and on, error line numbers correctly reflect the component
532       source.
533
534   How can I get a list of components matching a path pattern?
535       Use the resolver's glob_path method:
536
537             my @paths = $m->interp->resolver->glob_path('/some/comp/path/*');
538
539       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
542   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
546             my $m = HTML::Mason::Request->instance;
547
548       Before 1.1x, use
549
550             my $m = HTML::Mason::Commands::m;
551
552   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
559       To make |h escape just <, >, &, and ", which is often what people want,
560       put the following in your Apache configuration:
561
562              PerlSetVar  MasonEscapeFlags  "h => \&HTML::Mason::Escapes::basic_html_escape"
563
564       Or, in a top-level autohandler:
565
566              $m->interp->set_escape( h => \&HTML::Mason::Escapes::basic_html_escape );
567
568   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
575       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
582       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
586           /usr/local/htdocs/global/global/...
587
588       then add the root as
589
590           ['global', '/usr/local/htdocs/global']
591
592       Now you can prefix a path with /global to refer to any component in
593       that root.
594
595       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
600   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
607       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

HTTP AND HTML

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
620   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
623       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
627               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
641       -- Gareth Kirwan
642
643       Probably $r->params does not work. there is no such method in 'man
644       Apache'
645
646       -- Rajesh Kumar Mallah.
647
648   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
651   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
657   Can I use CGI.pm to output HTML constructs?
658       Yes. To get a new CGI object, use
659
660             my $query = new CGI('');
661
662       You have to give the empty string argument or CGI will try to read
663       GET/POST arguments.
664
665       To print HTML constructs returned by CGI functions, just enclose them
666       in <%%>, e.g.
667
668             <% $query->radio_group(...) %>
669
670   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
674   How do I do an external redirect?
675       In Mason 1.0x, use code like this:
676
677               $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
686       In Mason 1.1x, use the [=$m->redirect] method.
687
688       See the next question if your redirect isn't producing the right status
689       code.
690
691   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
696              Version = <% $HTML::Mason::VERSION %>
697
698       in a component.
699
700   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
706             sub handler {
707               my $r = shift;
708               $ah->handle_request($r);
709             }
710
711       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
715              eval { $m->comp('...') };
716              if ($@) {
717                 if ($m->aborted) {
718                     die $@;
719                 } else {
720                     # deal with non-abort exceptions
721                 }
722              }
723
724   How can I handle file uploads under Mason?
725       The basic HTML for an upload form looks like:
726
727              <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
732       The way you handle the submission depends on which args method you
733       chose for the !ApacheHandler class.
734
735       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
740         <%init>
741         my $query = $m->cgi_object;
742
743         # get a filehandle for the uploaded file
744         my $fh = $query->upload('userfile');
745
746         # print out the contents of the uploaded file
747         while (<$fh>) {
748               print;
749         }
750         close($fh);
751         </%init>
752
753       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
757       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
766         <%init>
767
768          # NOTE: If you are using libapreq2 + mod_perl2 + Apache 2,
769          # you will need to uncomment the following line:
770          # use Apache::Upload;
771
772          # you can store the file's contents in a scalar
773          my $file_contents;
774
775          # create an Apache::Upload object
776          my $upload = $r->upload;
777
778          # get a filehandle for the uploaded file
779          my $upload_fh = $upload->fh;
780
781          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
788       For more information on how to manually set the args method, see the
789       !ApacheHandler documentation.
790
791       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
795       Try doing this in your httpd.conf or handler.pl:
796
797             <Perl>
798             use CGI qw(-private_tempfiles);
799             </Perl>
800
801       You must do this _before_ you load either the HTML::Mason or
802       HTML::Mason::!ApacheHandler modules.
803
804       That may change which directories CGI tries to use.
805
806       You could also try
807
808             $CGI::TempFile::TMPDIRECTORY = '/tmp';
809
810       during startup, either in your httpd.conf or handler.pl
811
812       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
817       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
822   How can I manipulate cookies?
823       You can use the helpful modules Apache::Cookie and CGI::Cookie. It's
824       also fairly easy to roll your own cookie-manipulation functions, using
825       the methods provided by the $r global.
826
827       One thing to avoid: the combination of CGI::Cookie, Apache::Request,
828       and POST requests has caused people problems. It seems that
829       Apache::Cookie and Apache::Request make a better pair.
830
831   How can I populate form values automatically?
832       Several CPAN modules provide form-filling capabilities.
833       HTML::!FillInForm is one good choice and works well with Mason. Here's
834       a sample code snippet:
835
836            <%filter>
837            $_ = HTML::FillInForm->new->fill(scalarref => \$_, fdat => \%ARGS );
838            </%filter>
839
840       This will work for any component that contains a complete form in its
841       output.
842
843       If you are using Apache::Request to process incoming arguments under
844       mod_perl (the default as of 1.10), then you can also do this:
845
846            <%filter>
847            use HTML::FillInForm;
848            $_ = HTML::FillInForm->new->fill(scalarref => \$_, fobject => $r );
849            </%filter>
850
851       These two examples are slightly different from each other, in that each
852       makes a different set of parameters available to HTML::!FillInForm. In
853       the first example, the arguments used are those that were explicitly
854       passed to the component. In the second example, the arguments are those
855       that were passed in the initial HTTP request. Of course, variations on
856       this are possible by mixing and matching %ARGS, $m->request_args,
857       $m->caller_args, and so on.
858

INSTALLATION

860   What else do I need to use Mason?
861       If you are planning on using Mason in a web environment with the Apache
862       webserver, you'll need a working copy of Apache and mod_perl installed.
863       Make sure that your mod_perl installation works correctly before trying
864       to get Mason working. Also, if you are running RedHat Linux, beware the
865       mod_perl RPMs that ship with RedHat. They were unreliable for a very
866       long time, and their current state is still murky.
867
868   What platforms does Mason run on?
869       Because Mason consists of only Perl code, it should work anywhere Perl
870       runs (including most Unix and Win32 variants). If it doesn't work on
871       your operating system, let us know.
872
873   Can I run Mason outside a web server?
874       Yes, in fact Mason can be useful for generating a set of web pages
875       offline, as a general templating tool, or even as a code generator for
876       another language. See the "Standalone Mode" section of the Interpreter
877       manual.
878
879   Can I run Mason via CGI?
880       Yes. See "Using Mason from a CGI script" in the Interpreter manual.
881
882       The examples in the docs requires that you have Mason 1.10+ installed.
883
884       Note that running Mason under CGI (or other non-persistent
885       environments) will entail a substantial performance hit, since the perl
886       interpreter will have to load, load up Mason and its supporting modules
887       for every CGI execution. Using mod_perl or similar persistent
888       environments (SpeedyCGI, FastCGI, etc.) avoids this performance
889       bottleneck.
890
891   Can I use Mason with Apache/mod_perl 2.0?
892       Yes, as of Mason 1.27 (released 10/28/2004), there is support for
893       Apache/mod_perl 2.0 in the core Mason code. You may find other hints at
894       ApacheModPerl2.
895
896   Where can I find a web host supporting Mason?
897       Please check the [Hosting] page for a list of hosting providers
898       supporting HTML::Mason.  You may also be interested in the list of
899       [http://perl.apache.org/help/isps.html ISPs supporting mod_perl],
900       however, there are reports that this document has not been maintained
901       in several years.
902
903   What does the error "Can't locate object method 'TIEHASH' via package
904       'Apache::Table'" mean?
905       It means that Mason is trying to use some of mod_perl's "table"
906       interface methods, like $r->dir_config->get('key') or the like. It's
907       failing because your mod_perl server wasn't compiled with support for
908       Apache's Table API.
909
910       To fix the problem, you'll have to recompile your server, adding the
911       PERL_TABLE_API=1 flag (or EVERYTHING=1).
912
913       If you can't recompile your server, you can edit the Mason source code.
914       Find a line in ApacheHandler.pm that looks like this (it's line 365 in
915       Mason 1.04):
916
917             my @val = $mod_perl::VERSION < 1.24 ? $c->dir_config($p) :
918                $c->dir_config->get($p);
919
920       and change it to:
921
922             my @val = Apache::perl_hook('TableApi') ? $c->dir_config->get($p) :
923                $c->dir_config($p);
924
925       Recent versions of Mason use that, or a variant of it.
926
927   What does the error "Can't locate Apache/Request.pm in @INC" m
928       You are using the default !ApacheHandler args_method ('mod_perl'),
929       which requires that you have installed the Apache::Request package
930       (libapreq).
931
932       You can either install libapreq, or change args_method to 'CGI'. The
933       latter is a bit slower and uses more memory.
934
935   Why am I getting segmentation faults (or silently failing on startup)?
936       There are a few known mod_perl issues that cause segmentation faults or
937       a silent failure on the part of Apache to start itself up. Though not
938       specific to Mason, they are worth keeping in mind:
939
940       * Are you using a dynamically-linked mod_perl? DSO mod_perl builds were
941       unstable for a long time, although they might finally be getting
942       better. Rebuild Apache with mod_perl linked statically and see if the
943       problem goes away. Also see
944       http://perl.apache.org/docs/1.0/guide/install.html#When_DSO_can_be_Used.
945
946       * Earlier versions of XML::Parser and Apache could conflict, because
947       both  would statically compile in expat for XML parsing. This was fixed
948       as of Apache version 1.3.20 and XML::Parser 2.30, both of which can be
949       compiled against the same shared libexpat. You can also build Apache
950       with '--disable-rule=EXPAT'. Matthew Kennedy points out that 'If
951       "strings `which httpd` | grep -i xml" returns anything, you have this
952       problem.'
953
954       * Are you using Perl 5.6.0? Though not widespread, Perl 5.6.0 can
955       generate sporadic segmentation faults at runtime for some Perl code.
956       Specifically, evals of moderate complexity appear problematic. And,
957       since Mason uses lots of evals of moderate complexity, you can't avoid
958       them. If the two suggestions above don't solve your segfault problem
959       and you are running Perl 5.6.0, try upgrading to Perl 5.6.1.
960
961       MISCELLANEOUS
962
963   Where did the name come from?
964       It was inspired by a recent reading of Ken Follett's "The Pillars Of
965       The Earth." The book centered around the life of a mason, a builder of
966       great churches and buildings.
967
968       PERFORMANCE
969
970   Is Mason fast?
971       It is typically more than fast enough. 50-100 requests per second for a
972       simple component is typical for a reasonably modern Linux system. Some
973       simple benchmarking indicates that a Mason component is typically about
974       two to three times slower than an equivalent, hand-coded mod_perl
975       module.
976
977       Although benchmarks on [http://chamas.com/bench/ Apache Hello World!
978       benchmarks] site shows that Mason code is five (simple Hello World
979       page, [=hello.mas]) to ten (heavyweight template, [=h2000.mas]) times
980       slower than mod_perl solution.
981
982       Beware of "Hello World!" and other simple benchmarks. While these
983       benchmarks do a good job of measuring the setup and initialization time
984       for a package, they are typically not good measures of how a package
985       will perform in a complex, real-world application. As with any program,
986       the only way to know if it meets your requirements is to test it
987       yourself.
988
989       In general, however, if your application is fast enough in pure
990       mod_perl, it will most likely be fast enough under HTML::Mason as well.
991
992   How can I make my Mason application run faster?
993       The first thing you can do to optimize Mason performance is to optimize
994       your mod_perl installation. Consider implementing some of the tuning
995       tips recommended in mod_perl_tuning, which ships with every copy of
996       mod_perl.
997
998       If your application still needs to run faster, consider using Mason's
999       caching methods ($m->cache and $m->cache_self) to avoid regenerating
1000       dynamic content unnecessarily.
1001
1002   Does Mason leak memory?
1003       Mason 1.10 and 1.11 do have a memory leak. This is fixed with 1.12.
1004       Earlier versions of Mason may leak some memory when using the
1005       "mod_perl" args_method, due to what is arguably a bug in
1006       Apache::Request.
1007
1008       If you do find other memory leaks that are traceable to Mason, please
1009       check the known bugs list to make sure it hasn't already been reported.
1010       If it hasn't, simplify your handler.pl (if you have one) and the
1011       offending component as much as possible, and post your findings to the
1012       mason-users mailing list.
1013
1014       Of course it is always possible for your own component code to leak,
1015       e.g. by creating and not cleaning up global variables. And mod_perl
1016       processes do tend to grow as they run because of "copy-on-write"
1017       shared-memory management. The mod_perl documentation and performance
1018       faq make good bedtime reading.
1019
1020       If you are using RedHat's mod_perl RPM, or another DSO mod_perl
1021       installation, you will leak memory and should switch to a statically
1022       compiled mod_perl.
1023
1024       SERVER CONFIGURATION
1025
1026   Why are my config file changes not taking effect?
1027       1. After changing an httpd.conf or handler.pl or other server
1028       configuration file, make sure to do a FULL stop and start of the
1029       server. By default, the server will not reread Perl scripts or
1030       configuration when using "apachectl restart" or when sending a HUP or
1031       USR1 signal to the server.
1032
1033       For more details see "Server Stopping and Restarting" in the mod_perl
1034       guide.
1035
1036       2. Note that you cannot use Mason httpd parameters (MasonCompRoot,
1037       MasonErrorMode, etc.) and a handler.pl script that creates an
1038       ApacheHandler object at the same time. Depending on how you declare
1039       your PerlHandler, one or the other will always take precedence and the
1040       other will be ignored. For more details see "Site Configuration
1041       Methods" in the Admin manual.
1042
1043   What filename extensions should I use for Mason components?
1044       Unlike many templating systems, Mason comes with no obvious filenaming
1045       standards. While this flexibility was initially considered an
1046       advantage, in retrospect it has led to the proliferation of a million
1047       different component extensions (.m, .mc, .mhtml, .mcomp, ...) and has
1048       made it more difficult for users to share components and configuration.
1049
1050       The Mason team now recommends a filenaming scheme with extensions like
1051       .html, .txt, .pl for top-level components, and .mhtml, .mtxt, .mpl for
1052       internal (non-top-level) components.
1053
1054       Whatever naming scheme you choose should ideally accomplish three
1055       things:
1056
1057       * Distinguish top-level from internal components. This is obviously
1058       crucial for security.
1059
1060       * Distinguish output components from those that compute and return
1061       values. This improves clarity, and forces the component writer to
1062       decide between outputting and returning, as it is bad style to do both.
1063
1064       * Indicate the type of output of a component: text, html, xml, etc.
1065       This improves clarity, and helps browsers that ignore content-type
1066       headers (such as IE) process non-HTML pages correctly.
1067
1068   Can I serve images through a HTML::Mason server?
1069       If you put images in the same directories as components, you need to
1070       make sure that the images don't get handled through HTML::Mason. The
1071       reason is that HTML::Mason will try to parse the images and may
1072       inadvertently find HTML::Mason syntax (e.g. "<%"). Most images will
1073       probably pass through successfully but a few will cause HTML::Mason
1074       errors.
1075
1076       The simplest remedy is to have HTML::Mason decline image and other non-
1077       HTML requests, thus letting Apache serve them in the normal way.
1078
1079       Another solution is to put all images in a separate directory; it is
1080       then easier to tell Apache to serve them in the normal way. See the
1081       next question.
1082
1083       For performance reasons you should consider serving images from a
1084       completely separate (non-HTML::Mason) server. This will save a lot of
1085       memory as most requests will go to a thin image server instead of a
1086       large mod_perl server. See Stas Bekman's mod_perl guide and Vivek
1087       Khera's performance FAQ for a more detailed explanation. Both are
1088       available at http://perl.apache.org/
1089
1090   How can I prevent a particular subdirectory from being handled by
1091       HTML::Mason?
1092       Suppose you have a directory under your document root, "/plain", and
1093       you would like to serve these files normally instead of using the
1094       HTML::Mason handler. Use a Location directive like:
1095
1096             <Location /plain>
1097               SetHandler default-handler
1098             </Location>
1099
1100       Or suppose you have a "/cgi-bin" that you want to process via CGI:
1101
1102             <Location /cgi-bin>
1103               SetHandler cgi-script
1104             </Location>
1105
1106       When you have multiple Location directives, the latest ones in the
1107       configuration have the highest precedence. So to combine the previous
1108       directive with a typical Mason directive:
1109
1110             <Location />
1111               SetHandler perl-script
1112               PerlHandler HTML::Mason
1113             </Location>
1114
1115             <Location /cgi-bin>
1116               SetHandler cgi-script
1117             </Location>
1118
1119       More generally, you can use various Apache configuration methods to
1120       control which handlers are called for a given request. Ken Williams
1121       uses a FilesMatch directive to invoke Mason only on requests for
1122       ".html" files:
1123
1124              <FilesMatch  "\.html$">
1125                SetHandler perl-script
1126                PerlHandler HTML::Mason
1127              </FilesMatch>
1128
1129       Or you could reverse this logic, and write FilesMatch directives just
1130       for gifs and jpegs, or whatever.
1131
1132       If you are using a handler.pl, you can put the abort decision in your
1133       handler() routine. For example, a line like the following will produce
1134       the same end result as the <Location /plain> directive, above.
1135
1136             return -1 if $r->uri() =~ m|^/plain|;
1137
1138       However, performance will not be as good as the all-Apache
1139       configuration.
1140
1141   Why am I getting 404 errors for pages that clearly exist?
1142       The filename that Apache has resolved to may not fall underneath the
1143       component root you specified when you created the interpreter in
1144       handler.pl. HTML::Mason requires the file to fall under the component
1145       root so that it can call it as a top-level component. (For various
1146       reasons, such as object file creation, HTML::Mason cannot treat files
1147       outside the component root as a component.)
1148
1149       If you believe the file is in fact inside the component root and
1150       HTML::Mason is in error, it may be because you're referring to the
1151       Apache document root or the HTML::Mason component root through a
1152       symbolic link. The symbolic link may confuse HTML::Mason into thinking
1153       that two directories are different when they are in fact the same. This
1154       is a known "bug", but there is no obvious fix at this time. For now,
1155       you must refrain from using symbolic links in either of these
1156       configuration items.
1157
1158       The same thing could also happen in any context with more than one way
1159       to specify a canonical filename. For example, on Windows, if your
1160       document root starts with "C:" and your component root starts with
1161       "c:", you might have this problem even though both paths should resolve
1162       to the same file.
1163
1164       With Mason 0.895 and above, if you set Apache's LogLevel to warn, you
1165       will get appropriate warnings for these Mason-related 404s.
1166
1167   Some of my pages are being served with a content type other than text/html.
1168       How do I get HTML::Mason to properly set the content type?
1169       HTML::Mason doesn't actually touch the content type -- it relies on
1170       Apache to set it correctly. You can affect how Apache sets your content
1171       type in the configuration files (e.g. srm.conf). The most common change
1172       you'll want to make is to add the line
1173
1174             DefaultType text/html
1175
1176       This indicates that files with no extension and files with an unknown
1177       extension should be treated as text/html. By default, Apache would
1178       treat them as text/plain.
1179
1180   Microsoft Internet Explorer displays my page just fine, but Netscape or
1181       other browsers just display the raw HTML code.
1182       The most common cause of this is an incorrect content-type. All
1183       browsers are supposed to honor content-type, but MSIE tries to be smart
1184       and assumes content-type of text/html based on filename extension or
1185       page content.
1186
1187       The solution is to set your default content-type to text/html. See
1188       previous question.
1189
1190   My configuration prevents HTML::Mason from processing anything but html and
1191       text extensions, but I want to generate a dynamic image using
1192       HTML::Mason.  How can I get HTML::Mason to set the correct MIME type?
1193       Use mod_perl's $r->content_type function to set the appropriate MIME
1194       type. This will allow you to output, for example, a GIF file, even if
1195       your component is called dynamicImage.html. However there's no
1196       guarantee that every browser (e.g. Internet Explorer) will respect your
1197       MIME type rather than your file extension. Make sure to test on
1198       multiple browsers.
1199
1200   How do I bring in external modules?
1201       Use the PerlModule directive in your httpd.conf, or if you have a
1202       startup.pl file, put the 'use module' in there. If you want components
1203       to be able to refer to symbols exported by the module, however, you'll
1204       need to use the module inside the HTML::Mason::Commands package. See
1205       the "External modules" section of the Administrator's Guide.
1206
1207   How do I adjust Perl's INC path so it can find my modules?
1208       You can do this:
1209
1210           <Perl>
1211           use lib ...
1212           </Perl>
1213
1214       or this:
1215
1216           PerlSetEnv PERL5LIB /path/one:/path/two:...
1217
1218   How do I use Mason in conjunction with UserDir to support Mason in user's
1219       home directories?
1220       The idea is to create one ApacheHandler for each user, dynamically. You
1221       will need to use a handler.pl or other wrapper code (see "Writing a
1222       Wrapper" in the Adminstrator's Manual).
1223
1224       Outside your handler subroutine:
1225
1226              # $user_regexp: a regexp that matches the root directory of Mason.
1227              #               Make sure there is one arg in parens that represents
1228              #               the actual username--the handler uses this.
1229              my $user_regexp = qr'/Users/([^/]*)/(?:public_html|Sites)';
1230              my %user_handlers;
1231
1232              # Create base ApacheHandler object at startup.
1233              my $base_ah = new HTML::Mason::ApacheHandler( comp_root => $comp_root,
1234                                                         data_dir  => $data_dir );
1235
1236       Inside your handler subroutine:
1237
1238              sub handler
1239              {
1240                  my $r=$_[0];
1241                  ...
1242                  #
1243                  # Have a different handler for each home directory
1244                  #
1245                  my $curr_ah;
1246                  my $filename = $r->filename();
1247                  if($filename =~ m!$user_regexp!) {
1248                      my $user_name = $1;
1249                      $curr_ah = $user_handlers{$user_name};
1250                      if(!$curr_ah) {
1251                          $filename =~ m!($user_regexp)!;
1252                          my $user_dir = $1;
1253                          $curr_ah = new HTML::Mason::ApacheHandler(comp_root=>[[$user_name => $user_dir]],
1254                                                                    data_dir=>$data_dir);
1255                          $user_handlers{$1} = $curr_ah;
1256                      }
1257                  } else {
1258                      $curr_ah = $base_ah;
1259                  }
1260                  my $status = $curr_ah->handle_request($r);
1261
1262                  return $status;
1263              }
1264
1265   How do I connect to a database from Mason?
1266       The short answer is that most any perl code that works outside Mason,
1267       for connecting to a database, should work inside a component. I
1268       sometimes do draft development and quick debugging with something like:
1269
1270             <%once>
1271             use DBI;
1272             </%once>
1273
1274             <%init>
1275             my $dbh = DBI->connect ( blah, blah );
1276             ...
1277             </%init>
1278
1279       The long answer is, of course, longer. A good deal of thought should be
1280       put into how a web application talks to databases that it depends on,
1281       as these interconnections can easily be both performance bottlenecks
1282       and very un-robust.
1283
1284       Most people use some sort of connection pooling -- opening and then re-
1285       using a limited number of database connections. The Apache::DBI module
1286       provides connection pooling that is reliable and nearly painless. If
1287       Apache::DBI has been use'd, DBI->connect() will transparently reuse an
1288       already open connections, if it can.
1289
1290       The "right" place to ask Apache::DBI for database handles is often in a
1291       top level autohandler.
1292
1293       For example:
1294
1295             <%init>
1296             my $dbh = DBI->connect('dbi:mysq:somedb', 'user', 'pw');
1297             ... # other processing
1298             $m->call_next( %ARGS, dbh => $dbh );
1299             </%init>
1300
1301       Alternately, $dbh could be a global variable which you set via
1302       MasonAllowGlobals.
1303
1304       You can use Apache::DBI in your httpd.conf file quite easily simply by
1305       adding:
1306
1307             PerlModule Apache::DBI
1308
1309       If you want to do more with Apache::DBI, like call connect_on_init, you
1310       can use a <Perl> section
1311
1312             <Perl>
1313             use Apache::DBI;
1314             Apache::DBI->connect_on_init('dbi:mysql:somedb', 'user', 'pw');
1315             Apache::DBI->setPingTimeOut('dbi:mysql:somedb', 0);
1316             </Perl>
1317
1318       Others may simply use a handler.pl file. Georgiou Kiriakos writes:
1319
1320             You can connect in the handler.pl - I find it convenient to setup a
1321             global $dbh in it.  You just need to make sure you connect inside
1322             the handler subroutine (using Apache::DBI of course).  This way a)
1323             each httpd gets it's own connection and b) each httpd reconnects if
1324             the database is recycled.
1325
1326       Regardless of whether you set up global $dbh variables in handler.pl,
1327       the static sections of handler.pl should set up Apache::DBI stuff:
1328
1329             # List of modules that you want to use from components (see Admin
1330             # manual for details)
1331             {
1332                package HTML::Mason::Commands;
1333                use Apache::DBI;
1334                # use'ing Apache::DBI here lets us connect from inside components
1335                # if we need to.
1336                # --
1337                # declare global variables, like $dbh, here as well.
1338              }
1339
1340             # Configure database connection stuff
1341             my $datasource = "DBI:blah:blah";
1342             my $username = "user";
1343             my $password = "pass";
1344             my $attr = { RaiseError=>1 ,AutoCommit=>1 };
1345             Apache::DBI->connect_on_init($datasource, $username, $password, $attr);
1346             Apache::DBI->setPingTimeOut($datasource, 0);
1347
1348   How come a certain piece of Perl code runs fine under "regular" perl, but
1349       fails under Mason?
1350       Mason is usually a red herring in this situation. Mason IS "regular"
1351       perl, with a very simple system to translate Mason component syntax to
1352       Perl code.  You can look at the object files Mason creates for your
1353       components (in the obj/ subdirectory of the Mason data directory) to
1354       see the actual Perl code Mason generates.
1355
1356       If something suddenly stops working when you place it in a Mason
1357       environment, the problem is far more likely to rest with the following
1358       environmental changes than with Mason itself:
1359
1360       * With mod_perl, the server is running under a different user/group and
1361       thus has different permissions for the resource you're trying to access
1362
1363       * With mod_perl, code can stay resident in the perl interpreter for a
1364       long time.
1365
1366       * Your headers may be sent differently under mod_perl than under your
1367       previous CGI situation (or whatever it was)
1368
1369       Mason does not have anything to do with sending mail, or accessing a
1370       database, or maintaining user accounts, or server authentication, so if
1371       your problems are in areas like these, your time will be better spent
1372       looking at other environmental changes like the ones mentioned above.
1373
1374   I'm using HTML::Mason::!ApacheHandler and I have decline_dirs disabled and
1375       am using a dhandler to handle directory requests. But when a request
1376       comes in without the final slash after the directory name, relative
1377       links are broken. What gives?
1378       Mason has always incorrectly handled such directory requests; this
1379       issue will be resolved in the 1.3 release. The reason it will only be
1380       fixed in the next major version is that some folks may have come to
1381       rely on this functionality. So it's considered breaking backwards
1382       compatibility. But if you need it to do the right thing now, fear not!
1383       There are a number of workarounds to ensure that Apache adds a slash
1384       and redirects the browser to the appropriate URL. See
1385       HandlingDirectoriesWithDhandlers for all the juicy details.
1386
1387       UPGRADING TO 1.1x
1388
1389   After upgrading, I see this error whenever I load a page: "The following
1390       parameter was passed in the call to
1391       HTML::Mason::Component::FileBased->new() but was not listed in the
1392       validation options: create_time"
1393       Delete all of your object files.
1394
1395   When I try to start my server I see an error like: "The resolver class your
1396       Interp object uses does not implement the apache_request_to_comp_path'
1397       method.
1398       This means that ApacheHandler cannot resolve requests.
1399
1400       Are you using a handler.pl file created before version 1.10?  Please
1401       see the handler.pl sample that comes with the latest version of Mason.
1402
1403       You are explicitly creating an Interp object in your handler.pl and
1404       then passing that to ApacheHandler->new.
1405
1406       Instead, simply pass all of your Interp parameters to
1407       ApacheHandler->new directly. The parameters will end up going where
1408       they belong.
1409
1410   When I start Apache (or try to use Mason) I get an error like this: "The
1411       Parser module is no longer a part of HTML::Mason.  Please see the Lexer
1412       and Compiler modules, its replacements."
1413       The Parser module is no longer used.
1414
1415   I get an error like: "The following parameters were passed in the call to
1416       HTML::Mason::Container::new but were not listed in the validation
1417       options: error_format error_mode request_class resolver_class" when
1418       using ApacheHandler
1419       Do you have PerlFreshRestart turned on? Turn it off.
1420
1421       See http://perl.apache.org/docs/1.0/guide/troubleshooting.html - "Evil
1422       things might happen when using PerlFreshRestart".
1423
1424   I get an error like this: 'Can't locate object method "make_ah"
1425       package "Apache"' === We're not kidding. PerlFreshRestart is evil. Turn
1426       it off. See question above.
1427
1428   I get: "Unknown config item 'comp_root'" or "Unknown config item
1429       'comp_root'" or something similar with ApacheHandler.
1430       Turn PerlFreshRestart off. Really.
1431
1432   I get this with a custom handler.pl: 'Can't call method "handle_request" on
1433       an undefined value at ...'
1434       Just in case you weren't convinced that PerlFreshRestart is a bad idea,
1435       this should help convince you.
1436
1437   After upgrading, I get this error for all my components: '<%' without
1438       matching '%>' ...
1439       The "perl_' prefix for Mason tags, like <%perl_args>, is no longer
1440       supported. Remove this prefix.
1441

WHERE TO FIND INFORMATION

1443   Where do I obtain HTML::Mason?
1444       HTML::Mason is available from CPAN (the Comprehensive Perl Archive
1445       Network). Details about CPAN are available at http://www.perl.com/. See
1446       the [FAQ:Installation] section of this document for tips on obtaining
1447       and installing Mason.
1448
1449   Where can I ask questions about HTML::Mason?
1450       See ContactUs and MailingLists.
1451
1452
1453
1454perl v5.38.0                      2023-07-20               HTML::Mason::FAQ(3)
Impressum