WebStack

Annotated docs/parameters-headers.html

654:9156c2205b8f
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@436 1 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@436 2 
<html xmlns="http://www.w3.org/1999/xhtml"><head>
paulb@436 3
paulb@436 4 
  <title>Request Header Parameters</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
paulb@436 5 
  <link href="styles.css" rel="stylesheet" type="text/css" /></head>
paulb@470 6 
<body>
paulb@470 7 
<h1>Request Header Parameters</h1>
paulb@335 8 
 
 paulb@335      9 
 
 paulb@335     10 
<p>Header parameters are typically specified in the URL like this:</p>
 
 paulb@335     11 
<pre>http://www.boddie.org.uk/application?param1=value1&amp;param2=value2</pre>
 
 paulb@335     12 
 
 paulb@335     13 
<p>Following the rules set out in <a href="paths.html">"URLs and Paths"</a>,
 
 paulb@335     14 
we can say that the "query string" employed is this:</p>
 
 paulb@335     15 
<pre>param1=value1&amp;param2=value2</pre>
 
 paulb@335     16 
 
 paulb@335     17 
<p>From this string, we may extract the parameters and state that they are
 
 paulb@335     18 
the following:</p>
 
 paulb@335     19 
<ul>
 
 paulb@335     20 
  <li><code>param1</code> with the value <code>value1</code></li>
 
 paulb@335     21 
  <li><code>param2</code> with the value <code>value2</code></li>
 
 paulb@335     22 
</ul>
 
 paulb@335     23 
 
 paulb@335     24 
<p>Parameters encoded in this way can be written into hyperlinks and may be
 
 paulb@335     25 
used to remember things as users navigate their way around an application.
 
 paulb@436     26 
Alternatively, a Web form (in HTML) written to use the <code>GET</code> <a href="methods.html">request method</a> may be used to achieve the same
 
 paulb@335     27 
effect:</p>
 
 paulb@488     28 
<pre>&lt;form method="get" 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     29 
 
 paulb@335     30 
<div class="WebStack">
 
 paulb@335     31 
<h3>WebStack API - Accessing Header Parameters</h3>
 
 paulb@335     32 
 
 paulb@335     33 
<p>Transaction objects provide the following methods to access parameters
 
 paulb@335     34 
specified in request headers. The terminology used in the API describes such
 
 paulb@335     35 
parameters as path fields, since such parameters are often provided by form
 
 paulb@335     36 
fields.</p>
 
 paulb@335     37 
<dl>
 
 paulb@335     38 
  <dt><code>get_fields_from_path</code></dt>
 
 paulb@335     39 
    <dd>This returns the request parameters (fields) from the request headers
 
 paulb@335     40 
      (as defined in the path or URL). The fields are provided in a
 
 paulb@436     41 
      dictionary mapping field names to lists of values<br />
 
 paulb@436     42 
An optional&nbsp;<code>encoding</code> parameter may be used to assist
 
 paulb@436     43 
the process of converting parameter values to Unicode objects - see
 
 paulb@436     44 
below for a discussion of the issues with this parameter.</dd>
 
 paulb@335     45 
  <dt><code>get_query_string</code></dt>
 
 paulb@335     46 
    <dd>This returns the query string - ie. the part of the path or URL which
 
 paulb@335     47 
      contains the parameters. Typically, it is easier to use the above
 
 paulb@335     48 
      method instead.</dd>
 
 paulb@335     49 
</dl>
 
 paulb@335     50 
</div>
 
 paulb@335     51 
 
 paulb@335     52 
<p>There are some limitations with header parameters:</p>
 
 paulb@335     53 
<ul>
 
 paulb@335     54 
  <li>Since URLs are used to carry such parameters, any such parameter which
 
 paulb@335     55 
    should remain hidden will appear in the URL and probably be shown in
 
 paulb@335     56 
    browsers and other user interfaces.</li>
 
 paulb@335     57 
  <li>There isn't widespread agreement about how non-ASCII characters should
 
 paulb@436     58 
    be encoded in URLs. WebStack attempts to handle the ambiguity, but does require some assistance...</li><li>For
 
 paulb@436     59 
the conversion of such parameters to Unicode to function correctly,
 
 paulb@436     60 
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>.<br />
 
 paulb@436     61 
  </li>
 
 paulb@436     62 
 
 paulb@335     63 
</ul>
 
 paulb@436     64 
</body></html>