WebStack

Annotated docs/parameters-body.html

546:f72924d73db7
503:5e29854fe10d
488:0f2d178f6352
2005-11-15 paulb file changeset files shortlog [project @ 2005-11-15 15:46:01 by paulb] Added has_key method.
paulb@470 1 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@470 2 
<html xmlns="http://www.w3.org/1999/xhtml"><head>
paulb@470 3
paulb@470 4 
  <title>Request Body Parameters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
paulb@470 5 
  <link href="styles.css" rel="stylesheet" type="text/css" /></head>
paulb@335 6 
<body>
paulb@335 7 
<h1>Request Body Parameters</h1>
paulb@335 8 
 
 paulb@335      9 
<p>Request parameters are typically added to the request body when forms are
 
 paulb@470     10 
submitted by a browser which is instructed to use the <code>POST</code> <a href="methods.html">request method</a>. A Web form (in HTML) can be used to
 
 paulb@335     11 
achieve this; for example:</p>
 
 paulb@488     12 
<pre>&lt;form method="post" action="http://www.boddie.org.uk/application"&gt;<br />    &lt;input name="param1" type="text" value="value1" /&gt;<br />    &lt;input name="param2" type="text" value="value2" /&gt;<br />&lt;/form&gt;</pre>
 
 paulb@335     13 
 
 paulb@335     14 
<p>As a consequence of this form being submitted, the following parameters
 
 paulb@335     15 
will become available in the application:</p>
 
 paulb@335     16 
<ul>
 
 paulb@335     17 
  <li><code>param1</code> with the value <code><code>value1</code></code></li>
 
 paulb@335     18 
  <li><code><code>param2</code></code> with the value <code>value2</code></li>
 
 paulb@335     19 
</ul>
 
 paulb@335     20 
 
 paulb@335     21 
<p>Parameters encoded in this way are not transferred in URLs and are mostly
 
 paulb@335     22 
hidden in user interfaces, although viewing a Web page's source can often
 
 paulb@335     23 
reveal default values of such parameters.</p>
 
 paulb@335     24 
 
 paulb@335     25 
<div class="WebStack">
 
 paulb@335     26 
<h3>WebStack API - Accessing Body Parameters</h3>
 
 paulb@335     27 
 
 paulb@335     28 
<p>Transaction objects provide the following methods to access parameters
 
 paulb@335     29 
specified in request headers. The terminology used in the API describes such
 
 paulb@335     30 
parameters as body fields, since such parameters are often provided by form
 
 paulb@335     31 
fields.</p>
 
 paulb@335     32 
<dl>
 
 paulb@335     33 
  <dt><code>get_fields_from_body</code></dt>
 
 paulb@335     34 
    <dd>This returns the request parameters (fields) found in the request
 
 paulb@335     35 
      body (as defined in Web forms). The fields are provided in a dictionary
 
 paulb@335     36 
      mapping field names to lists of values. Each value will be a Unicode
 
 paulb@335     37 
      object unless the value represents uploaded file content (see
 
 paulb@335     38 
      below).<br />
 
 paulb@335     39 
      An optional <code>encoding</code> parameter may be used to assist the
 
 paulb@335     40 
      process of converting parameter values to Unicode objects - see below
 
 paulb@335     41 
      for a discussion of the issues with this parameter.</dd>
 
 paulb@335     42 
</dl>
 
 paulb@335     43 
</div>
 
 paulb@335     44 
 
 paulb@335     45 
<p>Some limitations exist with request body parameters:</p>
 
 paulb@335     46 
<ul>
 
 paulb@335     47 
  <li>For the conversion of such parameters to Unicode to function correctly,
 
 paulb@470     48 
    care must be taken with character encodings - this is discussed in <a href="responses.html">"Responses and Presentation"</a> and also in <a href="encodings.html">"Character Encodings"</a>.</li>
 
 paulb@335     49 
</ul>
 
 paulb@335     50 
 
 paulb@335     51 
<h2>File Uploads</h2>
 
 paulb@335     52 
 
 paulb@335     53 
<p>One way request body parameters may be used is to provide a mechanism for
 
 paulb@335     54 
the uploading of entire files from browsers and other Web clients to
 
 paulb@335     55 
applications. Unlike other parameters, those which carry file upload data
 
 paulb@335     56 
expose the contents of such uploaded files as plain Python string values
 
 paulb@335     57 
instead of Unicode objects.</p>
 
 paulb@470     58 
<h3>Unsupported Environments and Framework Issues</h3>
 
 paulb@470     59 
<ul>
 
 paulb@470     60 
  <li>Twisted does not provide file upload data as raw string values;
 
 paulb@470     61 
instead, file upload data will be decoded and returned as Unicode from
 
 paulb@470     62 
WebStack. This behaviour is due to the way Twisted processes the
 
 paulb@470     63 
incoming request and may be fixed in a future release.</li>
 
 paulb@470     64 
</ul>
 
 paulb@470     65 
 
 paulb@470     66 
</body></html>