1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/parameters-body.html Sun Apr 10 21:11:25 2005 +0000
1.3 @@ -0,0 +1,70 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<html xmlns="http://www.w3.org/1999/xhtml">
1.8 +<head>
1.9 + <title>Request Body Parameters</title>
1.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +
1.14 +<body>
1.15 +<h1>Request Body Parameters</h1>
1.16 +
1.17 +<p>Request parameters are typically added to the request body when forms are
1.18 +submitted by a browser which is instructed to use the <code>POST</code> <a
1.19 +href="methods.html">request method</a>. A Web form (in HTML) can be used to
1.20 +achieve this; for example:</p>
1.21 +<pre><form method="POST" action="http://www.boddie.org.uk/application">
1.22 + <input name="param1" type="text" />
1.23 + <input name="param2" type="text" />
1.24 +</form></pre>
1.25 +
1.26 +<p>As a consequence of this form being submitted, the following parameters
1.27 +will become available in the application:</p>
1.28 +<ul>
1.29 + <li><code>param1</code> with the value <code><code>value1</code></code></li>
1.30 + <li><code><code>param2</code></code> with the value <code>value2</code></li>
1.31 +</ul>
1.32 +
1.33 +<p>Parameters encoded in this way are not transferred in URLs and are mostly
1.34 +hidden in user interfaces, although viewing a Web page's source can often
1.35 +reveal default values of such parameters.</p>
1.36 +
1.37 +<div class="WebStack">
1.38 +<h3>WebStack API - Accessing Body Parameters</h3>
1.39 +
1.40 +<p>Transaction objects provide the following methods to access parameters
1.41 +specified in request headers. The terminology used in the API describes such
1.42 +parameters as body fields, since such parameters are often provided by form
1.43 +fields.</p>
1.44 +<dl>
1.45 + <dt><code>get_fields_from_body</code></dt>
1.46 + <dd>This returns the request parameters (fields) found in the request
1.47 + body (as defined in Web forms). The fields are provided in a dictionary
1.48 + mapping field names to lists of values. Each value will be a Unicode
1.49 + object unless the value represents uploaded file content (see
1.50 + below).<br />
1.51 + An optional <code>encoding</code> parameter may be used to assist the
1.52 + process of converting parameter values to Unicode objects - see below
1.53 + for a discussion of the issues with this parameter.</dd>
1.54 +</dl>
1.55 +</div>
1.56 +
1.57 +<p>Some limitations exist with request body parameters:</p>
1.58 +<ul>
1.59 + <li>For the conversion of such parameters to Unicode to function correctly,
1.60 + care must be taken with character encodings - this is discussed in <a
1.61 + href="responses.html">"Responses and Presentation"</a> and also in <a
1.62 + href="encodings.html">"Character Encodings"</a>.</li>
1.63 +</ul>
1.64 +
1.65 +<h2>File Uploads</h2>
1.66 +
1.67 +<p>One way request body parameters may be used is to provide a mechanism for
1.68 +the uploading of entire files from browsers and other Web clients to
1.69 +applications. Unlike other parameters, those which carry file upload data
1.70 +expose the contents of such uploaded files as plain Python string values
1.71 +instead of Unicode objects.</p>
1.72 +</body>
1.73 +</html>