1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/path-value-encoding.html Wed Nov 16 18:27:45 2005 +0000
1.3 @@ -0,0 +1,30 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.7 +
1.8 + <title>Encoding and Decoding Path Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.10 +<body>
1.11 +<h1>Encoding and Decoding Path Values</h1><p>On some occasions it can
1.12 +be necessary to manually decode path values, producing genuine Unicode
1.13 +objects, and then to encode them, producing plain strings that can be
1.14 +used in response headers and other places. For such occasions, some
1.15 +transaction methods are available:</p><div class="WebStack">
1.16 +<h3>WebStack API - Encoding and Decoding Path Values</h3>
1.17 +<p>WebStack provides the following methods to transform path values:</p>
1.18 +<dl><dt><code>decode_path</code></dt><dd>This method accepts a path containing "URL encoded" information (as defined in the <a href="paths.html">"URLs and Paths"</a>
1.19 +document) and, using an optional encoding parameter, returns a Unicode
1.20 +object containing genuine character values in place of the "URL
1.21 +encoded" values.</dd><dt><code>encode_path</code></dt><dd>This method
1.22 +accepts a Unicode object containing the path and an optional encoding
1.23 +parameter; it reverses the process carried out by the <code>decode_path</code> method.</dd></dl>
1.24 +</div><p>Generally, the <code>decode_path</code> method is of little interest; its only relatively common application might be to decode query strings:</p><pre>qs = trans.get_query_string() # eg. "a=%E6"<br />new_qs = trans.decode_path(qs, "iso-8859-1") # producing "a=æ"</pre><p>Such operations are generally better performed using the <a href="parameters.html">request parameter methods</a>.</p><p>The <code>encode_path</code>
1.25 +method is slightly more useful: since various transaction methods
1.26 +return values which have already been transformed into Unicode objects,
1.27 +we must consider the use of <code>encode_path</code> to produce values
1.28 +which are suitable for feeding into other methods. For example, having
1.29 +obtained a path, we may wish to cause a <a href="redirection.html">redirect</a> to another location
1.30 +based on that path:</p><pre>path = trans.get_path_without_query("iso-8859-1") # eg. "/app/resource"<br />path += "/æøå"<br />new_path = trans.encode_path(path, "iso-8859-1") # producing "/app/resource/%E6%F8%E5"<br />trans.redirect(new_path)</pre><p>It
1.31 +is essential to encode the path in such situations because the
1.32 +underlying mechanisms do not support the full range of Unicode
1.33 +characters. Some cases where this limitation exists are listed in the <a href="encodings.html">"Character Encodings"</a> document.</p></body></html>
1.34 \ No newline at end of file