1.1 --- a/docs/developing.html Wed Nov 16 18:27:07 2005 +0000
1.2 +++ b/docs/developing.html Wed Nov 16 18:27:45 2005 +0000
1.3 @@ -32,7 +32,7 @@
1.4 <li><a href="paths-services.html">Treating the Path Mostly Like a Filesystem</a></li>
1.5 <li><a href="paths-opaque.html">Using the Path as an Opaque Reference into an Application</a></li>
1.6
1.7 - </ul>
1.8 + </ul><li><a href="path-value-encoding.html">Encoding and Decoding Path Values</a></li><li><a href="path-manipulation.html">Manipulating Paths</a></li>
1.9
1.10 <li><a href="path-info-support.html">Path Info Support in Server Environments</a></li>
1.11
2.1 --- a/docs/path-info.html Wed Nov 16 18:27:07 2005 +0000
2.2 +++ b/docs/path-info.html Wed Nov 16 18:27:45 2005 +0000
2.3 @@ -83,10 +83,10 @@
2.4 <tr>
2.5 <td align="undefined" valign="undefined">Path</td>
2.6 <td align="undefined" valign="undefined">Building links to
2.7 -resources within an application - subtract the "path info" from
2.8 -the end and you should get the location of the application.</td>
2.9 +resources within an application.</td>
2.10 </tr>
2.11 - <tr>
2.12 + <tr><td align="undefined" valign="undefined">Path without path info</td><td align="undefined" valign="undefined">Finding the location of the application in a server environment. (This is the path with the "path info" subtracted from
2.13 +the end.)</td></tr><tr>
2.14 <td align="undefined" valign="undefined">Path info</td>
2.15 <td align="undefined" valign="undefined">Determining which
2.16 resources are being accessed within an application.</td>
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/path-manipulation.html Wed Nov 16 18:27:45 2005 +0000
3.3 @@ -0,0 +1,13 @@
3.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
3.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.7 +
3.8 + <title>Manipulating Paths</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.10 +<body>
3.11 +<h1>Manipulating Paths</h1><p>Whilst path values are useful in telling
3.12 +us something about where a particular resource resides or how far the
3.13 +processing of a resource has progressed, it is sometimes useful to
3.14 +apply some kind of transformation to the path in order to produce a
3.15 +reference to another resource or application. Consider the simple case
3.16 +of <a href="redirection.html">redirecting</a> a user to another resource:</p><p>First we must obtain a reference to the current resource:<br /></p><pre>this_resource = trans.get_path_without_query() # eg. "/app/resource/some-data"</pre><p>We may wish to redirect the user to the main application resource; this is done by removing <code>resource</code> from the end of the path:</p><pre>this_app = trans.update_path("..") # produces "/app/resource"</pre><p>A complete description of this method can be found in the API documentation.</p></body></html>
3.17 \ No newline at end of file
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/path-value-encoding.html Wed Nov 16 18:27:45 2005 +0000
4.3 @@ -0,0 +1,30 @@
4.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
4.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.7 +
4.8 + <title>Encoding and Decoding Path Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.10 +<body>
4.11 +<h1>Encoding and Decoding Path Values</h1><p>On some occasions it can
4.12 +be necessary to manually decode path values, producing genuine Unicode
4.13 +objects, and then to encode them, producing plain strings that can be
4.14 +used in response headers and other places. For such occasions, some
4.15 +transaction methods are available:</p><div class="WebStack">
4.16 +<h3>WebStack API - Encoding and Decoding Path Values</h3>
4.17 +<p>WebStack provides the following methods to transform path values:</p>
4.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>
4.19 +document) and, using an optional encoding parameter, returns a Unicode
4.20 +object containing genuine character values in place of the "URL
4.21 +encoded" values.</dd><dt><code>encode_path</code></dt><dd>This method
4.22 +accepts a Unicode object containing the path and an optional encoding
4.23 +parameter; it reverses the process carried out by the <code>decode_path</code> method.</dd></dl>
4.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>
4.25 +method is slightly more useful: since various transaction methods
4.26 +return values which have already been transformed into Unicode objects,
4.27 +we must consider the use of <code>encode_path</code> to produce values
4.28 +which are suitable for feeding into other methods. For example, having
4.29 +obtained a path, we may wish to cause a <a href="redirection.html">redirect</a> to another location
4.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
4.31 +is essential to encode the path in such situations because the
4.32 +underlying mechanisms do not support the full range of Unicode
4.33 +characters. Some cases where this limitation exists are listed in the <a href="encodings.html">"Character Encodings"</a> document.</p></body></html>
4.34 \ No newline at end of file
5.1 --- a/docs/paths.html Wed Nov 16 18:27:07 2005 +0000
5.2 +++ b/docs/paths.html Wed Nov 16 18:27:45 2005 +0000
5.3 @@ -58,6 +58,12 @@
5.4 <dd>This gets the entire path of a resource but without any parameter
5.5 information.<br />
5.6
5.7 +An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd><dt><code>get_path_without_info</code></dt><dd>This gets the entire path of a resource but without any parameter
5.8 +information or any special "path info" (as described in <a href="path-info.html">"Paths To and Within Applications"</a>).
5.9 +The result is more or less equivalent to the location where an
5.10 +application has been "published" - ie. the location of an application
5.11 +in a server environment.<br />
5.12 +
5.13 An optional <code>encoding</code> parameter may be used to assist the process of converting the path to a Unicode object - see below.</dd>
5.14 </dl>
5.15 </div>
5.16 @@ -124,7 +130,7 @@
5.17 <h2>More About Paths</h2>
5.18 <ul>
5.19 <li><a href="path-info.html">Paths To and Within Applications</a></li>
5.20 - <li><a href="path-design.html">Path Design and Interpretation</a></li>
5.21 + <li><a href="path-design.html">Path Design and Interpretation</a></li><li><a href="path-value-encoding.html">Encoding and Decoding Path Values</a></li><li><a href="path-manipulation.html">Manipulating Paths</a></li>
5.22 <li><a href="path-info-support.html">Path Info Support in Server
5.23 Environments</a></li>
5.24 </ul>
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/redirection.html Wed Nov 16 18:27:45 2005 +0000
6.3 @@ -0,0 +1,18 @@
6.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
6.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
6.7 +
6.8 + <title>Redirection</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
6.10 +
6.11 +<body>
6.12 +<h1>Redirection</h1><p>Instead of presenting information to a user when
6.13 +that user visits a particular URL, we may instead choose to redirect
6.14 +that user to another URL, at which there may be information to be
6.15 +viewed. To redirect a user of an application, we can use the following
6.16 +transaction method:</p><div class="WebStack">
6.17 +<h3>WebStack API - Redirection</h3>
6.18 +<p>WebStack provides the following method to perform redirection:</p>
6.19 +<dl><dt><code>redirect</code></dt><dd>This method accepts a path value
6.20 +suitable for use in response headers indicating the location to which a
6.21 +user shall be redirected. An optional response code (see <a href="responses.html">"Responses and Presentation"</a>) can be specified to modify the meaning of the redirection (as defined in the HTTP specifications).</dd></dl></div><p>Since the path value must be usable in response header, it is necessary to transform paths as described in the <a href="path-value-encoding.html">"Encoding and Decoding Path Values"</a> document, and an example of redirection is given in that document.</p></body></html>
6.22 \ No newline at end of file