{
"mode": "perldoc",
"parameter": "HTML::Mason::FAQ",
"section": "",
"url": "https://www.chedong.com/phpMan.php/perldoc/HTML%3A%3AMason%3A%3AFAQ/json",
"generated": "2026-06-12T23:08:09Z",
"sections": {
"NAME": {
"content": "HTML::Mason::FAQ - Frequently asked questions\n\nAUTOHANDLERS, METHODS, ATTRIBUTES, INHERITANCE\nCan I set a page's inheritance dynamically at request time (e.g. based on URL arguments)?\nNo. Inheritance is a fixed property of a component, determined once when the component is\nloaded. Dynamic inheritance is on the todo list.\n\nHow can I tell Mason to use autohandlers or dhandlers when calling one component from another component (i.e. internal redirect)?\nUsually this situation arises when a top-level component makes a run-time decision to use a\nsecond component as the \"real\" page, and calls it via <& &> or $m->comp.\n\nAutohandlers and dhandlers are only triggered for the top-level component of a request. In 1.1,\nyou can use an Apache internal redirect or a Mason subrequest ($m->subexec) to solve the\nproblem.\n\nI added a simple autohandler to a directory and now my pages don't appear.\nMake sure to include a call to $m->callnext somewhere in the autohandler.\n\nWhere does a dhandler inherit from? Can I change it to inherit based on the URL path?\nA dhandler's inheritance is determined by its location in the hierarchy, not by the URL that\ninvoked it.\n\nConsider a site with the following components:\n\n/autohandler\n/dhandler\n/products/autohandler\n\nand suppose a request comes in for /products/index.html. /dhandler will handle the request but\nwill still inherit from /autohandler.\n\nThis is not always the desired behavior, but there is no easy way to change it. If you want\n/products/* requests to use /products/autohandler, you'll need to create /products/dhandler as\nwell.\n\nCan I change the value of an attribute dynamically, based on the request?\nNo, attributes are static. The closest thing to a dynamic attribute is a method. If you've been\nusing an attribute widely and don't want to change it to a method everywhere, consider using an\nattribute/method combination. Suppose your attribute is called 'bgcolor'. Create a default\nmethod called 'bgcolor' in the autohandler:\n\n<%method bgcolor>\n<%init>\nreturn $m->basecomp->attr('bgcolor');\n<%init>\n\n\nThen replace every other\n\n$m->basecomp->attr('bgcolor');\n\nwith\n\n$m->basecomp->callmethod('bgcolor')\n\nor\n\n<& SELF:bgcolor &>\n\nNow you can leave the attribute definitions alone, but define a method if and when you need a\ndynamically computed value.\n",
"subsections": [
{
"name": "When using multiple component roots and autohandlers, does every autohandler in every root get called, and in what or",
"content": "Mason will try each autohandler path in turn, e.g.\n\n/foo/bar/baz/autohandler\n/foo/bar/autohandler\n/foo/autohandler\n/autohandler\n\nFor each path, it will search all of the component roots, and only run the *first* autohandler\nfound. Some of the autohandlers might come from one root and some from another. However, there\nis no way that multiple autohandlers would be run for the same path (/foo/autohandler, for\nexample.) There is also no way for /foo/autohandler in root 1 to explicitly call\n/foo/autohandler in root 2.\n\nPeople sometimes ask for this behavior to be changed. We feel it's a bad idea because multiple\ncomponent roots, right now, are very clean in both behavior and implementation. Trying to run\nmultiple autohandlers for the same path would require a complex set of precedence rules that\nwould almost certainly lead to unpredictable behavior. (Think about multiple versions of\nmultiple autohandlers at different directory levels, and trying to predict which order they'd\nrun in.)\n"
}
]
},
"CACHING": {
"content": "When I change a component I don't always see the results in the output. How do I invalidate Mason code caches?\nMason employs two kinds of code caching. First, Mason caches loaded components in memory.\nSecond, Mason keeps an object file (a compiled version of the component) for every loaded\ncomponent under dataroot/obj.\n\nBefore executing a memory-cached component, Mason compares the stored timestamp with the\ntimestamp of the source file. If the source file has a later timestamp, Mason will load the\ncomponent from the filesystem.\n\nSimilarly, before using an object file, Mason compares the modified timestamp of the source and\nobject files. If the source file has a later timestamp, then it is reparsed and the object file\nis overwritten.\n\nThe system is designed so that you will immediately see the effects of source file changes.\nThere are several ways for this system to breakdown; most are easy to avoid once you know about\nthem.\n\n* If you copy or move in a component source file from elsewhere, it will retain the original\nfile's timestamp, which may be earlier than the object file.\n\n* If you use tar, rsync, rdist or similar programs to transfer components, the timestamps of the\ncreated files may not be updated to the current time. Check the program's documentation for\ntimestamp-related options.\n\n* If you use a shared file system like NFS, the timestamps of locally created files may not jibe\nwith timestamps of NFS files due to differences in machine clocks.\n\n* If you ftp files onto a running server, Mason may read the file while it is incomplete. If the\nftp then completes within the same second, Mason will not notice the change, and won't ever read\nthe complete file.\n\nWhen in doubt, touching the source files (with the Unix touch command, or by re-saving in an\neditor) should force Mason to reload the component. If that does not work, try removing the\nobject files and/or restarting the server to clear the memory cache. However, these remedies\nshould be necessary only to diagnose the caching problem, not for normal Mason operation. On a\nnormal Mason system cache expiration should just work \"as expected\".\n\nMason code caching breaks down often in my situation. Couldn't you do something smarter than just comparing the timestamps?\nWhen coming up with invalidation schemes, we must consider efficiency as well as failure\npredictability. The current scheme does fail in certain situations, but those situations are\nvery predictable. If you incorrectly use tar or copy or another technique mentioned above,\nyou'll see the cache invalidation failure very quickly.\n\nSome alternatives that have been suggested:\n\n* Compare the sizes of the files as well as timestamps, or use the more liberal \"source\ntimestamp != object timestamp\". This would indeed increase the chance of catching a change. But\nit would still fail occasionally (e.g. when changing a single character, or when copying an\nold-timestamp file that just happens to match the current timestamp), resulting in intermittent,\nhead-scratching errors. In our opinion, it is better to fail miserably up front and be forced to\nfix your system than to have a mostly-working system that fails once a week. This is especially\ntrue when you are relying on Mason's cache invalidation on a production system.\n\n* Comparing MD5 or other signatures of the content. This would be very accurate, but would\nrequire reading and processing the source file instead of just performing a stat. This extra\nexpense reduces the effectiveness of the cache.\n\nThe bottom line: If you are relying on Mason's cache invalidation on a production system, you\nshould take the time and build in the appropriate infrastructure to ensure that source file\ntimestamps are always up-to-date after they are copied/untarred into place.\n\nWhen I change code in a library file I don't see the results. How can I get Mason to reread the library files?\nmodperl processes, in general, do not automatically reread your library files. You either have\nto stop and start the server whenever you change a library file, or install something like\nApache::Reload which will automate their reloading. However, see ApacheReload for important\nusage information.\n\nOnce I've made an error in a component, the error keeps appearing in the logs, no matter how many times I fix it and reload!\nAre you using Apache::Reload in its default (!ReloadAll) mode? If so, see ApacheReload for\ndetails.\n\nDo data cache files expire automatically when a component or its dependencies change?\nUnfortunately they do not. This is on the to-do list.\n\nWith Mason 1.1x and beyond, you can use the following idiom to say ``expire when my component\nsource file changes'':\n\n$m->cache(...,\nexpireif=>sub {\n(stat($m->currentcomp->sourcefile))[9] > $[0]->getcreatedat\n} )\n\nWith Mason <= 1.05, the idiom looks like:\n\n$m->cache(...,\nexpireif=>sub {\n(stat($m->currentcomp->sourcefile))[9] > $[0]\n} )\n",
"subsections": []
},
"COMPONENTS": {
"content": "What is a component?\nA component is a file that contains some combination of text (typically HTML), perl code and\nHTML::Mason directives.\n\nSome components are accessed directly by web browsers. These are called top-level components. A\ntop-level component might consist purely of static HTML.\n\nOther components are support components, which are called by top-level components or other\nsupport components. These components are analogous to perl subroutines -- they allow you to\ncreate small packages of code that you can reuse throughout your project.\n\nHow do components communicate with each other?\nComponents can return values to their callers, just like subroutines.\n\nSome components may have very simple return values. As an example, consider a component called\nisNetscape which returns a true value when the client's browser is Netscape and undef when it is\nnot. The isNetscape component could then be used easily in an if() or other control statement.\n\nOf course, components can also return strings of text, arrays, hashes or other arbitrarily\ncomplex perl data structures.\n\nHow do I use modules in components?\nTechnically you can just say \"use module-name\" at the beginning of a component. The\ndisadvantages of this method are that:\n\n* the module will be used separately by every httpd child process, costing both time and memory.\n\n* it is difficult to keep track of all the modules being used on a site.\n\nA more efficient method is to put the use line in the handler.pl or use the PerlModule\ndirective. If you want components to be able to refer to symbols exported by the module, you\nneed to use the module inside the HTML::Mason::Commands package. See the \"External modules\"\nsection of the Administrator's Guide:\n\nCan I define subroutines in components?\nDefining a named subroutine in a <%perl> or <%init> section does not work reliably because such\na definition would end up residing inside another subroutine, and Perl doesn't like that.\n\nYou can technically define named subroutines inside the <%once> section of any component, but we\nhighly discourage this, because all components are executed in the same namespace. This makes it\neasy to create two subroutines with the same name in two different components.\n\nConsider the following options:\n\n* If the routine is going to display HTML, use a separate component or a <%def> subcomponent.\n\n* If the subroutine is only of use in your component, use an anonymous subroutine defined in\n<%once>. Even though you could define the anonymous subroutine in any section, a <%once> is\nrecommended, both for performance and to avoid nested-anonymous-subroutine leaks in Perl <=5.6.\nExample:\n\n<%once>\nmy $foo = sub {\n...\n};\n\n\n...\n\n% $foo->()\n\n* If the subroutine is of interest to more than just your component, have you considered putting\nit in a module?\n\nNote that calling a component, while reasonably fast, is about an order of magnitude slower than\ncalling an equivalent subroutine. So if you're going to call the routine many times in a loop,\nyou may wish to use the anonymous subroutine for performance reasons. Benchmark for yourself.\n\nDoes Mason set the current working directory (\".\") for me?\nMason does not touch the working directory, as this would entail an unnecessary performance hit\nfor the majority of users that don't need it.\n\nIn an Apache environment, the working directory will be set in a more-or-less random way,\ndepending on such seemingly irrelevant factors as whether you started the server in\nsingle-process mode or not. In a non-Apache environment the working directory will be whatever\nit was before Mason started executing.\n\nOften people expect the working directory to be the directory of the current component. You can,\ninstead, get that directory manually with\n\n$m->currentcomp->sourcedir\n\nHow do I exit from all components including the ones that called me?\nUse $m->abort, documented in the Request manual:\n\nWhy does my output have extra newlines/whitespace and how can I get rid of it?\nAny newlines that are not either inside a tag or on a %-line will become part of the output.\nSince browsers ignore extra whitespace this is not generally a problem, but there are situations\nwhere it matters, e.g. within tags.\n\nFirst, for components that only return a value and shouldn't output *any* content, you should\nalways use <%init>:\n\n<%args>\n$foo\n\n\nThis content will be ignored.\n\n<%init>\nmy $bar = $dbh->selectrowarray(\"SELECT bar FROM t WHERE foo=?\", $foo);\nreturn $bar;\n\n\nIn components that do display content, there are various strategies. To eliminate selected\nnewlines, use the backslash. For example,\n\n\nfoo\\\n% if (1) {\nbar\\\n% }\nbaz\n\n\noutputs \"foobarbaz\" with no newlines.\n\nTo prevent a component from outputting any newlines, use a filter:\n\n<%filter>\ns/\\n//g;\n\n\nTo emit binary data without the risk of inserting extra whitespace, surround your code with\n$m->clearbuffer and $m->abort, to suppress any preceding and following content:\n\n<%init>\n$m->clearbuffer;\nmy $fh = IO::File->new('< binaryfile') or die $!;\nmy $buffer;\nwhile (read $fh, $buffer, 8192) {\n$m->print($buffer);\n}\n$m->abort;\n\n\nAt some point Mason will probably offer a \"reasonable\" whitespace removal feature, controlled by\nparameter.\n\nI'm trying to generate an image or other binary file, but it seems to be getting corrup\nThis is almost always caused by unwanted whitespace at the beginning or end of your binary data.\nPut a $m->clearbuffer before, and an $m->abort after, your code. See the last part of the\nanswer above.\n\nIn Apache 1.0 a real working example looks like this:\n\nmy $fh;\nmy $fileName = '/tmp/mypic.jpg';\nopen ( $fh, $fileName ) or die $!;\n\n$m->clearbuffer();\n$r->contenttype( 'image/jpeg' ); # set mime-type\n$r->sendhttpheader;\n$r->sendfd ( $fh );\nclose ( $fh );\n\nIn Apache 2.0 use:\n\nuse Apache2::Const qw(HTTPOK)\n\nmy $fileName = 'someimage.jpg';\n$m->clearbuffer();\n$r->contenttype( 'image/jpeg' );\n$r->sendfile( $fileName )\n$r->abort( Apache2::Const::HTTPOK );\n\nHow do I put comments in components?\n* Put general comments in the <%doc> section.\n\n* In the <%init> and <%cleanup> sections, and in a <%perl> block, use standard Perl comments\n('#').\n\n* In Mason 1.3 and beyond, use <%# %> for single or multi-line comments anywhere outside of Perl\nsections. Before 1.3, this syntax isn't guaranteed to work; one alternative is to begin a line\nwith %#.\n\n* If you are producing HTML, you can use standard HTML comments delimited by . The\ndifference is that these comments will appear in the final output.\n\nWhat's a good way to temporarily comment out code in a component?\nFor HTML, you might be tempted to surround the section with . But be careful! Any code\ninside the section will still execute. Here's a example of commenting out a call to an ad\nserver:\n\n\n\nThe ad will still be fetched and counted, but not displayed!\n\nA better way to block out a section is if (0):\n\n% if (0) {\n...\n% }\n\nCode blocked out in this way will neither be executed nor displayed, and multiple if (0) blocks\ncan be nested inside each other (unlike HTML comments).\n\nAnother way to block out code is with a <%doc> tag or a <%# %> comment, although these not\ncannot be nested.\n\nHow can I capture the output of a component (and modify it, etc.) instead of having it automatically output?\nUse $m->scomp, documented in the Request manual:\n\nCan I use globals in components?\nAll HTML::Mason components run in the same package (HTML::Mason::Commands), so if you set a\nglobal variable in one you'll be able to read it in all the others. The only problem is that\nMason by default parses components with strict mode on, so you'll get a warning about the global\n(and Mason considers all such warnings fatal). To avoid errors, simply declare your globals via\nthe MasonAllowGlobals parameter.\n\nPerlSetVar MasonAllowGlobals $dbh\nPerlAddVar MasonAllowGlobals $user\n\nIf you have a handler.pl file, you can also declare global variables in the handler() subroutine\nas long as you explicitly put them in the HTML::Mason::Commands package.\n\npackage HTML::Mason::Commands;\nuse vars qw(...);\n\nor use the Parser allowglobals parameter.\n\nAlternatively you can turn off strict entirely by passing:\n\nusestrict => 0\n\nwhen you create the Parser object. Then you can use all the globals you want. Doing this is\nterribly silly, however, and is bound to get you in trouble down the road.\n\nHow do I share variables between components?\nFirst, you can pass variables from one component to another.\n\nSecond, you can use globals. All components run in the same package (HTML::Mason::Commands as of\nthis writing), so globals in this package are visible to all components. See the previous\nquestion.\n\nThere is no way to share a variable between just a few components; this is a limitation of\nPerl's scoping rules. You can make a variable /visible/ to only certain components using 'our'\ndeclarations:\n\n<%once>\nour ($sharedvar);\n\n\nSee the Perl documentation on 'our' to make sure you understand what this is doing.\n\nThe <%shared> section is /not/ for sharing variables among different file components. It is for\nsharing variables among the subcomponents and methods of a single file component.\n\nWhy does the order of output get mixed up when I use print or $r->print?\nThis should no longer happen with Mason 1.10+. For those users still using older versions of\nMason, read the following:\n\nSince your server is most likely in batch mode, all Mason output gets buffered til the end of\nthe request. print and $r->print circumvent the buffer and thus come out before other Mason\noutput.\n\nSolution: don't use print or $r->print. Use $m->out if you must output inside a Perl section.\nSee the section on output mode in the Administrator's Guide.\n\nand the section on $m->out in the Request manual.\n\nWhy doesn't my <%cleanup> code run every time the component runs?\nA <%cleanup> block is equivalent to a \"<%perl>\" block at the end of the component. This means it\nwill NOT execute if the component explicitly returns, or if an abort or error occurs in that\ncomponent or one of its children.\n\nIf you need code that is guaranteed to run when the component or request exits, consider using a\nmodperl cleanup handler, or creating a custom class with a DESTROY method.\n\nIs <%args> exactly like %ARGS, and do I need to worry about it?\nMason allows you to predeclare arguments to components by specifying variables to hold those\narguments in an <%args> section. Because these are perl variables that you are\npredeclaring, they must have legal perl identifier names -- they can't, for example, contain\nperiods.\n\nIf you want to pass arguments that are not identified with legal perl names, you must manually\npull those arguments out of the %ARGS hash that modperl sets up for you. Why would you want to\nname your arguments un-legally, you ask? Well, just for starters, the form input element will pass arguments clickable.x and clickable.y to the action url\nautomatically. If you want to access these, you'd have to use $ARGS{clickable.x} and\n$ARGS{clickable.y} rather than trying to declare them in <%args>.\n\nWhy does Mason display the wrong line numbers in errors?\nDue to limitations in the 1.0x parser, Mason can only display line numbers relative to object\nfiles.\n\nIn 1.1 and on, error line numbers correctly reflect the component source.\n\nHow can I get a list of components matching a path pattern?\nUse the resolver's globpath method:\n\nmy @paths = $m->interp->resolver->globpath('/some/comp/path/*');\n\nThis will work even with multiple component roots; you'll get a combined list of all matching\ncomponent paths in all component roots.\n\nCan I access $m (the request object) from outside a component, e.g. inside a subroutine?\nIn 1.1x and on, use\n\nmy $m = HTML::Mason::Request->instance;\n\nBefore 1.1x, use\n\nmy $m = HTML::Mason::Commands::m;\n\nHow can I make the |h escape flag work with my Russian/Japanese/other-non-western encoding?\nThe |h flag is implemented with [=HTML::Entities::encodehtml]. This function, by default,\nescapes control chars and high-bit chars as well as <, >, &, and \". This works well for\nISO-8559-1 encoding but not with other encodings.\n\nTo make |h escape just <, >, &, and \", which is often what people want, put the following in\nyour Apache configuration:\n\nPerlSetVar MasonEscapeFlags \"h => \\&HTML::Mason::Escapes::basichtmlescape\"\n\nOr, in a top-level autohandler:\n\n$m->interp->setescape( h => \\&HTML::Mason::Escapes::basichtmlescape );\n\nWhen using multiple component roots, is there a way to explicitly call a component in a specific root?\nMultiple component roots were designed to work just like Perl's @INC. A given component path\nmatches exactly one file, the first file found in an ordered search through the roots. There is\nno way to explicitly ask for a file in a specific root.\n\nPeople sometimes ask for the ability to do this. We feel it's a bad idea because it would\nendanger the cleanliness of multiple component roots in both behavior and implementation. As it\nstands now, the rules are very easy to understand and the implementation is very clean and\nisolated; only the resolver really needs know about multiple component roots.\n\nIf you want to be able to explicitly refer to components in a given root, put an extra\nsubdirectory between the root and the components. e.g. put your components in\n\n/usr/local/htdocs/global/global/...\n\nthen add the root as\n\n['global', '/usr/local/htdocs/global']\n\nNow you can prefix a path with /global to refer to any component in that root.\n\nAlternatively, [http://search.cpan.org/dist/MasonX-Request-ExtendedCompRoot\nMasonX::Request::ExtendedCompRoot] is a subclass of Mason that does allow you to call components\nin a specific component root.\n\nIs there a syntax checker like perl -c for components?\nIt is impossible to write a truly generic standalone script to syntax check components, because\ncomponents rely on certain globals and modules to be present in their environment. Mason may\nreport compile errors from such a script even though they would not occur in your normal web\nenvironment.\n\nThe best you can do is write a standalone script that mimics your web environment as much as\npossible - in particular, declaring the same globals and loading the same modules. Instead of\nactually executing components, your script need only load them with $interp->load(). This method\nwill throw a fatal error if a component fails to load.\n",
"subsections": []
},
"HTTP AND HTML": {
"content": "How do I access GET or POST arguments?\nGET and POST arguments are automatically parsed and placed into named component arguments just\nas if you had called the component with <& &> or $m->comp. So you can get at GET/POST data by\npre-declaring argument names and/or using the %ARGS hash which is always available.\n\nHow can I access the raw content of a POST in a Mason component?\nIt depends on your environment as to what you can do.\n\nApache/modperl has an easier way of doing it than CGI/FCGi, which uses FakeApache. As you can\nsee from the comment, since FakeApache implements read, I couldn't get it to be completely\ndynamic:\n\nmy $inputText;\n# FakeApache implements read, so we can't automatically tell\n# if we're in modperl or FCGI\nif (0 && $r->can('read')){\n$r->read( $inputText, $r->headersin->{'Content-length'} );\n}\nelse {\nmy %params = $r->params;\nmy $postedcontent = $params{POSTDATA} || $params{keywords};\n$postedcontent ||= join '', %params if ($r->method eq 'POST');\n$postedcontent = join '', @$postedcontent if (ref $postedcontent eq 'ARRAY');\n$inputText = $postedcontent\n}\n\n-- Gareth Kirwan\n\nProbably $r->params does not work. there is no such method in 'man Apache'\n\n-- Rajesh Kumar Mallah.\n\nWhat happens if I include query args in a POST?\nAs of Mason 1.01, query string and POST arguments are always combined.\n\nShould I use CGI.pm to read GET/POST arguments?\nNo! HTML::Mason automatically parses GET/POST arguments and places them in declared component\narguments and %ARGS (see previous question). If you create a CGI object in the usual way for a\nPOST request, it will hang the process trying to read $r->content a second time.\n\nCan I use CGI.pm to output HTML constructs?\nYes. To get a new CGI object, use\n\nmy $query = new CGI('');\n\nYou have to give the empty string argument or CGI will try to read GET/POST arguments.\n\nTo print HTML constructs returned by CGI functions, just enclose them in <%%>, e.g.\n\n<% $query->radiogroup(...) %>\n\nHow do I modify the outgoing HTTP headers?\nUse the usual Apache.pm functions, such as $r->headerout. See the \"Sending HTTP Headers\"\nsection in the Component Developer's Guide.\n\nHow do I do an external redirect?\nIn Mason 1.0x, use code like this:\n\n$m->clearbuffer;\n# The next two lines are necessary to stop Apache from re-reading\n# POSTed data.\n$r->method('GET');\n$r->headersin->unset('Content-length');\n$r->contenttype('text/html');\n$r->headerout('Location' => $location);\n$m->abort(301);\n\nIn Mason 1.1x, use the [=$m->redirect] method.\n\nSee the next question if your redirect isn't producing the right status code.\n\nWhen trying to use $m->redirect I get 'Can't locate object method \"redirect\" via package \"HTML::Mason::!ApacheHandler\"'.\n$m->redirect is supported only in Mason 1.1x and on. Check your Mason version by putting\n\nVersion = <% $HTML::Mason::VERSION %>\n\nin a component.\n\nWhy isn't my status code reaching users' browsers?\nIf you are using a handler.pl, your handler() routine should always return the error code that",
"subsections": [
{
"name": "handle_request",
"content": "very, very simple handler() routine would look like this:\n\nsub handler {\nmy $r = shift;\n$ah->handlerequest($r);\n}\n\nIf you are using $m->abort or $m->redirect and there is an eval() wrapped directly or indirectly\naround the call, you must take care to propagate abort exceptions after the eval(). This looks\nlike:\n\neval { $m->comp('...') };\nif ($@) {\nif ($m->aborted) {\ndie $@;\n} else {\n# deal with non-abort exceptions\n}\n}\n\nHow can I handle file uploads under Mason?\nThe basic HTML for an upload form looks like:\n\n