ch10_07.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<blockquote><pre class="code">print $query-&gt;radio_group(-name=&gt;'<em class="replaceable"><tt>name</tt></em>',
                          -values=&gt;\<em class="replaceable"><tt>@list</tt></em>,
                          -default=&gt;'<em class="replaceable"><tt>selected</tt></em>',
                          -linebreak=&gt;'true',
                          -labels=&gt;\<em class="replaceable"><tt>%labelhash</tt></em>,
                          -columns=&gt;<em class="replaceable"><tt>n</tt></em>,
                          -columnheader=&gt;'<em class="replaceable"><tt>string</tt></em>',
                          -rows=&gt;<em class="replaceable"><tt>m</tt></em>,
                          -rowheader=&gt;'<em class="replaceable"><tt>string</tt></em>');</pre></blockquote>

<dl>
<dt><b><tt class="literal">-columns=&gt;</tt><em class="replaceable">n</em> </b></dt>
<dd>
The number of columns to use.</p>
</dd>


<dt><b><tt class="literal">-columnheader=&gt;'</tt><em class="replaceable">string</em><tt class="literal">'</tt> </b></dt>
<dd>
A header for the column.</p>
</dd>


<dt><b><tt class="literal">-rows=</tt><em class="replaceable">m</em> </b></dt>
<dd>
The number of rows to use. If omitted, and
<tt class="literal">-columns</tt> is specified, the rows will be calculated
for you.
</p>
</dd>


<dt><b><tt class="literal">-rowheader=&gt;'</tt><em class="replaceable">string</em><tt class="literal">'</tt></b></dt>
<dd>
A header for the row.</p>
</dd>

</dl>
</dd>

</dl></div>

<a name="INDEX-1692" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>raw_cookie</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
raw_cookie(  )
</pre><p><a name="INDEX-1692" />Returns the value of the HTTP_COOKIE
header.
</p></div>

<a name="INDEX-1693" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>ReadParse</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
ReadParse(  )
</pre><p><a name="INDEX-1693" />Creates a hash named
<tt class="literal">%in</tt> containing query information. Used for
backwards compatibility with the Perl4
<em class="emphasis">cgi-lib.pl</em>.
</p></div>

<a name="INDEX-1694" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>redirect</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print $<em class="replaceable">query</em>-&gt;redirect('<em class="replaceable">url</em>')
</pre><p><a name="INDEX-1694" />Generates a header for redirecting the
browser.
</p><dl>
<dt><i><em class="replaceable"><tt>url</tt></em></i></dt>
<dd>
The absolute URL to redirect to. Using named parameters, the syntax
is:
</p>

<blockquote><pre class="code">print $query-&gt;redirect(-uri=&gt;'<em class="replaceable"><tt>url</tt></em>',
                       -nph=&gt;1);</pre></blockquote>
</dd>

</dl></div>

<a name="INDEX-1695" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>referer</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
referer(  )
</pre><p><a name="INDEX-1695" />Returns the referring URL.
</p></div>

<a name="INDEX-1696" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>remote_host</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
remote_host(  )
</pre><p><a name="INDEX-1696" />Returns the remote hostname or IP
address, depending on the configuration of the server.
</p></div>

<a name="INDEX-1697" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>remote_user</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
remote_user(  )
</pre><p><a name="INDEX-1697" />Returns the username supplied for
authorization.
</p></div>

<a name="INDEX-1698" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>request_method</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
request_method(  )
</pre><p><a name="INDEX-1698" />Returns the request method.
</p></div>

<a name="INDEX-1699" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>reset</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print $<em class="replaceable">query</em>-&gt;reset
</pre><p><a name="INDEX-1699" />Generates a button that resets the form
to its initial values. See also <tt class="literal">defaults</tt>.
</p></div>

<a name="INDEX-1700" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>save</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">query</em>-&gt;save(<em class="replaceable">filehandle</em>)
</pre><p><a name="INDEX-1700" />Saves the form to the specified
filehandle, to be read back with the <tt class="literal">new</tt>
constructor.
</p><dl>
<dt><i><em class="replaceable"><tt>filehandle</tt></em></i></dt>
<dd>
The filehandle to save the file to</p>
</dd>

</dl></div>

<a name="INDEX-1701" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>script_name</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
script_name(  )
</pre><p><a name="INDEX-1701" />Returns the current partial URL.
</p></div>

<a name="INDEX-1702" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>scrolling_list</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
print 
$<em class="replaceable">query</em>-&gt;scrolling_list('<em class="replaceable">name</em>',\@<em class="replaceable">list</em>[,<em class="replaceable">selected</em>,<em class="replaceable">size</em>,'true',\%<em class="replaceable">labelhash</em>]);
</pre></td><td align="right" /></tr></table><p><p><a name="INDEX-1702" />Generates a scrolling list.
</p><dl>
<dt><i><em class="replaceable"><tt>name</tt></em></i></dt>
<dd>
The name to assign the input to (required).</p>
</dd>


<dt><b><tt class="literal">\@</tt><em class="replaceable">list</em></b></dt>
<dd>
An array reference with the list items. You can also use an anonymous
array reference.
</p>
</dd>


<dt><i><em class="replaceable"><tt>selected</tt></em></i></dt>
<dd>
The menu item(s) to be initially selected (default is that nothing is
selected). This can be a single value or a reference to a list of
values.
</p>
</dd>


<dt><i><em class="replaceable"><tt>size</tt></em></i></dt>
<dd>
The number of elements to display in the list box.</p>
</dd>


<dt><b><tt class="literal">'true'</tt></b></dt>
<dd>
Allows multiple selections.</p>
</dd>


<dt><b><tt class="literal">\%</tt><em class="replaceable">labelhash</em></b></dt>
<dd>
A hash reference listing labels for each list item. Default is the
list text itself. (See <tt class="literal">popup_menu</tt> for an example.)
Using named parameters, the syntax is:
</p>


<blockquote><pre class="code">print $query-&gt;scrolling_list(-name=&gt;'<em class="replaceable"><tt>name</tt></em>',
                             -values=&gt;\@<em class="replaceable"><tt>listarray</tt></em>,
                             -default=&gt;<em class="replaceable"><tt>selected</tt></em>,
                             -size=&gt;<em class="replaceable"><tt>size</tt></em>,
                             -multiple=&gt;'true',
                             -labels=&gt;\%<em class="replaceable"><tt>labelhash</tt></em>,
                             -onChange=&gt;<em class="replaceable"><tt>function</tt></em>,
                             -onFocus=&gt;<em class="replaceable"><tt>function</tt></em>,
                             -onBlur=&gt;<em class="replaceable"><tt>function</tt></em>);</pre></blockquote>

<dl>
<dt><b><tt class="literal">-onChange=&gt;</tt><em class="replaceable">function</em> </b></dt>
<dd>
Browser should execute <em class="replaceable"><tt>function</tt></em> when the
user changes the text field
</p>
</dd>


<dt><b><tt class="literal">-onFocus=&gt;</tt><em class="replaceable">function</em> </b></dt>
<dd>
Browser should execute <em class="replaceable"><tt>function</tt></em> when the
focus is on on the text field
</p>
</dd>


<dt><b><tt class="literal">-onBlur=&gt;</tt><em class="replaceable">function</em> </b></dt>
<dd>
Browser should execute <em class="replaceable"><tt>function</tt></em> when the
focus leaves the text field
</p>
</dd>

</dl>
</dd>

</dl></div>

<a name="INDEX-1703" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>self_url</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">url</em> = $<em class="replaceable">query</em>-&gt;self_url
</pre><p><a name="INDEX-1703" />Returns the URL of the current script
with all its state information intact.
</p></div>

<a name="INDEX-1704" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>start_html</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print $<em class="replaceable">query</em>-&gt;start_html(['<em class="replaceable">title</em>', '<em class="replaceable">email</em>', '<em class="replaceable">base</em>', <em class="replaceable">attribute</em>='<em class="emphasis">value</em>'])
</pre><p><a name="INDEX-1704" />Generates
<tt class="literal">&lt;HTML&gt;</tt> and <tt class="literal">&lt;BODY&gt;</tt>
tags.
</p><dl>
<dt><i><em class="replaceable"><tt>title</tt></em></i></dt>
<dd>
The title of the page.</p>
</dd>


<dt><i><em class="replaceable"><tt>email</tt></em></i></dt>
<dd>
The author's email address.</p>
</dd>


<dt><i><em class="replaceable"><tt>base</tt></em></i></dt>
<dd>
Whether to use a <tt class="literal">&lt;BASE&gt;</tt> tag in the header.</p>
</dd>


<dt><i><em class="replaceable"><tt>attribute</em><tt class="literal">='</tt><em class="replaceable">value</tt></em><tt class="literal">'</tt></i></dt>
<dd>
Specifies an attribute to the <tt class="literal">&lt;BODY&gt;</tt> tag.
Using named parameters, the syntax is:
</p>


<blockquote><pre class="code">print $query-&gt;start_html(-title=&gt;'<em class="replaceable"><tt>title</tt></em>',
                         -author=&gt;'<em class="replaceable"><tt>email_address</tt></em>',
                         -base=&gt;'true',
                         -xbase=&gt;'<em class="replaceable"><tt>url</tt></em>',
                         -meta=&gt;{'<em class="replaceable"><tt>metatag1</em>'=&gt;'<em class="replaceable">value1</tt></em>',
                                 '<em class="replaceable"><tt>metatag2</tt></em>'=&gt;
                                            '<em class="replaceable"><tt>value2</tt></em>'},
                         -script=&gt;'<em class="replaceable"><tt>$script</tt></em>',
                         -onLoad=&gt;'<em class="replaceable"><tt>$function</tt></em>',
                         -onUnload=&gt;'<em class="replaceable"><tt>$function</tt></em>',
                         -<em class="replaceable"><tt>attribute</em>=&gt;'<em class="replaceable">value</tt></em>');</pre></blockquote>

<dl>
<dt><b><tt class="literal">-title=&gt;'</tt><em class="replaceable">title</em><tt class="literal">'</tt></b></dt>
<dd>
Specifies the title of the page.</p>
</dd>


<dt><b><tt class="literal">-author=&gt;'</tt><em class="replaceable">email_address</em><tt class="literal">'</tt></b></dt>
<dd>
Specifies the author's email address.</p>
</dd>


<dt><b><tt class="literal">-xbase=&gt;'</tt><em class="replaceable">url</em><tt class="literal">'</tt> </b></dt>
<dd>
Provides an HREF for the <tt class="literal">&lt;BASE&gt;</tt> tag. Default
is the current location.
</p>
</dd>


<dt><b><tt class="literal">-meta=&gt;{'</tt><em class="replaceable">metatag1</em><tt class="literal">'=&gt;'</tt><em class="replaceable">value1</em><tt class="literal">', ... }</tt> </b></dt>
<dd>
Adds arbitrary meta information to the header as a reference to a
hash. Valid tags are:
</p>
</dd>


<dt><b><tt class="literal">keywords</tt></b></dt>
<dd>
Keywords for this document</p>
</dd>


<dt><b><tt class="literal">copyright</tt></b></dt>
<dd>
Copyright for this document description</p>
</dd>


<dt><b><tt class="literal">description</tt></b></dt>
<dd>
Description for this document</p>
</dd>


<dt><i><em class="replaceable"><tt>attribute</em><tt class="literal">=&gt;'</tt><em class="replaceable">value</tt></em><tt class="literal">'</tt></i></dt>
<dd>
Specifies an attribute to the <tt class="literal">&lt;BODY&gt;</tt> tag</p>
</dd>

</dl>
</dd>



<dt><b><tt class="literal">-script=&gt;'$</tt><em class="replaceable">script</em><tt class="literal">'</tt> </b></dt>
<dd>
Specifies a JavaScript script to be embedded within a
<tt class="literal">&lt;SCRIPT&gt;</tt> block.
</p>
</dd>


<dt><b><tt class="literal">-onLoad=&gt;'$</tt><em class="replaceable">function</em><tt class="literal">'</tt></b></dt>
<dd>
Browser should execute specified function upon entering page.</p>
</dd>