1HTML::Mason::FAQ(3) User Contributed Perl Documentation HTML::Mason::FAQ(3)
2
3
4
6 HTML::Mason::FAQ - Frequently asked questions
7
9 Can I set a page's inheritance dynamically at request time (e.g. based on
10 URL arguments)?
11 No. Inheritance is a fixed property of a component, determined once
12 when the component is loaded. Dynamic inheritance is on the todo list.
13
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
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
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
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
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
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)