ch10_07.htm

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

<dt><b><tt class="literal">-domain=&gt;'</tt><em class="replaceable">domain_name</em><tt class="literal">'</tt></b></dt>
<dd>
The domain for which the cookie is valid.</p>
</dd>


<dt><b><tt class="literal">-secure=&gt;1</tt></b></dt>
<dd>
Use this cookie only for a secure session.</p>
</dd>

</dl>
</dd>

</dl></div>

<a name="INDEX-1675" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>defaults</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;defaults('<em class="replaceable">label</em>')
</pre><p><a name="INDEX-1675" />Generates a button that resets the form
to its defaults. See also <tt class="literal">reset</tt>.
</p><dl>
<dt><b><tt class="literal">'</tt><em class="replaceable">label</em><tt class="literal">'</tt></b></dt>
<dd>
The label to use for the button. If omitted, the label is
<tt class="literal">Defaults</tt>.
</p>
</dd>

</dl></div>

<a name="INDEX-1676" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>delete</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
<tt class="literal">$</tt><em class="replaceable">query</em>-&gt;delete('<em class="replaceable">parameter</em>')
</pre><p><a name="INDEX-1676" />Deletes a parameter.
</p><dl>
<dt><b><tt class="literal">'</tt><em class="replaceable">parameter</em><tt class="literal">'</tt></b></dt>
<dd>
The parameter to delete</p>
</dd>

</dl></div>

<a name="INDEX-1677" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>delete_all</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
<tt class="literal">$</tt><em class="replaceable">query</em>-&gt;delete_all(  )
</pre><p><a name="INDEX-1677" />Deletes the entire CGI object.
</p></div>

<a name="INDEX-1678" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>dump</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;dump([<em class="replaceable">true</em>])
</pre><p><a name="INDEX-1678" />Dumps all name/value pairs as an HTML
list.
</p><dl>
<dt><i><em class="replaceable"><tt>true</tt></em></i></dt>
<dd>
If specified, prints as plain text</p>
</dd>

</dl></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>end_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 <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;end_html(  )
</pre><p>Ends an HTML document.</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>filefield</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;filefield('<em class="replaceable">name</em>' [,'<em class="replaceable">default</em>',<em class="replaceable">size</em>,<em class="replaceable">maxlength</em> ])
</pre><p>Generates a file upload field for Netscape browsers.</p><dl>
<dt><i><em class="replaceable"><tt>name</tt></em></i></dt>
<dd>
The filename to assign the supplied file contents to (required)</p>
</dd>


<dt><i><em class="replaceable"><tt>default</tt></em></i></dt>
<dd>
The initial value (filename) to place in the text field</p>
</dd>


<dt><i><em class="replaceable"><tt>size</tt></em></i></dt>
<dd>
The size of the text field (in characters)</p>
</dd>


<dt><i><em class="replaceable"><tt>maxlength</tt></em></i></dt>
<dd>
The maximum length of the text field (in characters)</p>

<p>Using named parameters, the syntax is: </p>

<blockquote><pre class="code">print $query-&gt;textfield(-name=&gt;'<em class="replaceable"><tt>name</tt></em>',
                        -default=&gt;'<em class="replaceable"><tt>value</tt></em>',
                        -size=&gt;<em class="replaceable"><tt>size</tt></em>,
                        -maxlength=&gt;<em class="replaceable"><tt>maxlength</tt></em>,
                        -override=&gt;1,
                        -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>,
                        -onSelect=&gt;<em class="replaceable"><tt>function</tt></em>);</pre></blockquote>

<dl>
<dt><b><tt class="literal">-override=&gt;1</tt></b></dt>
<dd>
Text field should not inherit its value from a previous invocation of
the script
</p>
</dd>


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


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

</dl>
</dd>

</dl></div>

<a name="INDEX-1679" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>header</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;header([<em class="replaceable">content_type</em> ,<em class="replaceable">status</em> ,<em class="replaceable">headers</em>])
</pre><p><a name="INDEX-1679" />Generates the HTTP header for the
document.
</p><dl>
<dt><i><em class="replaceable"><tt>content_type</tt></em></i></dt>
<dd>
The content type to return. Default is <tt class="literal">text/html</tt>.</p>
</dd>


<dt><i><em class="replaceable"><tt>status</tt></em></i></dt>
<dd>
The HTTP status code and description to return. Default is
<tt class="literal">200 OK</tt>.
</p>
</dd>


<dt><i><em class="replaceable"><tt>headers</tt></em></i></dt>
<dd>
Additional headers to include, such as <tt class="literal">Content-Length:
123</tt>. Using named parameters, the syntax is:
</p>
<blockquote><pre class="code">print $query-&gt;header(-type=&gt;'<em class="replaceable"><tt>content_type</tt></em>',
                     -nph=&gt;1,
                     -status=&gt;'<em class="replaceable"><tt>status_code</tt></em>',
                     -expires=&gt;'<em class="replaceable"><tt>expcode</tt></em>',
                     -cookie=&gt;'<em class="replaceable"><tt>cookie</tt></em>',
                     -target=&gt;'<em class="replaceable"><tt>frame</tt></em>',
                     -header=&gt;'<em class="replaceable"><tt>value</tt></em>');</pre></blockquote>

<dl>
<dt><b><tt class="literal">-type=&gt;</tt><em class="replaceable">content_type</em></b></dt>
<dd>
Specifies the content type.</p>
</dd>


<dt><b><tt class="literal">-nph=&gt;1</tt></b></dt>
<dd>
Uses headers for a no-parse-header script.</p>
</dd>


<dt><b><tt class="literal">-status=&gt;</tt><em class="replaceable">status_code</em></b></dt>
<dd>
Specifies the status code.</p>
</dd>


<dt><b><tt class="literal">-expires=&gt;</tt><em class="replaceable">expcode</em></b></dt>
<dd>
Specifies an expiration timestamp (such as <tt class="literal">+3d</tt> for
three days). Values for <em class="replaceable"><tt>expcode</tt></em> are:
</p>

<dl>
<dt><i><em class="replaceable"><tt>n</tt></em><tt class="literal">s</tt></i></dt>
<dd>
<em class="replaceable"><tt>n</tt></em> seconds</p>
</dd>


<dt><i><em class="replaceable"><tt>n</tt></em><tt class="literal">m</tt></i></dt>
<dd>
<em class="replaceable"><tt>n</tt></em> minutes</p>
</dd>


<dt><i><em class="replaceable"><tt>n</tt></em><tt class="literal">h</tt></i></dt>
<dd>
<em class="replaceable"><tt>n</tt></em> hours</p>
</dd>


<dt><i><em class="replaceable"><tt>n</tt></em><tt class="literal">d</tt></i></dt>
<dd>
<em class="replaceable"><tt>n</tt></em> days</p>
</dd>


<dt><i><em class="replaceable"><tt>n</tt></em><tt class="literal">M</tt></i></dt>
<dd>
<em class="replaceable"><tt>n</tt></em> months</p>
</dd>


<dt><i><em class="replaceable"><tt>n</tt></em><tt class="literal">y</tt></i></dt>
<dd>
<em class="replaceable"><tt>n</tt></em> years</p>
</dd>


<dt><i><em class="replaceable"><tt>day_of_week</em>, <em class="replaceable">dd</em>-<em class="replaceable">MMM</em>-<em class="replaceable">YY hh:mm:ss</tt></em> <tt class="literal">GMT</tt> </i></dt>
<dd>
At the specified time</p>
</dd>


<dt><b><tt class="literal">now</tt></b></dt>
<dd>
Expires immediately</p>
</dd>

</dl>
</dd>


<dt><b><tt class="literal">-cookie=&gt;</tt><em class="replaceable">cookie</em></b></dt>
<dd>
Specifies a cookie. The cookie may be a scalar value or an array
reference.
</p>
</dd>


<dt><b><tt class="literal">-header=&gt;</tt><em class="replaceable">value</em></b></dt>
<dd>
Specifies any HTTP header.</p>
</dd>


<dt><b><tt class="literal">-target=&gt;</tt><em class="replaceable">frame</em></b></dt>
<dd>
Writes to specified frame.</p>
</dd>

</dl>
</dd>

</dl></div>

<a name="INDEX-1680" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>hidden</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;hidden('<em class="replaceable">name</em>', '<em class="replaceable">value</em>' [,'<em class="replaceable">value</em>'... ])
</pre><p><a name="INDEX-1680" />Generates a hidden text field.
</p><dl>
<dt><i><em class="replaceable"><tt>name</tt></em></i></dt>
<dd>
The name to give the value (required).</p>
</dd>


<dt><i><em class="replaceable"><tt>value</tt></em></i></dt>
<dd>
The value to assign to <em class="replaceable"><tt>name</tt></em>. Multiple
values can be specified. Using named parameters, the syntax is:
</p>

<blockquote><pre class="code">print $query-&gt;hidden(-name=&gt;'<em class="replaceable"><tt>name</tt></em>',
                       -default=&gt;'<em class="replaceable"><tt>value</tt></em>');</pre></blockquote>
<p>With named parameters, the value can also be represented as a
reference to an array, such as:
</p>


<blockquote><pre class="code">print $query-&gt;hidden(-name=&gt;'<em class="replaceable"><tt>name</tt></em>',
                     -default=&gt;['<em class="replaceable"><tt>value1</em>', '<em class="replaceable">value2</tt></em>', 
...  ]);</pre></blockquote>
</dd>

</dl></div>

<a name="INDEX-1681" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>image_button</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
print <tt class="literal">$</tt><em class="replaceable">query</em>-&gt;image_button('<em class="replaceable">name</em>','<em class="replaceable">url</em>' [,'<em class="replaceable">align</em>'])
</pre><p><a name="INDEX-1681" />Generates a clickable image map.
</p><dl>
<dt><i><em class="replaceable"><tt>name</tt></em></i></dt>
<dd>
The name to use. When clicked, the
<em class="replaceable"><tt>x</em><em class="emphasis">,</em><em class="replaceable">y</tt></em>position is returned as
<em class="replaceable"><tt>name</em><em class="emphasis">.</em><em class="replaceable">x</tt></em>and
<em class="replaceable"><tt>name</em><em class="emphasis">.</em><em class="replaceable">y</tt></em>,
respectively.
</p>
</dd>


<dt><i><em class="replaceable"><tt>url</tt></em></i></dt>
<dd>