1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTML::Mason::ApacheHandler - Mason/mod_perl interface</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<p><A NAME="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><A HREF="#name">NAME</a></li>
<li><A HREF="#synopsis">SYNOPSIS</a></li>
<li><A HREF="#description">DESCRIPTION</a></li>
<li><A HREF="#parameters_to_the_new___construc">PARAMETERS TO THE <code>new()</code> CONSTRUCTOR</a></li>
<li><A HREF="#accessor_methods">ACCESSOR METHODS</a></li>
<li><A HREF="#other_methods">OTHER METHODS</a></li>
<li><A HREF="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><A NAME="name">NAME</a></h1>
<p>HTML::Mason::ApacheHandler - Mason/mod_perl interface</p>
<p>
</p>
<hr />
<h1><A NAME="synopsis">SYNOPSIS</a></h1>
<pre>
use HTML::Mason::ApacheHandler;</pre>
<pre>
my $ah = HTML::Mason::ApacheHandler->new (..name/value params..);
...
sub handler {
my $r = shift;
$ah->handle_request($r);
}</pre>
<p>
</p>
<hr />
<h1><A NAME="description">DESCRIPTION</a></h1>
<p>The ApacheHandler object links Mason to mod_perl (version 1 or 2),
running components in response to HTTP requests. It is controlled
primarily through parameters to the <code>new()</code> constructor.</p>
<p>
</p>
<hr />
<h1><A NAME="parameters_to_the_new___construc">PARAMETERS TO THE <code>new()</code> CONSTRUCTOR</a></h1>
<dl>
<dt><strong><A NAME="item_apache_status_title">apache_status_title</a></strong>
<dd>
<p>Title that you want this ApacheHandler to appear as under
Apache::Status. Default is ``HTML::Mason status''. This is useful if
you create more than one ApacheHandler object and want them all
visible via Apache::Status.</p>
</dd>
</li>
<dt><strong><A NAME="item_args_method">args_method</a></strong>
<dd>
<p>Method to use for unpacking GET and POST arguments. The valid options
are 'CGI' and 'mod_perl'; these indicate that a <code>CGI.pm</code> or
<code>Apache::Request</code> object (respectively) will be created for the
purposes of argument handling.</p>
</dd>
<dd>
<p>'mod_perl' is the default under mod_perl-1 and requires that you have
installed the <code>Apache::Request</code> package. Under mod_perl-2, the default
is 'CGI' because <code>Apache2::Request</code> is still in development.</p>
</dd>
<dd>
<p>If args_method is 'mod_perl', the <code>$r</code> global is upgraded to an
Apache::Request object. This object inherits all Apache methods and
adds a few of its own, dealing with parameters and file uploads. See
<code>Apache::Request</code> for more information.</p>
</dd>
<dd>
<p>If the args_method is 'CGI', the Mason request object (<code>$m</code>) will have a
method called <code>cgi_object</code> available. This method returns the CGI
object used for argument processing.</p>
</dd>
<dd>
<p>While Mason will load <code>Apache::Request</code> or <code>CGI</code> as needed at runtime, it
is recommended that you preload the relevant module either in your
<em>httpd.conf</em> or <em>handler.pl</em> file, as this will save some memory.</p>
</dd>
</li>
<dt><strong><A NAME="item_decline_dirs">decline_dirs</a></strong>
<dd>
<p>True or false, default is true. Indicates whether Mason should decline
directory requests, leaving Apache to serve up a directory index or a
<code>FORBIDDEN</code> error as appropriate. See the <A HREF="Admin.html#allowing_directory_requests">allowing directory requests</a> section of the administrator's manual
for more information about handling directories with Mason.</p>
</dd>
</li>
<dt><strong><A NAME="item_interp">interp</a></strong>
<dd>
<p>The interpreter object to associate with this compiler. By default a
new object of the specified <A HREF="Params.html#interp_class">interp_class</a> will be created.</p>
</dd>
</li>
<dt><strong><A NAME="item_interp_class">interp_class</a></strong>
<dd>
<p>The class to use when creating a interpreter. Defaults to
<a HREF="Interp.html">HTML::Mason::Interp</a>.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><A NAME="accessor_methods">ACCESSOR METHODS</a></h1>
<p>All of the above properties, except interp_class, have standard accessor
methods of the same name: no arguments retrieves the value, and one
argument sets it, except for args_method, which is not settable. For
example:</p>
<pre>
my $ah = HTML::Mason::ApacheHandler->new;
my $decline_dirs = $ah->decline_dirs;
$ah->decline_dirs(1);</pre>
<p>
</p>
<hr />
<h1><A NAME="other_methods">OTHER METHODS</a></h1>
<p>The ApacheHandler object has a few other publically accessible methods
that may be of interest to end users.</p>
<dl>
<dt><strong><A NAME="item_handle_request">handle_request ($r)</a></strong>
<dd>
<p>This method takes an Apache or Apache::Request object representing a
request and translates that request into a form Mason can understand.
Its return value is an Apache status code.</p>
</dd>
<dd>
<p>Passing an Apache::Request object is useful if you want to set
Apache::Request parameters, such as POST_MAX or DISABLE_UPLOADS.</p>
</dd>
</li>
<dt><strong><A NAME="item_prepare_request">prepare_request ($r)</a></strong>
<dd>
<p>This method takes an Apache object representing a request and returns
a new Mason request object or an Apache status code. If it is a
request object you can manipulate that object as you like, and then
call the request object's <code>exec</code> method to have it generate output.</p>
</dd>
<dd>
<p>If this method returns an Apache status code, that means that it could
not create a Mason request object.</p>
</dd>
<dd>
<p>This method is useful if you would like to have a chance to decline a
request based on properties of the Mason request object or a component
object. For example:</p>
</dd>
<dd>
<pre>
my $req = $ah->prepare_request($r);
# $req must be an Apache status code if it's not an object
return $req unless ref($req);</pre>
</dd>
<dd>
<pre>
return DECLINED
unless $req->request_comp->source_file =~ /\.html$/;</pre>
</dd>
<dd>
<pre>
$req->exec;</pre>
</dd>
</li>
<dt><strong><A NAME="item_request_args">request_args ($r)</a></strong>
<dd>
<p>Given an Apache request object, this method returns a three item list.
The first item is a hash reference containing the arguments passed by
the client's request.</p>
</dd>
<dd>
<p>The second is an Apache request object. This is returned for
backwards compatibility from when this method was responsible for
turning a plain Apache object into an Apache::Request object.</p>
</dd>
<dd>
<p>The third item may be a CGI.pm object or <code>undef</code>, depending on the
value of the <A HREF="Params.html#args_method">args_method</a> parameter.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><A NAME="see_also">SEE ALSO</a></h1>
<p><a HREF="Mason.html">HTML::Mason</a>,
<a HREF="Admin.html">HTML::Mason::Admin</a>,
<a HREF="Interp.html">HTML::Mason::Interp</a></p>
</body>
</html>
|
