1.1 --- a/docs/parameters.html Mon Apr 25 22:19:20 2005 +0000
1.2 +++ b/docs/parameters.html Tue Apr 26 18:33:06 2005 +0000
1.3 @@ -1,106 +1,121 @@
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 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.8 <html xmlns="http://www.w3.org/1999/xhtml">
1.9 <head>
1.10 <title>Request Parameters and Uploads</title>
1.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 + <meta name="generator"
1.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.14 <link href="styles.css" rel="stylesheet" type="text/css" />
1.15 </head>
1.16 -
1.17 <body>
1.18 <h1>Request Parameters and Uploads</h1>
1.19 -
1.20 -<p>Even though it is possible to expose different parts of an application
1.21 -using different <a href="paths.html">URLs and paths</a>, this usually is only
1.22 +<p>Even though it is possible to expose different parts of an
1.23 +application
1.24 +using different <a href="paths.html">URLs and paths</a>, this usually
1.25 +is only
1.26 enough for applications which model some kind of <a
1.27 -href="paths-filesystem.html">filesystem</a> or repository. Applications which
1.28 -involve user input through forms, for example, need to be able to receive
1.29 -such input by other means, and this is where request parameters come in. For
1.30 + href="paths-filesystem.html">filesystem</a> or repository.
1.31 +Applications which
1.32 +involve user input through forms, for example, need to be able to
1.33 +receive
1.34 +such input by other means, and this is where request parameters come
1.35 +in. For
1.36 example, when a user fills out a form in a Web browser, the following
1.37 happens:</p>
1.38 <ol>
1.39 - <li>The browser collects the values in the form fields and puts them in a
1.40 - request as request parameters.</li>
1.41 + <li>The browser collects the values in the form fields and puts them
1.42 +in a request as request parameters.</li>
1.43 <li>The request is sent to the server environment and into the
1.44 - application.</li>
1.45 +application.</li>
1.46 <li>The application reads the field values using the WebStack API.</li>
1.47 </ol>
1.48 -
1.49 <h2>Parameter Origins</h2>
1.50 -
1.51 <p>Request parameters can originate from two sources:</p>
1.52 <ul>
1.53 - <li><a href="parameters-headers.html">Request headers</a> - parameters are
1.54 - found here when they are specified in the URL as a "query string".</li>
1.55 - <li><a href="parameters-body.html">Request bodies</a> - parameters are
1.56 - found here when the POST <a href="methods.html">request method</a> is
1.57 - used.</li>
1.58 + <li><a href="parameters-headers.html">Request headers</a> -
1.59 +parameters are found here when they are specified in the URL as a
1.60 +"query string".</li>
1.61 + <li><a href="parameters-body.html">Request bodies</a> - parameters
1.62 +are found here when the POST <a href="methods.html">request method</a>
1.63 +is used.</li>
1.64 </ul>
1.65 -
1.66 -<p>One useful application of parameters transferred in request bodies is the
1.67 +<p>One useful application of parameters transferred in request bodies
1.68 +is the
1.69 sending or uploading of file contents through such parameters - this is
1.70 -described in "Request Body Parameters". Another way of uploading content in
1.71 +described in "Request Body Parameters". Another way of uploading
1.72 +content in
1.73 conjunction with the <code>PUT</code> <a href="methods.html">request
1.74 method</a> is mentioned below.</p>
1.75 -
1.76 <div class="WebStack">
1.77 <h3>WebStack API - Getting All Parameters</h3>
1.78 -
1.79 -<p>If the origin of the different parameters received in a request is not
1.80 -particularly interesting or important, WebStack provides a convenience method
1.81 +<p>If the origin of the different parameters received in a request is
1.82 +not
1.83 +particularly interesting or important, WebStack provides a convenience
1.84 +method
1.85 in transaction objects to get all known parameters from a request:</p>
1.86 <dl>
1.87 <dt><code>get_fields</code></dt>
1.88 - <dd>This method returns a dictionary mapping field names to lists of
1.89 - values for all known parameters. Each value will be a Unicode
1.90 - object.<br />
1.91 - An optional <code>encoding</code> parameter may be used to assist the
1.92 - process of converting parameter values to Unicode objects - see <a
1.93 - href="parameters-body.html">"Request Body Parameters"</a> and <a
1.94 - href="encodings.html">"Character Encodings"</a> for more discussion of
1.95 - this parameter.</dd>
1.96 + <dd>This method returns a dictionary mapping field names to lists of
1.97 +values for all known parameters. Each value will be a Unicode object.<br />
1.98 +An optional <code>encoding</code> parameter may be used to assist the
1.99 +process of converting parameter values to Unicode objects - see <a
1.100 + href="parameters-body.html">"Request Body Parameters"</a> and <a
1.101 + href="encodings.html">"Character Encodings"</a> for more discussion of
1.102 +this parameter.</dd>
1.103 + <dt><code>get_query_string</code></dt>
1.104 + <dd>This method returns the part of the URL which contains parameter
1.105 +information. Such information will be "URL-encoded", meaning that
1.106 +certain characters will have the form <code>%xx</code> where <code>xx</code>
1.107 +is a two digit hexadecimal number referring to the byte value of the
1.108 +unencoded character - see <a href="encodings.html">"Character
1.109 +Encodings"</a> for information on how byte values should be
1.110 +interpreted. </dd>
1.111 </dl>
1.112 </div>
1.113 -
1.114 -<p>Generally, it is not recommended to just get all parameters since there
1.115 -may be some parameters from the request headers which have the same names as
1.116 -some other parameters from the request body. Consequently, confusion could
1.117 +<p>Generally, it is not recommended to just get all parameters since
1.118 +there
1.119 +may be some parameters from the request headers which have the same
1.120 +names as
1.121 +some other parameters from the request body. Consequently, confusion
1.122 +could
1.123 arise about the significance of various parameter values.</p>
1.124 -
1.125 <h2>Using PUT Requests to Upload Files</h2>
1.126 -
1.127 -<p>When handling requests in your application, instead of treating request as
1.128 -containers of parameters and using the WebStack API methods to access those
1.129 -parameters, you can instead choose to read directly from the data sent by the
1.130 -user and interpret that data in your own way. In most situations, this is not
1.131 -really necessary - those methods will decode request parameters (for example,
1.132 -form fields) in a way which is fairly convenient - but when files are being
1.133 -sent, and when the <a href="methods.html">request method</a> is specified as
1.134 -<code>PUT</code>, it is necessary to obtain the input stream from the request
1.135 +<p>When handling requests in your application, instead of treating
1.136 +request as
1.137 +containers of parameters and using the WebStack API methods to access
1.138 +those
1.139 +parameters, you can instead choose to read directly from the data sent
1.140 +by the
1.141 +user and interpret that data in your own way. In most situations, this
1.142 +is not
1.143 +really necessary - those methods will decode request parameters (for
1.144 +example,
1.145 +form fields) in a way which is fairly convenient - but when files are
1.146 +being
1.147 +sent, and when the <a href="methods.html">request method</a> is
1.148 +specified as
1.149 +<code>PUT</code>, it is necessary to obtain the input stream from the
1.150 +request
1.151 and to read the file contents from that stream.</p>
1.152 -
1.153 <div class="WebStack">
1.154 <h3>WebStack API - Reading Directly from Requests</h3>
1.155 -
1.156 <p>When the request does not contain standard form-encoded parameter
1.157 -information and instead contains the contents of an uploaded file, methods
1.158 -like <code>get_fields</code> and <code>get_fields_from_body</code> should be
1.159 +information and instead contains the contents of an uploaded file,
1.160 +methods
1.161 +like <code>get_fields</code> and <code>get_fields_from_body</code>
1.162 +should be
1.163 avoided and other methods in the transaction employed.</p>
1.164 <dl>
1.165 <dt><code>get_request_stream</code></dt>
1.166 - <dd>This returns the input stream associated with the request. Reading
1.167 - from this will result in the request body being obtained as a plain
1.168 - Python string.</dd>
1.169 + <dd>This returns the input stream associated with the request.
1.170 +Reading from this will result in the request body being obtained as a
1.171 +plain Python string.</dd>
1.172 <dt><code>get_content_type</code></dt>
1.173 - <dd>This returns a content type object (typically
1.174 - <code>WebStack.Generic.ContentType</code>) which describes the request
1.175 - body's contents.</dd>
1.176 + <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>)
1.177 +which describes the request body's contents.</dd>
1.178 </dl>
1.179 </div>
1.180 -
1.181 <p>The purpose and behaviour of <code>PUT</code> <a
1.182 -href="methods.html">request methods</a> is described in the HTTP
1.183 + href="methods.html">request methods</a> is described in the HTTP
1.184 specification.</p>
1.185 </body>
1.186 </html>