{
"mode": "perldoc",
"parameter": "HTML::Mason::CGIHandler",
"section": "",
"url": "https://www.chedong.com/phpMan.php/perldoc/HTML%3A%3AMason%3A%3ACGIHandler/json",
"generated": "2026-06-12T21:34:16Z",
"synopsis": "In httpd.conf or .htaccess:\n\nAction html-mason /cgi-bin/masonhandler.cgi\nAddHandler html-mason .html\n\n\nRemoveHandler .html\n\n\nOrder allow,deny\nDeny from all\n\nA script at /cgi-bin/masonhandler.pl :\n#!/usr/bin/perl\nuse HTML::Mason::CGIHandler;\nmy $h = HTML::Mason::CGIHandler->new\n(\ndatadir => '/home/jethro/code/masondata',\nallowglobals => [qw(%session $u)],\n);\n$h->handlerequest;\nA .html component somewhere in the web server's document root:\n<%args>\n$mood => 'satisfied'\n\n% $r->errheaderout(Location => \"http://blahblahblah.com/moodring/$mood.html\");\n...",
"sections": {
"NAME": {
"content": "HTML::Mason::CGIHandler - Use Mason in a CGI environment\n",
"subsections": []
},
"SYNOPSIS": {
"content": "In httpd.conf or .htaccess:\n\n\nAction html-mason /cgi-bin/masonhandler.cgi\nAddHandler html-mason .html\n\n\nRemoveHandler .html\n\n\nOrder allow,deny\nDeny from all\n\n\nA script at /cgi-bin/masonhandler.pl :\n\n#!/usr/bin/perl\nuse HTML::Mason::CGIHandler;\n\nmy $h = HTML::Mason::CGIHandler->new\n(\ndatadir => '/home/jethro/code/masondata',\nallowglobals => [qw(%session $u)],\n);\n\n$h->handlerequest;\n\nA .html component somewhere in the web server's document root:\n\n<%args>\n$mood => 'satisfied'\n\n% $r->errheaderout(Location => \"http://blahblahblah.com/moodring/$mood.html\");\n...\n",
"subsections": []
},
"DESCRIPTION": {
"content": "This module lets you execute Mason components in a CGI environment. It lets you keep your\ntop-level components in the web server's document root, using regular component syntax and\nwithout worrying about the particular details of invoking Mason on each request.\n\nIf you want to use Mason components from *within* a regular CGI script (or any other Perl\nprogram, for that matter), then you don't need this module. You can simply follow the directions\nin the Using Mason from a standalone script section of the administrator's manual.\n\nThis module also provides an $r request object for use inside components, similar to the Apache\nrequest object under \"HTML::Mason::ApacheHandler\", but limited in functionality. Please note\nthat we aim to replicate the \"modperl\" functionality as closely as possible - if you find\ndifferences, do *not* depend on them to stay different. We may fix them in a future release.\nAlso, if you need some missing functionality in $r, let us know, we might be able to provide it.\n\nFinally, this module alters the \"HTML::Mason::Request\" object $m to provide direct access to the\nCGI query, should such access be necessary.\n\n\"HTML::Mason::CGIHandler\" Methods\n* new()\n\nCreates a new handler. Accepts any parameter that the Interpreter accepts.\n\nIf no \"comproot\" parameter is passed to \"new()\", the component root will be\n$ENV{DOCUMENTROOT}.\n\n* handlerequest()\n\nHandles the current request, reading input from $ENV{QUERYSTRING} or \"STDIN\" and sending\nheaders and component output to \"STDOUT\". This method doesn't accept any parameters. The\ninitial component will be the one specified in $ENV{PATHINFO}.\n\n* handlecomp()\n\nLike \"handlerequest()\", but the first (only) parameter is a component path or component\nobject. This is useful within a traditional CGI environment, in which you're essentially\nusing Mason as a templating language but not an application server.\n\n\"handlecomponent()\" will create a CGI query object, parse the query parameters, and send\nthe HTTP header and component output to STDOUT. If you want to handle those parts yourself,\nsee the Using Mason from a standalone script section of the administrator's manual.\n\n* handlecgiobject()\n\nAlso like \"handlerequest()\", but this method takes only a CGI object as its parameter. This\ncan be quite useful if you want to use this module with CGI::Fast.\n\nThe component path will be the value of the CGI object's \"pathinfo()\" method.\n\n* requestargs()\n\nGiven an \"HTML::Mason::FakeApache\" object, this method is expected to return a hash\ncontaining the arguments to be passed to the component. It is a separate method in order to\nmake it easily overrideable in a subclass.\n\n* interp()\n\nReturns the Mason Interpreter associated with this handler. The Interpreter lasts for the\nentire lifetime of the handler.\n\n$r Methods\n* headersin()\n\nThis works much like the \"Apache\" method of the same name. In an array context, it will\nreturn a %hash of response headers. In a scalar context, it will return a reference to the\ncase-insensitive hash blessed into the \"HTML::Mason::FakeTable\" class. The values initially\npopulated in this hash are extracted from the CGI environment variables as best as possible.\nThe pattern is to merely reverse the conversion from HTTP headers to CGI variables as\ndocumented here: .\n\n* headerin()\n\nThis works much like the \"Apache\" method of the same name. When passed the name of a header,\nreturns the value of the given incoming header. When passed a name and a value, sets the\nvalue of the header. Setting the header to \"undef\" will actually *unset* the header (instead\nof setting its value to \"undef\"), removing it from the table of headers returned from future\ncalls to \"headersin()\" or \"headerin()\".\n\n* headersout()\n\nThis works much like the \"Apache\" method of the same name. In an array context, it will\nreturn a %hash of response headers. In a scalar context, it will return a reference to the\ncase-insensitive hash blessed into the \"HTML::Mason::FakeTable\" class. Changes made to this\nhash will be made to the headers that will eventually be passed to the \"CGI\" module's\n\"header()\" method.\n\n* headerout()\n\nThis works much like the \"Apache\" method of the same name. When passed the name of a header,\nreturns the value of the given outgoing header. When passed a name and a value, sets the\nvalue of the header. Setting the header to \"undef\" will actually *unset* the header (instead\nof setting its value to \"undef\"), removing it from the table of headers that will be sent to\nthe client.\n\nThe headers are eventually passed to the \"CGI\" module's \"header()\" method.\n\n* errheadersout()\n\nThis works much like the \"Apache\" method of the same name. In an array context, it will\nreturn a %hash of error response headers. In a scalar context, it will return a reference to\nthe case-insensitive hash blessed into the \"HTML::Mason::FakeTable\" class. Changes made to\nthis hash will be made to the error headers that will eventually be passed to the \"CGI\"\nmodule's \"header()\" method.\n\n* errheaderout()\n\nThis works much like the \"Apache\" method of the same name. When passed the name of a header,\nreturns the value of the given outgoing error header. When passed a name and a value, sets\nthe value of the error header. Setting the header to \"undef\" will actually *unset* the\nheader (instead of setting its value to \"undef\"), removing it from the table of headers that\nwill be sent to the client.\n\nThe headers are eventually passed to the \"CGI\" module's \"header()\" method.\n\nOne header currently gets special treatment - if you set a \"Location\" header, you'll cause\nthe \"CGI\" module's \"redirect()\" method to be used instead of the \"header()\" method. This\nmeans that in order to do a redirect, all you need to do is:\n\n$r->errheaderout(Location => 'http://redirect.to/here');\n\nYou may be happier using the \"$m->redirect\" method, though, because it hides most of the\ncomplexities of sending headers and getting the status code right.\n\n* contenttype()\n\nWhen passed an argument, sets the content type of the current request to the value of the\nargument. Use this method instead of setting a \"Content-Type\" header directly with\n\"headerout()\". Like \"headerout()\", setting the content type to \"undef\" will remove any\ncontent type set previously.\n\nWhen called without arguments, returns the value set by a previous call to \"contenttype()\".\nThe behavior when \"contenttype()\" hasn't already been set is undefined - currently it\nreturns \"undef\".\n\nIf no content type is set during the request, the default MIME type \"text/html\" will be\nused.\n\n* method()\n\nReturns the request method used for the current request, e.g., \"GET\", \"POST\", etc.\n\n* httpheader()\n\nThis method returns the outgoing headers as a string, suitable for sending to the client.\n\n* sendhttpheader()\n\nSends the outgoing headers to the client.\n\n* notes()\n\nThis works much like the \"Apache\" method of the same name. When passed a $key argument, it\nreturns the value of the note for that key. When passed a $value argument, it stores that\nvalue under the key. Keys are case-insensitive, and both the key and the value must be\nstrings. When called in a scalar context with no $key argument, it returns a hash reference\nblessed into the \"HTML::Mason::FakeTable\" class.\n\n* pnotes()\n\nLike \"notes()\", but takes any scalar as an value, and stores the values in a case-sensitive\nhash.\n\n* subprocessenv()\n\nWorks like the \"Apache\" method of the same name, but is simply populated with the current\nvalues of the environment. Still, it's useful, because values can be changed and then seen\nby later components, but the environment itself remains unchanged. Like the \"Apache\" method,\nit will reset all of its values to the current environment again if it's called without a\n$key argument.\n\n* params()\n\nThis method returns a hash containing the parameters sent by the client. Multiple parameters\nof the same name are represented by array references. If both POST and query string\narguments were submitted, these will be merged together.\n\nAdded $m methods\nThe $m object provided in components has all the functionality of the regular\n\"HTML::Mason::Request\" object $m, and the following:\n\n* cgiobject()\n\nReturns the current \"CGI\" request object. This is handy for processing cookies or perhaps\neven doing HTML generation (but is that *really* what you want to do?). If you pass an\nargument to this method, you can set the request object to the argument passed. Use this\nwith care, as it may affect components called after the current one (they may check the\ncontent length of the request, for example).\n\nNote that the ApacheHandler class (for using Mason under modperl) also provides a\n\"cgiobject()\" method that does the same thing as this one. This makes it easier to write\ncomponents that function equally well under CGIHandler and ApacheHandler.\n\n* cgirequest()\n\nReturns the object that is used to emulate Apache's request object. In other words, this is\nthe object that $r is set to when you use this class.\n\n\"HTML::Mason::FakeTable\" Methods\nThis class emulates the behavior of the \"Apache::Table\" class, and is used to store manage the\ntables of values for the following attributes of <$r>:\n\nheadersin\nheadersout\nerrheadersout\nnotes\nsubprocessenv\n\n\"HTML::Mason::FakeTable\" is designed to behave exactly like \"Apache::Table\", and differs in only\none respect. When a given key has multiple values in an \"Apache::Table\" object, one can fetch\neach of the values for that key using Perl's \"each\" operator:\n\nwhile (my ($k, $v) = each %{$r->headersout}) {\npush @cookies, $v if lc $k eq 'set-cookie';\n}\n\nIf anyone knows how Apache::Table does this, let us know! In the meantime, use \"get()\" or \"do()\"\nto get at all of the values for a given key (\"get()\" is much more efficient, anyway).\n\nSince the methods named for these attributes return an \"HTML::Mason::FakeTable\" object hash in a\nscalar reference, it seemed only fair to document its interface.\n\n* new()\n\nReturns a new \"HTML::Mason::FakeTable\" object. Any parameters passed to \"new()\" will be\nadded to the table as initial values.\n\n* add()\n\nAdds a new value to the table. If the value did not previously exist under the given key, it\nwill be created. Otherwise, it will be added as a new value to the key.\n\n* clear()\n\nClears the table of all values.\n\n* do()\n\nPass a code reference to this method to have it iterate over all of the key/value pairs in\nthe table. Keys will multiple values will trigger the execution of the code reference\nmultiple times for each value. The code reference should expect two arguments: a key and a\nvalue. Iteration terminates when the code reference returns false, to be sure to have it\nreturn a true value if you wan it to iterate over every value in the table.\n\n* get()\n\nGets the value stored for a given key in the table. If a key has multiple values, all will\nbe returned when \"get()\" is called in an array context, and only the first value when it is\ncalled in a scalar context.\n\n* merge()\n\nMerges a new value with an existing value by concatenating the new value onto the existing.\nThe result is a comma-separated list of all of the values merged for a given key.\n\n* set()\n\nTakes key and value arguments and sets the value for that key. Previous values for that key\nwill be discarded. The value must be a string, or \"set()\" will turn it into one. A value of\n\"undef\" will have the same behavior as \"unset()\".\n\n* unset()\n\nTakes a single key argument and deletes that key from the table, so that none of its values\nwill be in the table any longer.\n",
"subsections": []
}
},
"summary": "HTML::Mason::CGIHandler - Use Mason in a CGI environment",
"flags": [],
"examples": [],
"see_also": []
}