WebStack

Annotated docs/parameters-headers.html

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