HTML::Mason::ApacheHandler(3pm)

1HTML::Mason::ApacheHandUlseerr(3C)ontributed Perl DocumeHnTtMaLt:i:oMnason::ApacheHandler(3)
2
3
4

NAME

6       HTML::Mason::ApacheHandler - Mason/mod_perl interface
7

SYNOPSIS

9           use HTML::Mason::ApacheHandler;
10
11           my $ah = HTML::Mason::ApacheHandler->new (..name/value params..);
12           ...
13           sub handler {
14               my $r = shift;
15               $ah->handle_request($r);
16           }
17

DESCRIPTION

19       The ApacheHandler object links Mason to mod_perl (version 1 or 2), run‐
20       ning components in response to HTTP requests. It is controlled primar‐
21       ily through parameters to the new() constructor.
22

PARAMETERS TO THE new() CONSTRUCTOR

24       apache_status_title
25           Title that you want this ApacheHandler to appear as under
26           Apache::Status.  Default is "HTML::Mason status".  This is useful
27           if you create more than one ApacheHandler object and want them all
28           visible via Apache::Status.
29
30       args_method
31           Method to use for unpacking GET and POST arguments. The valid
32           options are 'CGI' and 'mod_perl'; these indicate that a "CGI.pm" or
33           "Apache::Request" object (respectively) will be created for the
34           purposes of argument handling.
35
36           'mod_perl' is the default under mod_perl-1 and requires that you
37           have installed the "Apache::Request" package.  Under mod_perl-2,
38           the default is 'CGI' because "Apache2::Request" is still in devel‐
39           opment.
40
41           If args_method is 'mod_perl', the $r global is upgraded to an
42           Apache::Request object. This object inherits all Apache methods and
43           adds a few of its own, dealing with parameters and file uploads.
44           See "Apache::Request" for more information.
45
46           If the args_method is 'CGI', the Mason request object ($m) will
47           have a method called "cgi_object" available.  This method returns
48           the CGI object used for argument processing.
49
50           While Mason will load "Apache::Request" or "CGI" as needed at run‐
51           time, it is recommended that you preload the relevant module either
52           in your httpd.conf or handler.pl file, as this will save some mem‐
53           ory.
54
55       decline_dirs
56           True or false, default is true. Indicates whether Mason should
57           decline directory requests, leaving Apache to serve up a directory
58           index or a "FORBIDDEN" error as appropriate. See the allowing
59           directory requests section of the administrator's manual for more
60           information about handling directories with Mason.
61
62       interp
63           The interpreter object to associate with this compiler. By default
64           a new object of the specified interp_class will be created.
65
66       interp_class
67           The class to use when creating a interpreter. Defaults to
68           HTML::Mason::Interp.
69

ACCESSOR METHODS

71       All of the above properties, except interp_class, have standard acces‐
72       sor methods of the same name: no arguments retrieves the value, and one
73       argument sets it, except for args_method, which is not settable.  For
74       example:
75
76           my $ah = HTML::Mason::ApacheHandler->new;
77           my $decline_dirs = $ah->decline_dirs;
78           $ah->decline_dirs(1);
79

OTHER METHODS

81       The ApacheHandler object has a few other publically accessible methods
82       that may be of interest to end users.
83
84       handle_request ($r)
85           This method takes an Apache or Apache::Request object representing
86           a request and translates that request into a form Mason can under‐
87           stand.  Its return value is an Apache status code.
88
89           Passing an Apache::Request object is useful if you want to set
90           Apache::Request parameters, such as POST_MAX or DISABLE_UPLOADS.
91
92       prepare_request ($r)
93           This method takes an Apache object representing a request and
94           returns a new Mason request object or an Apache status code.  If it
95           is a request object you can manipulate that object as you like, and
96           then call the request object's "exec" method to have it generate
97           output.
98
99           If this method returns an Apache status code, that means that it
100           could not create a Mason request object.
101
102           This method is useful if you would like to have a chance to decline
103           a request based on properties of the Mason request object or a com‐
104           ponent object.  For example:
105
106               my $req = $ah->prepare_request($r);
107               # $req must be an Apache status code if it's not an object
108               return $req unless ref($req);
109
110               return DECLINED
111                   unless $req->request_comp->source_file =~ /\.html$/;
112
113               $req->exec;
114
115       request_args ($r)
116           Given an Apache request object, this method returns a three item
117           list.  The first item is a hash reference containing the arguments
118           passed by the client's request.
119
120           The second is an Apache request object.  This is returned for back‐
121           wards compatibility from when this method was responsible for turn‐
122           ing a plain Apache object into an Apache::Request object.
123
124           The third item may be a CGI.pm object or "undef", depending on the
125           value of the args_method parameter.
126

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS TO THE new() CONSTRUCTOR

ACCESSOR METHODS

OTHER METHODS

SEE ALSO