info > HTML::Mason::CGIHandler

man perldoc info pydoc3 ri search

📚 NAME

HTML::Mason::CGIHandler — Use Mason in a CGI environment

🚀 Quick Reference

Use Case	Command	Description
🧩 Configure Apache for Mason	<LocationMatch "\.html$"> Action html-mason /cgi-bin/mason_handler.cgi AddHandler html-mason .html (plus protection rules)	Set up Apache to invoke Mason CGI handler for .html files, while protecting handler scripts and dhandler/autohandler.
🖥️ Create CGI handler script	my $h = HTML::Mason::CGIHandler->new( data_dir => '/path', allow_globals => [qw(%session $u)] ); $h->handle_request;	Initialize handler with interpreter options and process the current request.
📝 Write a component with args	<%args> $mood => 'satisfied' </%args> % $r->err_header_out(Location => "http://...$mood.html");	Use Mason component syntax with argument declarations and $r for redirect.
🔄 Handle a specific component path	$h->handle_comp('/path/to/component');	Execute a particular component, parsing query params and sending HTTP header.
📦 Handle a CGI object directly	$h->handle_cgi_object($cgi_object);	Use with CGI::Fast or custom CGI object; component path from $cgi->path_info().
🔍 Access CGI query from component	$m->cgi_object (returns CGI object)	Get the current CGI request object for cookies, form data, etc.

📋 SYNOPSIS

In httpd.conf or .htaccess:

<LocationMatch "\.html$">
    Action html-mason /cgi-bin/mason_handler.cgi
    AddHandler html-mason .html
</LocationMatch>
<LocationMatch "^/cgi-bin/">
    RemoveHandler .html
</LocationMatch>
<FilesMatch "(autohandler|dhandler)$">
    Order allow,deny
    Deny from all
</FilesMatch>

A script at /cgi-bin/mason_handler.pl :

#!/usr/bin/perl
use HTML::Mason::CGIHandler;

my $h = HTML::Mason::CGIHandler->new
 (
  data_dir  => '/home/jethro/code/mason_data',
  allow_globals => [qw(%session $u)],
 );

$h->handle_request;

A .html component somewhere in the web server's document root:

<%args>
 $mood => 'satisfied'
</%args>
% $r->err_header_out(Location => "http://blahblahblah.com/moodring/$mood.html");
...

📝 DESCRIPTION

This module lets you execute Mason components in a CGI environment. It lets you keep your top-level components in the web server's document root, using regular component syntax and without worrying about the particular details of invoking Mason on each request.

If you want to use Mason components from within a regular CGI script (or any other Perl program, for that matter), then you don't need this module. You can simply follow the directions in the Using Mason from a standalone script section of the administrator's manual.

This module also provides an $r request object for use inside components, similar to the Apache request object under HTML::Mason::ApacheHandler, but limited in functionality. Please note that we aim to replicate the mod_perl functionality as closely as possible — if you find differences, do not depend on them to stay different. We may fix them in a future release. Also, if you need some missing functionality in $r, let us know, we might be able to provide it.

Finally, this module alters the HTML::Mason::Request object $m to provide direct access to the CGI query, should such access be necessary.

⚙️ HTML::Mason::CGIHandler Methods

• ➡️ new() — Creates a new handler. Accepts any parameter that the Interpreter accepts. If no comp_root parameter is passed to new(), the component root will be $ENV{DOCUMENT_ROOT}.
• ➡️ handle_request() — Handles the current request, reading input from $ENV{QUERY_STRING} or STDIN and sending headers and component output to STDOUT. This method doesn't accept any parameters. The initial component will be the one specified in $ENV{PATH_INFO}.
• ➡️ handle_comp() — Like handle_request(), but the first (only) parameter is a component path or component object. This is useful within a traditional CGI environment, in which you're essentially using Mason as a templating language but not an application server. handle_component() will create a CGI query object, parse the query parameters, and send the HTTP header and component output to STDOUT. If you want to handle those parts yourself, see the Using Mason from a standalone script section of the administrator's manual.
• ➡️ handle_cgi_object() — Also like handle_request(), but this method takes only a CGI object as its parameter. This can be quite useful if you want to use this module with CGI::Fast. The component path will be the value of the CGI object's path_info() method.
• ➡️ request_args() — Given an HTML::Mason::FakeApache object, this method is expected to return a hash containing the arguments to be passed to the component. It is a separate method in order to make it easily overrideable in a subclass.
• ➡️ interp() — Returns the Mason Interpreter associated with this handler. The Interpreter lasts for the entire lifetime of the handler.

🔧 $r Methods

• ➡️ headers_in() — Works like the Apache method. In array context returns a %hash of response headers; in scalar context returns a reference to the case-insensitive hash blessed into HTML::Mason::FakeTable, populated from CGI environment variables.
• ➡️ header_in() — Get or set an incoming header by name. Setting to undef unsets the header.
• ➡️ headers_out() — Works like the Apache method. Returns a %hash (array context) or a blessed hash reference (scalar context) of outgoing response headers.
• ➡️ header_out() — Get or set an outgoing header by name. Setting to undef unsets it. Headers are passed to the CGI module's header() method.
• ➡️ err_headers_out() — Works like the Apache method. Returns error response headers (for redirects, etc.).
• ➡️ err_header_out() — Get or set an error header by name. Setting a Location header causes the CGI module's redirect() method to be used instead of header().
• ➡️ content_type() — Set or get the content type of the current request. Default is text/html if not set.
• ➡️ method() — Returns the request method (GET, POST, etc.).
• ➡️ http_header() — Returns the outgoing headers as a string.
• ➡️ send_http_header() — Sends the outgoing headers to the client.
• ➡️ notes() — Works like the Apache method. Stores/retrieves string values under case-insensitive keys. In scalar context with no key, returns a blessed hash reference.
• ➡️ pnotes() — Like notes(), but takes any scalar value and stores values in a case-sensitive hash.
• ➡️ subprocess_env() — Works like the Apache method, populated with current environment values. Values can be changed locally; calling without a key resets to current environment.
• ➡️ params() — Returns a hash of parameters from the client. Multiple same-name parameters are represented as array references. Merges POST and query string arguments.

➕ Added $m methods

The $m object provided in components has all the functionality of the regular HTML::Mason::Request object $m, plus:

• ➡️ cgi_object() — Returns the current CGI request object. Can also set the request object via an argument. The ApacheHandler class also provides this method for compatibility.
• ➡️ cgi_request() — Returns the object used to emulate Apache's request object (i.e., what $r is set to).

📋 HTML::Mason::FakeTable Methods

This class emulates Apache::Table and is used to manage tables of values for: headers_in, headers_out, err_headers_out, notes, subprocess_env. It differs only in that multiple values for a key cannot be fetched via each; use get() or do() instead.

• ➡️ new() — Returns a new HTML::Mason::FakeTable object. Parameters are added as initial values.
• ➡️ add() — Adds a new value to the table under a key. If the key already exists, adds as another value.
• ➡️ clear() — Clears all values from the table.
• ➡️ do() — Iterates over all key/value pairs, executing a code reference with key and value arguments. Returns false when the code reference returns false.
• ➡️ get() — Gets the value(s) for a key. In array context returns all values; in scalar context returns the first.
• ➡️ merge() — Merges a new value with an existing one by concatenating with a comma separator.
• ➡️ set() — Sets a key to a string value, discarding previous values. undef behaves like unset().
• ➡️ unset() — Deletes a key from the table.

---

perl v5.30.2 2020-05-22 HTML::Mason::CGIHandler(3pm)

📚 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION