Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::Mason::CGIHandleUser Contributed Perl DocumentHTML::Mason::CGIHandler(3)

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.24.1			  2014-11-15	    HTML::Mason::CGIHandler(3)

NAME | SYNOPSIS | DESCRIPTION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Mason::CGIHandler&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help