| <% $h->{foo} %> | \n<% $h->{bar} %> | \n<% $h->{baz} %> | \n
\n<% $body %>\n<& footer &>\n\n<%init>\nmy $arg = $m->dhandlerarg; # get rest of path\nmy ($section, $story) = split(\"/\", $arg); # split out pieces\nmy $sth = $DBH->prepare\n(qq{SELECT headline,body FROM news\nWHERE section = ? AND story = ?);\n$sth->execute($section, $story);\nmy ($headline, $body) = $sth->fetchrowarray;\nreturn 404 if !$headline; # return \"not found\" if no such story\n\n\nBy default dhandlers do not get a chance to handle requests to a directory itself (e.g.\n/newsfeeds). These are automatically deferred to Apache, which generates an index page or a\nFORBIDDEN error. Often this is desirable, but if necessary the administrator can let in\ndirectory requests as well; see the allowing directory requests section of the administrator's\nmanual.\n\nA component or dhandler that does not want to handle a particular request may defer control to\nthe next dhandler by calling \"$m->decline\".\n\nWhen using dhandlers under modperl, you may find that sometimes Apache will not set a content\ntype for a response. This usually happens when a dhandler handles a request for a non-existent\nfile or directory. You can add a \" By <% $author %>, <% $date %>
\nCopyright 1999 McHuffy Inc.\n\n\n\nSame idea, using components for the header/footer:\n\n<& /shared/header &>\n% $m->callnext;\n<& /shared/footer &>\n\nThe next autohandler applies a filter to its pages, adding an absolute hostname to relative\nimage URLs:\n\n% $m->callnext;\n\n<%filter>\ns{(<% $headline %>
\n\n
\n\n<%method *name*>\nEach instance of this section creates a *method* embedded inside the current component. Methods\nresemble subcomponents in terms of naming, contents, and scope. However, while subcomponents can\nonly be seen from the parent component, methods are meant to be called from other components.\n\nThere are two ways to call a method. First, via a path of the form \"comp:method\":\n\n<& /foo/bar:method1 &>\n\n$m->comp('/foo/bar:method1');\n\nSecond, via the callmethod component method:\n\nmy $comp = $m->fetchcomp('/foo/bar');\n...\n$comp->callmethod('method1');\n\nMethods are commonly used in conjunction with autohandlers to make templates more flexible. See\nObject-Oriented Techniques for more information.\n\nYou cannot create a subcomponent and method with the same name. This is mostly to prevent\nobfuscation and accidental errors.\n",
"subsections": []
},
"FLAGS AND ATTRIBUTES": {
"content": "The \"<%flags>\" and \"<%attr>\" sections consist of key/value pairs, one per line, joined by '=>'.\nIn each pair, the key must be any valid Perl \"bareword identifier\" (made of letters, numbers,\nand the underscore character), and the value may be any scalar value, including references. An\noptional comment may follow each line.\n\n<%flags>\nUse this section to set official Mason flags that affect the current component's behavior.\n\nCurrently there is only one flag, \"inherit\", which specifies the component's *parent* in the\nform of a relative or absolute component path. A component inherits methods and attributes from\nits parent; see Object-Oriented Techniques for examples.\n\n<%flags>\ninherit=>'/sitehandler'\n\n\n<%attr>\nUse this section to assign static key/value attributes that can be queried from other\ncomponents.\n\n<%attr>\ncolor => 'blue'\nfonts => [qw(arial geneva helvetica)]\n\n\nTo query an attribute of a component, use the \"attr\" method:\n\nmy $color = $comp->attr('color')\n\nwhere $comp is a component object.\n\nMason evaluates attribute values once when loading the component. This makes them faster but\nless flexible than methods.\n",
"subsections": []
},
"FILTERING": {
"content": "This section describes several ways to apply filtering functions over the results of the current\ncomponent. By separating out and hiding a filter that, say, changes HTML in a complex way, we\nallow non-programmers to work in a cleaner HTML environment.\n\n<%filter> section\nThe \"<%filter>\" section allows you to arbitrarily filter the output of the current component.\nUpon entry to this code, $ contains the component output, and you are expected to modify it in\nplace. The code has access to component arguments and can invoke subroutines, call other\ncomponents, etc.\n\nThis simple filter converts the component output to UPPERCASE:\n\n<%filter>\ntr/a-z/A-Z/\n\n\nThe following navigation bar uses a filter to \"unlink\" and highlight the item corresponding to\nthe current page:\n\nHome | Products |\nBackground | Financials |\nTech Support | Contact Us\n\n<%filter>\nmy $uri = $r->uri;\ns{(.*?)} {$1}i;\n\n\nThis allows a designer to code such a navigation bar intuitively without \"if\" statements\nsurrounding each link! Note that the regular expression need not be very robust as long as you\nhave control over what will appear in the body.\n\nA filter block does not have access to variables declared in a component's \"<%init>\" section,\nthough variables declared in the \"<%args>\", \"<%once>\" or \"<%shared>\" blocks are usable in a\nfilter.\n\nIt should be noted that a filter cannot rely on receiving all of a component's output at once,\nand so may be called multiple times with different chunks of output. This can happen if\nautoflush is on, or if a filter-containing component, or the components it calls, call the\n\"$m->flushbuffer()\" method.\n\nYou should never call Perl's \"return()\" function inside a filter section, or you will not see\nany output at all.\n\nYou can use Component Calls with Content if you want to filter specific parts of a component\nrather than the entire component.\n",
"subsections": []
},
"COMMENT MARKERS": {
"content": "There are several ways to place comments in components, i.e. arbitrary text that is ignored by\nthe parser.\n\n<%doc>\nText in this section is treated as a comment and ignored. Most useful for a component's main\ndocumentation. One can easily write a program to sift through a set of components and pull out\ntheir \"<%doc>\" blocks to form a reference page.\n\n<% # comment... %>\nA \"<% %>\" tag is considered a comment if all of its lines are either whitespace, or begin with a\n'#' optionally preceded by whitespace. For example,\n\n<% # This is a single-line comment %>\n\n<%\n# This is a\n# multi-line comment\n%>\n\n%# comment\nBecause a line beginning with \"%\" is treated as Perl, \"%#\" automatically works as a comment.\nHowever we prefer the \"<% # comment %>\" form over \"%#\", because it stands out a little more as a\ncomment and because it is more flexible with regards to preceding whitespace.\n\n% if (0) { }\nAnything between these two lines\n\n% if (0) {\n...\n% }\n\nwill be skipped by Mason, including component calls. While we don't recommend this for comments\nper se, it is a useful notation for \"commenting out\" code that you don't want to run.\n\nHTML/XML/... comments\nHTML and other markup languages will have their own comment markers, for example \"\".\nNote two important differences with these comments versus the above comments:\n\n* They will be sent to the client and appear in the source of the page.\n\n* They do not block component calls and other code from running, so don't try to use them to\ncomment out code!\n\n\n",
"subsections": []
},
"OTHER SYNTAX": {
"content": "<%text>\nText in this section is printed as-is with all Mason syntax ignored. This is useful, for\nexample, when documenting Mason itself from a component:\n\n<%text>\n% This is an example of a Perl line.\n<% This is an example of an expression block. %>\n\n\nThis works for almost everything, but doesn't let you output \"\" itself! When all else\nfails, use \"$m->print\":\n\n% $m->print('The tags are <%text> and .');\n",
"subsections": [
{
"name": "Escaping expressions",
"content": "Mason has facilities for *escaping* the output from \"<% %>\" tags, on either a site-wide or a\nper-expression basis.\n\nAny \"<% %>\" expression may be terminated by a '|' and one or more escape flags (plus arbitrary\nwhitespace), separated by commas:\n\n<% $filedata |h %>\n\nThe current valid flags are:\n\n* h\n\nEscape HTML ('<' => '<', etc.) using \"HTML::Entities::encode()\". Before Perl 5.8.0 this\nmodule assumes that text is in the ISO-8859-1 character set; see the next section for how to\noverride this escaping. After 5.8.0, the encoding assumes that text is in Unicode.\n\n* u\n\nEscape a URL query string (':' => '%3A', etc.) - all but [a-zA-Z0-9.-]\n\n* n\n\nThis is a special flag indicating that the default escape flags should *not* be used for\nthis substitution.\n\nThe administrator may specify a set of default escape flags via the defaultescapeflags\nparameter. For example, if the administrator sets defaultescapeflags to \"['h']\", then all <%\n%> expressions will automatically be HTML-escaped. In this case you would use the \"n\" flag to\nturn off HTML-escaping for a specific expression:\n\n<% $htmlblock |n %>\n\nMultiple escapes can be specified as a comma-separated list:\n\n<% $uri | u, n %>\n\nThe old pre-defined escapes, 'h', 'u', and 'n', can be used *without* commas, so that this is\nlegal:\n\n<% $uri | un %>\n\nHowever, this only works for these three escapes, and no others. If you are using user-defined\nescapes as well, you *must* use a comma:\n\n<% $uri | u, addsession %>\n\nUser-defined Escapes\nBesides the default escapes mentioned above, it is possible for the user to define their own\nescapes or to override the built-in 'h' and 'u' escapes.\n\nThis is done via the Interp object's escapeflags parameter or setescape() method. Escape names\nmay be any number of characters as long as it matches the regex \"/^[\\w-]+$/\". The one exception\nis that you cannot override the 'n' flag.\n\nEach escape flag is associated with a subroutine reference. The subroutine should expect to\nreceive a scalar reference, which should be manipulated in place. Any return value from this\nsubroutine is ignored.\n\nEscapes can be defined at any time but using an escape that is not defined will cause an error\nwhen executing that component.\n\nA common use for this feature is to override the built-in HTML escaping, which will not work\nwith non-ISO-8559-1 encodings. If you are using such an encoding and want to switch the 'h' flag\nto do escape just the minimal set of characters (\"<\", \">\", \"&\", \"\"\"), put this in your Apache\nconfiguration:\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\nOr you could write your own escape function for a particular encoding:\n\n$ah->interp->setescape( h => \\&myhtmlescape );\n\nAnd of course this can be used for all sorts of other things, like a naughty words filter for\nthe easily offended:\n\n$interp->setescape( 'no-naughty' => \\&removenaughtywords );\n\nManually applying escapes\nYou can manually apply one or more escapes to text using the Interp object's \"applyescapes()\"\nmethod. e.g.\n\n$m->interp->applyescapes( 'some html content', 'h' );\n"
},
{
"name": "Backslash at end of line",
"content": "A backslash (\\) at the end of a line suppresses the newline. In HTML components, this is mostly\nuseful for fixed width areas like \"\" tags, since browsers ignore white space for the most\npart. An example:\n\n
\nfoo\n% if (1) {\nbar\n% }\nbaz\n\n\noutputs\n\nfoo\nbar\nbaz\n\nbecause of the newlines on lines 2 and 4. (Lines 3 and 5 do not generate a newline because the\nentire line is taken by Perl.) To suppress the newlines:\n\n\nfoo\\\n% if (1) {\nbar\\\n% }\nbaz\n\n\nwhich prints\n\nfoobarbaz\n"
}
]
},
"DATA CACHING": {
"content": "Mason's data caching interface allows components to cache the results of computation for\nimproved performance. Anything may be cached, from a block of HTML to a complex data structure.\n\nEach component gets its own private, persistent data cache. Except under special circumstances,\none component does not access another component's cache. Each cached value may be set to expire\nat a certain time.\n\nData caching is implemented on top of one of two external caching APIs: \"Cache::Cache\", which is\nstable but has not changed in years, or \"CHI\", which has picked up where \"Cache::Cache\" has left\noff and is actively maintained. You control which one Mason uses with the datacacheapi\nparameter. \"Cache::Cache\" is the default for backward compatibility reasons, but we recommend\n\"CHI\" for anyone doing serious caching. The APIs are very similar for Mason users, so that most\nof the information below applies to both; any differences are noted.\n",
"subsections": [
{
"name": "Basic Usage",
"content": "The \"$m->cache\" method returns a cache object representing the cache for this component. Here's\nthe typical usage of \"$m->cache\":\n\nmy $result = $m->cache->get('key');\nif (!defined($result)) {\n... compute $result ...\n$m->cache->set('key', $result);\n}\n\n\"$m->cache->get\" attempts to retrieve this component's cache value. If the value is available it\nis placed in $result. If the value is not available, $result is computed and stored in the cache\nby \"$m->cache->set\".\n\nMultiple Keys/Values\nA cache can store multiple key/value pairs. A value can be anything serializable by \"Storable\",\nfrom a simple scalar to an arbitrary complex list or hash reference:\n\n$m->cache->set(name => $string);\n$m->cache->set(friends => \\@list);\n$m->cache->set(map => \\%hash);\n\nYou can fetch all the keys in a cache with\n\nmy @idents = $m->cache->getkeys;\n\nIt should be noted that Mason reserves all keys beginning with \"mason\" for its own use.\n"
},
{
"name": "Expiration",
"content": "You can pass an optional third argument to \"$m->cache->set\" indicating when the item should\nexpire:\n\n$m->cache->set('name1', $string1, '5 min'); # Expire in 5 minutes\n$m->cache->set('name2', $string2, '3h'); # Expire in 3 hours\n\nTo change the expiration time for a piece of data, call \"set\" again with the new expiration. To\nexpire an item immediately, use \"$m->cache->remove\".\n\nYou can also specify an expiration condition when you fetch the item, using the *expireif*\noption:\n\nmy $result = $m->cache->get('key',\nexpireif=>sub { $[0]->getcreatedat < (stat($file))[9] });\n\n*expireif* takes an anonymous subroutine, which is called with the cache object as its only\nparameter. If the subroutine returns a true value, the item is expired. In the example above, we\nexpire the item whenever a certain file changes.\n\nFinally, you can expire a cache item from an external script; see Accessing a Cache Externally\nbelow.\n"
},
{
"name": "Avoiding Concurrent Recomputation",
"content": "The code shown in \"Basic Usage\" above,\n\nmy $result = $m->cache->get('key');\nif (!defined($result)) {\n... compute $result ...\n$m->cache->set('key', $result);\n}\n\ncan suffer from a kind of race condition for caches that are accessed frequently and take a long\ntime to recompute.\n\nSuppose that a particular cache value is accessed five times a second and takes three seconds to\nrecompute. When the cache expires, the first process comes in, sees that it is expired, and\nstarts to recompute the value. The second process comes in and does the same thing. This\nsequence continues until the first process finishes and stores the new value. On average, the\nvalue will be recomputed and written to the cache 15 times!\n\nOne solution is the *busylock* flag:\n\nmy $result = $m->cache->get('key', busylock=>'30 sec');\n\nIn this case, when the value cannot be retrieved, \"get()\" sets the expiration time of the value\n30 seconds in the future before returning \"undef\". This tells the first process to compute the\nnew value while causing subsequent processes to use the old value for 30 seconds.\n\nShould the 30 seconds expire before the first process is done, a second process will start\ncomputing the new value while setting the expiration time yet another 30 seconds in the future,\nand so on.\n\nThe disadvantage of this solution is that multiple writes to the cache will be performed for\neach \"set()\".\n\nAnother solution, available only if you are using \"CHI\", is \"expiresvariance\" which will create\na variable time window during which expiration may occur. See the \"CHI\" documentation for\ndetails.\n"
},
{
"name": "Caching All Output",
"content": "Occasionally you will need to cache the complete output of a component. For this purpose, Mason\noffers the \"$m->cacheself\" method. This method causes Mason to check to see if this component\nhas already been run and its output cached. If this is the case, this output is simply sent as\noutput. Otherwise, the component run normally and its output and return value cached.\n\nIt is typically used right at the top of an \"<%init>\" section:\n\n<%init>\nreturn if $m->cacheself(key => 'fookey', expiresin => '3 hours',\n...
\n...\n\n\nWelcome, <% $fname %>. Here are your options:\n\n<%shared>\nmy $dbh = DBI::connect ...;\nmy $user = $r->connection->user;\nmy $sth = $dbh->prepare(\"select lname,fname, from users where userid = ?\");\n$sth->execute($user);\nmy ($lname, $fname) = $sth->fetchrowarray;\nmy $fullname = \"$first $last\";\n\n\n\"<%shared>\" presents a good alternative to \"<%init>\" when data is needed across multiple scopes.\nOutside these situations, \"<%init>\" is preferred for its slightly greater speed and predictable\nexecution model.\n"
},
{
"name": "Example",
"content": "Let's say we have three components:\n\n/autohandler\n/products/autohandler\n/products/index.html\n\nand that a request comes in for /products/index.html.\n\n/autohandler contains a general template for the site, referring to a number of standard methods\nand attributes for each page:\n\n\n<& SELF:title &>
\n\n\n<%method footer>\n\n\nNotice how we provide defaults for each method and attribute, even if blank.\n\n/products/autohandler overrides some attributes and methods for the /products section of the\nsite.\n\n<%attr>\nbodystyle => 'plain'\n\n<%method title>\nMcGuffey Inc.: Products\n\n\n% $m->callnext;\n\nNote that this component, though it only defines attributes and methods, must call\n\"$m->callnext\" if it wants the rest of the chain to run.\n\n/products/index.html might override a few attributes, but mainly provides a primary section for\nthe body.\n"
}
]
},
"COMMON TRAPS": {
"content": "Do not call $r->content or \"new CGI\"\nMason calls \"$r->content\" itself to read request input, emptying the input buffer and\nleaving a trap for the unwary: subsequent calls to \"$r->content\" hang the server. This is a\nmodperl \"feature\" that may be fixed in an upcoming release.\n\nFor the same reason you should not create a CGI object like\n\nmy $query = new CGI;\n\nwhen handling a POST; the CGI module will try to reread request input and hang. Instead,\ncreate an empty object:\n\nmy $query = new CGI (\"\");\n\nsuch an object can still be used for all of CGI's useful HTML output functions. Or, if you\nreally want to use CGI's input functions, initialize the object from %ARGS:\n\nmy $query = new CGI (\\%ARGS);\n",
"subsections": []
},
"MASON AND SOURCE FILTERS": {
"content": "Modules which work as source filters, such as \"Switch.pm\", will only work when you are using\nobject files. This is because of how source filters are implemented, and cannot be changed by\nthe Mason authors.\n",
"subsections": []
}
}
}
}