phpman > info > HTML::Mason::CGIHandler

HTML::Mason::CGIHandleUsermContributed Perl DocumeHTML::Mason::CGIHandler(3pm)

NAME
       HTML::Mason::CGIHandler - Use Mason in a CGI environment

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
       o   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}.

       o   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}.

       o   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.

       o   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.

       o   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.

       o   interp()

           Returns the Mason Interpreter associated with this handler.  The
           Interpreter lasts for the entire lifetime of the handler.

   $r Methods
       o   headers_in()

           This works much like the "Apache" method of the same name. In an
           array context, it will return a %hash of response headers. In a
           scalar context, it will return a reference to the case-insensitive
           hash blessed into the "HTML::Mason::FakeTable" class. The values
           initially populated in this hash are extracted from the CGI
           environment variables as best as possible. The pattern is to merely
           reverse the conversion from HTTP headers to CGI variables as
           documented here:
           <http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1>.

       o   header_in()

           This works much like the "Apache" method of the same name. When
           passed the name of a header, returns the value of the given
           incoming header. When passed a name and a value, sets the value of
           the header. Setting the header to "undef" will actually unset the
           header (instead of setting its value to "undef"), removing it from
           the table of headers returned from future calls to "headers_in()"
           or "header_in()".

       o   headers_out()

           This works much like the "Apache" method of the same name. In an
           array context, it will return a %hash of response headers. In a
           scalar context, it will return a reference to the case-insensitive
           hash blessed into the "HTML::Mason::FakeTable" class. Changes made
           to this hash will be made to the headers that will eventually be
           passed to the "CGI" module's "header()" method.

       o   header_out()

           This works much like the "Apache" method of the same name.  When
           passed the name of a header, returns the value of the given
           outgoing header.  When passed a name and a value, sets the value of
           the header.  Setting the header to "undef" will actually unset the
           header (instead of setting its value to "undef"), removing it from
           the table of headers that will be sent to the client.

           The headers are eventually passed to the "CGI" module's "header()"
           method.

       o   err_headers_out()

           This works much like the "Apache" method of the same name. In an
           array context, it will return a %hash of error response headers. In
           a scalar context, it will return a reference to the case-
           insensitive hash blessed into the "HTML::Mason::FakeTable" class.
           Changes made to this hash will be made to the error headers that
           will eventually be passed to the "CGI" module's "header()" method.

       o   err_header_out()

           This works much like the "Apache" method of the same name. When
           passed the name of a header, returns the value of the given
           outgoing error header. When passed a name and a value, sets the
           value of the error header. Setting the header to "undef" will
           actually unset the header (instead of setting its value to
           "undef"), removing it from the table of headers that will be sent
           to the client.

           The headers are eventually passed to the "CGI" module's "header()"
           method.

           One header currently gets special treatment - if you set a
           "Location" header, you'll cause the "CGI" module's "redirect()"
           method to be used instead of the "header()" method.  This means
           that in order to do a redirect, all you need to do is:

            $r->err_header_out(Location => 'http://redirect.to/here');

           You may be happier using the "$m->redirect" method, though, because
           it hides most of the complexities of sending headers and getting
           the status code right.

       o   content_type()

           When passed an argument, sets the content type of the current
           request to the value of the argument.  Use this method instead of
           setting a "Content-Type" header directly with "header_out()".  Like
           "header_out()", setting the content type to "undef" will remove any
           content type set previously.

           When called without arguments, returns the value set by a previous
           call to "content_type()".  The behavior when "content_type()"
           hasn't already been set is undefined - currently it returns
           "undef".

           If no content type is set during the request, the default MIME type
           "text/html" will be used.

       o   method()

           Returns the request method used for the current request, e.g.,
           "GET", "POST", etc.

       o   http_header()

           This method returns the outgoing headers as a string, suitable for
           sending to the client.

       o   send_http_header()

           Sends the outgoing headers to the client.

       o   notes()

           This works much like the "Apache" method of the same name. When
           passed a $key argument, it returns the value of the note for that
           key. When passed a $value argument, it stores that value under the
           key. Keys are case-insensitive, and both the key and the value must
           be strings. When called in a scalar context with no $key argument,
           it returns a hash reference blessed into the
           "HTML::Mason::FakeTable" class.

       o   pnotes()

           Like "notes()", but takes any scalar as an value, and stores the
           values in a case-sensitive hash.

       o   subprocess_env()

           Works like the "Apache" method of the same name, but is simply
           populated with the current values of the environment. Still, it's
           useful, because values can be changed and then seen by later
           components, but the environment itself remains unchanged. Like the
           "Apache" method, it will reset all of its values to the current
           environment again if it's called without a $key argument.

       o   params()

           This method returns a hash containing the parameters sent by the
           client.  Multiple parameters of the same name are represented by
           array references.  If both POST and query string arguments were
           submitted, these will be merged together.

   Added $m methods
       The $m object provided in components has all the functionality of the
       regular "HTML::Mason::Request" object $m, and the following:

       o   cgi_object()

           Returns the current "CGI" request object.  This is handy for
           processing cookies or perhaps even doing HTML generation (but is
           that really what you want to do?).  If you pass an argument to this
           method, you can set the request object to the argument passed.  Use
           this with care, as it may affect components called after the
           current one (they may check the content length of the request, for
           example).

           Note that the ApacheHandler class (for using Mason under mod_perl)
           also provides a "cgi_object()" method that does the same thing as
           this one.  This makes it easier to write components that function
           equally well under CGIHandler and ApacheHandler.

       o   cgi_request()

           Returns the object that is used to emulate Apache's request object.
           In other words, this is the object that $r is set to when you use
           this class.

   "HTML::Mason::FakeTable" Methods
       This class emulates the behavior of the "Apache::Table" class, and is
       used to store manage the tables of values for the following attributes
       of <$r>:

       headers_in
       headers_out
       err_headers_out
       notes
       subprocess_env

       "HTML::Mason::FakeTable" is designed to behave exactly like
       "Apache::Table", and differs in only one respect. When a given key has
       multiple values in an "Apache::Table" object, one can fetch each of the
       values for that key using Perl's "each" operator:

         while (my ($k, $v) = each %{$r->headers_out}) {
             push @cookies, $v if lc $k eq 'set-cookie';
         }

       If anyone knows how Apache::Table does this, let us know! In the
       meantime, use "get()" or "do()" to get at all of the values for a given
       key ("get()" is much more efficient, anyway).

       Since the methods named for these attributes return an
       "HTML::Mason::FakeTable" object hash in a scalar reference, it seemed
       only fair to document its interface.

       o   new()

           Returns a new "HTML::Mason::FakeTable" object. Any parameters
           passed to "new()" will be added to the table as initial values.

       o   add()

           Adds a new value to the table. If the value did not previously
           exist under the given key, it will be created. Otherwise, it will
           be added as a new value to the key.

       o   clear()

           Clears the table of all values.

       o   do()

           Pass a code reference to this method to have it iterate over all of
           the key/value pairs in the table. Keys will multiple values will
           trigger the execution of the code reference multiple times for each
           value. The code reference should expect two arguments: a key and a
           value. Iteration terminates when the code reference returns false,
           to be sure to have it return a true value if you wan it to iterate
           over every value in the table.

       o   get()

           Gets the value stored for a given key in the table. If a key has
           multiple values, all will be returned when "get()" is called in an
           array context, and only the first value when it is called in a
           scalar context.

       o   merge()

           Merges a new value with an existing value by concatenating the new
           value onto the existing. The result is a comma-separated list of
           all of the values merged for a given key.

       o   set()

           Takes key and value arguments and sets the value for that key.
           Previous values for that key will be discarded. The value must be a
           string, or "set()" will turn it into one. A value of "undef" will
           have the same behavior as "unset()".

       o   unset()

           Takes a single key argument and deletes that key from the table, so
           that none of its values will be in the table any longer.

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