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 redirect the current request to be a file download?
823       A detailed explanation is provided in ForceFileDownload.
824
825   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
830       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
834   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
839            <%filter>
840            $_ = HTML::FillInForm->new->fill(scalarref => \$_, fdat => \%ARGS );
841            </%filter>
842
843       This will work for any component that contains a complete form in its
844       output.
845
846       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
849            <%filter>
850            use HTML::FillInForm;
851            $_ = HTML::FillInForm->new->fill(scalarref => \$_, fobject => $r );
852            </%filter>
853
854       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

INSTALLATION

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
871   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
876   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
882   Can I run Mason via CGI?
883       Yes. See "Using Mason from a CGI script" in the Interpreter manual.
884
885       The examples in the docs requires that you have Mason 1.10+ installed.
886
887       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
894   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
899   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
906   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
913       To fix the problem, you'll have to recompile your server, adding the
914       PERL_TABLE_API=1 flag (or EVERYTHING=1).
915
916       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
920             my @val = $mod_perl::VERSION < 1.24 ? $c->dir_config($p) :
921                $c->dir_config->get($p);
922
923       and change it to:
924
925             my @val = Apache::perl_hook('TableApi') ? $c->dir_config->get($p) :
926                $c->dir_config($p);
927
928       Recent versions of Mason use that, or a variant of it.
929
930   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
935       You can either install libapreq, or change args_method to 'CGI'. The
936       latter is a bit slower and uses more memory.
937
938   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
943       * 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
949       * 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
957       * 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
964       MISCELLANEOUS
965
966   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
971       PERFORMANCE
972
973   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
980       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
985       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
992       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
995   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
1001       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
1005   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
1011       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
1017       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
1023       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
1027       SERVER CONFIGURATION
1028
1029   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
1036       For more details see "Server Stopping and Restarting" in the mod_perl
1037       guide.
1038
1039       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
1046   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
1053       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
1057       Whatever naming scheme you choose should ideally accomplish three
1058       things:
1059
1060       * Distinguish top-level from internal components. This is obviously
1061       crucial for security.
1062
1063       * 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
1067       * 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
1071   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
1079       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
1082       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
1086       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
1093   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
1099             <Location /plain>
1100               SetHandler default-handler
1101             </Location>
1102
1103       Or suppose you have a "/cgi-bin" that you want to process via CGI:
1104
1105             <Location /cgi-bin>
1106               SetHandler cgi-script
1107             </Location>
1108
1109       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
1113             <Location />
1114               SetHandler perl-script
1115               PerlHandler HTML::Mason
1116             </Location>
1117
1118             <Location /cgi-bin>
1119               SetHandler cgi-script
1120             </Location>
1121
1122       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
1127              <FilesMatch  "\.html$">
1128                SetHandler perl-script
1129                PerlHandler HTML::Mason
1130              </FilesMatch>
1131
1132       Or you could reverse this logic, and write FilesMatch directives just
1133       for gifs and jpegs, or whatever.
1134
1135       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
1139             return -1 if $r->uri() =~ m|^/plain|;
1140
1141       However, performance will not be as good as the all-Apache
1142       configuration.
1143
1144   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
1152       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
1161       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
1167       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
1170   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
1177             DefaultType text/html
1178
1179       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
1183   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
1190       The solution is to set your default content-type to text/html. See
1191       previous question.
1192
1193   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
1203   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
1210   How do I adjust Perl's INC path so it can find my modules?
1211       You can do this:
1212
1213           <Perl>
1214           use lib ...
1215           </Perl>
1216
1217       or this:
1218
1219           PerlSetEnv PERL5LIB /path/one:/path/two:...
1220
1221   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
1227       Outside your handler subroutine:
1228
1229              # $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
1235              # Create base ApacheHandler object at startup.
1236              my $base_ah = new HTML::Mason::ApacheHandler( comp_root => $comp_root,
1237                                                         data_dir  => $data_dir );
1238
1239       Inside your handler subroutine:
1240
1241              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
1265                  return $status;
1266              }
1267
1268   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
1273             <%once>
1274             use DBI;
1275             </%once>
1276
1277             <%init>
1278             my $dbh = DBI->connect ( blah, blah );
1279             ...
1280             </%init>
1281
1282       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
1287       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
1293       The "right" place to ask Apache::DBI for database handles is often in a
1294       top level autohandler.
1295
1296       For example:
1297
1298             <%init>
1299             my $dbh = DBI->connect('dbi:mysq:somedb', 'user', 'pw');
1300             ... # other processing
1301             $m->call_next( %ARGS, dbh => $dbh );
1302             </%init>
1303
1304       Alternately, $dbh could be a global variable which you set via
1305       MasonAllowGlobals.
1306
1307       You can use Apache::DBI in your httpd.conf file quite easily simply by
1308       adding:
1309
1310             PerlModule Apache::DBI
1311
1312       If you want to do more with Apache::DBI, like call connect_on_init, you
1313       can use a <Perl> section
1314
1315             <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
1321       Others may simply use a handler.pl file. Georgiou Kiriakos writes:
1322
1323             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
1329       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
1332             # 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
1343             # 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
1351   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
1359       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
1363       * 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
1366       * With mod_perl, code can stay resident in the perl interpreter for a
1367       long time.
1368
1369       * Your headers may be sent differently under mod_perl than under your
1370       previous CGI situation (or whatever it was)
1371
1372       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
1377   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
1390       UPGRADING TO 1.1x
1391
1392   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
1398   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
1403       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
1406       You are explicitly creating an Interp object in your handler.pl and
1407       then passing that to ApacheHandler->new.
1408
1409       Instead, simply pass all of your Interp parameters to
1410       ApacheHandler->new directly. The parameters will end up going where
1411       they belong.
1412
1413   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
1418   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
1424       See http://perl.apache.org/docs/1.0/guide/troubleshooting.html - "Evil
1425       things might happen when using PerlFreshRestart".
1426
1427   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
1431   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
1435   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
1440   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

WHERE TO FIND INFORMATION

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
1452   Where can I ask questions about HTML::Mason?
1453       See ContactUs and MailingLists.
1454
1455
1456
1457perl v5.28.1                      2017-10-29               HTML::Mason::FAQ(3)
Impressum