WebStack

Annotated docs/parameters.html

470:e7963e3448d8
383:74ed715c5455
357:b086884cf017
2005-05-01 paulb file changeset files shortlog [project @ 2005-05-01 18:16:52 by paulb] Added missing example for Zope.
paulb@357 1 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@335 2 
<html xmlns="http://www.w3.org/1999/xhtml">
paulb@335 3 
<head>
paulb@335 4 
  <title>Request Parameters and Uploads</title>
paulb@357 5 
  <meta name="generator"
paulb@357 6 
 content="amaya 8.1a, see http://www.w3.org/Amaya/" />
paulb@335 7 
  <link href="styles.css" rel="stylesheet" type="text/css" />
paulb@335 8 
</head>
paulb@335 9 
<body>
paulb@335 10 
<h1>Request Parameters and Uploads</h1>
paulb@357 11 
<p>Even though it is possible to expose different parts of an
paulb@357 12 
application
paulb@357 13 
using different <a href="paths.html">URLs and paths</a>, this usually
paulb@357 14 
is only
paulb@335 15 
enough for applications which model some kind of <a
paulb@357 16 
 href="paths-filesystem.html">filesystem</a> or repository.
paulb@357 17 
Applications which
paulb@357 18 
involve user input through forms, for example, need to be able to
paulb@357 19 
receive
paulb@357 20 
such input by other means, and this is where request parameters come
paulb@357 21 
in. For
paulb@335 22 
example, when a user fills out a form in a Web browser, the following
paulb@335 23 
happens:</p>
paulb@335 24 
<ol>
paulb@357 25 
  <li>The browser collects the values in the form fields and puts them
paulb@357 26 
in a request as request parameters.</li>
paulb@335 27 
  <li>The request is sent to the server environment and into the
paulb@357 28 
application.</li>
paulb@335 29 
  <li>The application reads the field values using the WebStack API.</li>
paulb@335 30 
</ol>
paulb@335 31 
<h2>Parameter Origins</h2>
paulb@335 32 
<p>Request parameters can originate from two sources:</p>
paulb@335 33 
<ul>
paulb@357 34 
  <li><a href="parameters-headers.html">Request headers</a> -
paulb@357 35 
parameters are found here when they are specified in the URL as a
paulb@357 36 
"query string".</li>
paulb@357 37 
  <li><a href="parameters-body.html">Request bodies</a> - parameters
paulb@357 38 
are found here when the POST <a href="methods.html">request method</a>
paulb@357 39 
is used.</li>
paulb@335 40 
</ul>
paulb@357 41 
<p>One useful application of parameters transferred in request bodies
paulb@357 42 
is the
paulb@346 43 
sending or uploading of file contents through such parameters - this is
paulb@357 44 
described in "Request Body Parameters". Another way of uploading
paulb@357 45 
content in
paulb@346 46 
conjunction with the <code>PUT</code> <a href="methods.html">request
paulb@346 47 
method</a> is mentioned below.</p>
paulb@335 48 
<div class="WebStack">
paulb@335 49 
<h3>WebStack API - Getting All Parameters</h3>
paulb@357 50 
<p>If the origin of the different parameters received in a request is
paulb@357 51 
not
paulb@357 52 
particularly interesting or important, WebStack provides a convenience
paulb@357 53 
method
paulb@335 54 
in transaction objects to get all known parameters from a request:</p>
paulb@335 55 
<dl>
paulb@335 56 
  <dt><code>get_fields</code></dt>
paulb@357 57 
  <dd>This method returns a dictionary mapping field names to lists of
paulb@357 58 
values for all known parameters. Each value will be a Unicode object.<br />
paulb@357 59 
An optional <code>encoding</code> parameter may be used to assist the
paulb@357 60 
process of converting parameter values to Unicode objects - see <a
paulb@357 61 
 href="parameters-body.html">"Request Body Parameters"</a> and <a
paulb@357 62 
 href="encodings.html">"Character Encodings"</a> for more discussion of
paulb@357 63 
this parameter.</dd>
paulb@357 64 
  <dt><code>get_query_string</code></dt>
paulb@357 65 
  <dd>This method returns the part of the URL which contains parameter
paulb@357 66 
information. Such information will be "URL-encoded", meaning that
paulb@357 67 
certain characters will have the form&nbsp;<code>%xx</code> where&nbsp;<code>xx</code>
paulb@357 68 
is a two digit hexadecimal number referring to the byte value of the
paulb@357 69 
unencoded character - see&nbsp;<a href="encodings.html">"Character
paulb@357 70 
Encodings"</a> for information on how byte values should be
paulb@357 71 
interpreted. </dd>
paulb@335 72 
</dl>
paulb@335 73 
</div>
paulb@357 74 
<p>Generally, it is not recommended to just get all parameters since
paulb@357 75 
there
paulb@357 76 
may be some parameters from the request headers which have the same
paulb@357 77 
names as
paulb@357 78 
some other parameters from the request body. Consequently, confusion
paulb@357 79 
could
paulb@335 80 
arise about the significance of various parameter values.</p>
paulb@346 81 
<h2>Using PUT Requests to Upload Files</h2>
paulb@357 82 
<p>When handling requests in your application, instead of treating
paulb@357 83 
request as
paulb@357 84 
containers of parameters and using the WebStack API methods to access
paulb@357 85 
those
paulb@357 86 
parameters, you can instead choose to read directly from the data sent
paulb@357 87 
by the
paulb@357 88 
user and interpret that data in your own way. In most situations, this
paulb@357 89 
is not
paulb@357 90 
really necessary - those methods will decode request parameters (for
paulb@357 91 
example,
paulb@357 92 
form fields) in a way which is fairly convenient - but when files are
paulb@357 93 
being
paulb@357 94 
sent, and when the <a href="methods.html">request method</a> is
paulb@357 95 
specified as
paulb@357 96 
<code>PUT</code>, it is necessary to obtain the input stream from the
paulb@357 97 
request
paulb@346 98 
and to read the file contents from that stream.</p>
paulb@346 99 
<div class="WebStack">
paulb@346 100 
<h3>WebStack API - Reading Directly from Requests</h3>
paulb@346 101 
<p>When the request does not contain standard form-encoded parameter
paulb@357 102 
information and instead contains the contents of an uploaded file,
paulb@357 103 
methods
paulb@357 104 
like <code>get_fields</code> and <code>get_fields_from_body</code>
paulb@357 105 
should be
paulb@346 106 
avoided and other methods in the transaction employed.</p>
paulb@346 107 
<dl>
paulb@346 108 
  <dt><code>get_request_stream</code></dt>
paulb@357 109 
  <dd>This returns the input stream associated with the request.
paulb@357 110 
Reading from this will result in the request body being obtained as a
paulb@357 111 
plain Python string.</dd>
paulb@346 112 
  <dt><code>get_content_type</code></dt>
paulb@357 113 
  <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>)
paulb@357 114 
which describes the request body's contents.</dd>
paulb@346 115 
</dl>
paulb@346 116 
</div>
paulb@346 117 
<p>The purpose and behaviour of <code>PUT</code> <a
paulb@357 118 
 href="methods.html">request methods</a> is described in the HTTP
paulb@346 119 
specification.</p>
paulb@335 120 
</body>
paulb@335 121 
</html>