1.1 --- a/docs/paths.html Mon Apr 25 22:19:20 2005 +0000
1.2 +++ b/docs/paths.html Tue Apr 26 18:33:06 2005 +0000
1.3 @@ -1,176 +1,82 @@
1.4 -<?xml version="1.0" encoding="iso-8859-1"?>
1.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.8 <html xmlns="http://www.w3.org/1999/xhtml">
1.9 <head>
1.10 <title>URLs and Paths</title>
1.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 + <meta name="generator"
1.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.14 <link href="styles.css" rel="stylesheet" type="text/css" />
1.15 </head>
1.16 -
1.17 <body>
1.18 <h1>URLs and Paths</h1>
1.19 -
1.20 -<p>The URL at which your application shall appear is arguably the first part
1.21 -of the application's user interface that any user will see. In this context,
1.22 +<p>The URL at which your application shall appear is arguably the first
1.23 +part
1.24 +of the application's user interface that any user will see. Remember
1.25 +that a user of your application does not have to be a real person; in
1.26 +fact,
1.27 a user can be any of the following things:</p>
1.28 <ul>
1.29 <li>A real person entering the URL into a browser's address bar.</li>
1.30 <li>A real person linking to your application by writing the URL in a
1.31 - separate Web page.</li>
1.32 - <li>A program which has the URL defined within it and which may manipulate
1.33 - the URL to perform certain kinds of operations.</li>
1.34 +separate Web page.</li>
1.35 + <li>A program which has the URL defined within it and which may
1.36 +manipulate the URL to perform certain kinds of operations.</li>
1.37 </ul>
1.38 -
1.39 +<p>Some application developers have a fairly rigid view of what kind of
1.40 +information a URL should contain and how it should be structured. In
1.41 +this guide, we shall look at a number of different approaches.</p>
1.42 <h2>Interpreting Path Information</h2>
1.43 -
1.44 -<p>What the URL is supposed to do is to say where (on the Internet or on an
1.45 -intranet) your application resides and which resource or service is being
1.46 +<p>What the URL is supposed to do is to say where (on the Internet or
1.47 +on an
1.48 +intranet) your application resides and which resource or service is
1.49 +being
1.50 accessed, and these look like this:</p>
1.51 <pre>http://www.boddie.org.uk/python/WebStack.html</pre>
1.52 -
1.53 -<p>With WebStack, we also talk about a "path" as being just the part of the
1.54 -URL which refers to the resource or service, ignoring the actual Internet
1.55 -address, and so these look like this:</p>
1.56 +<p>In an application the full URL, containing the address of the
1.57 +machine on which it is running, is not always interesting. In the
1.58 +WebStack API (and in other Web programming frameworks), we also talk
1.59 +about "paths" - a path is just the part of the
1.60 +URL which refers to the resource or service, ignoring the actual
1.61 +Internet
1.62 +address, and so the above example would have a path which looks like
1.63 +this:</p>
1.64 <pre>/python/WebStack.html</pre>
1.65 -
1.66 <p>When writing a Web application, most of the time you just need to
1.67 -concentrate on the path because the address doesn't usually tell you anything
1.68 +concentrate on the path because the address doesn't usually tell you
1.69 +anything
1.70 you don't already know. What you need to do is to interpret the path
1.71 -specified in the request in order to work out which resource or service the
1.72 -request is destined for.</p>
1.73 -
1.74 +specified in the request in order to work out which resource or service
1.75 +the user is trying to access.</p>
1.76 <div class="WebStack">
1.77 <h3>WebStack API - Path Methods in Transaction Objects</h3>
1.78 -
1.79 -<p>WebStack provides the following transaction methods for inspecting path
1.80 +<p>WebStack provides the following transaction methods for inspecting
1.81 +path
1.82 information:</p>
1.83 <dl>
1.84 <dt><code>get_path</code></dt>
1.85 - <dd>This gets the entire path of a resource including parameter
1.86 - information (as described in <a href="parameters.html">"Request
1.87 - Parameters and Uploads"</a>).</dd>
1.88 + <dd>This gets the entire path of a resource including parameter
1.89 +information (as described in <a href="parameters.html">"Request
1.90 +Parameters and Uploads"</a>).</dd>
1.91 <dt><code>get_path_without_query</code></dt>
1.92 - <dd>This gets the entire path of a resource but without any parameter
1.93 - information.</dd>
1.94 + <dd>This gets the entire path of a resource but without any parameter
1.95 +information.</dd>
1.96 </dl>
1.97 </div>
1.98 -
1.99 +<h2>Query Strings</h2>
1.100 <p>Sometimes, a "query string" will be provided as part of a URL; for
1.101 example:</p>
1.102 <pre>http://www.boddie.org.uk/application?param1=value1</pre>
1.103 -
1.104 -<p>The question mark character marks the beginning of the query string which
1.105 -contains encoded parameter information; such information and its inspection
1.106 +<p>The question mark character marks the beginning of the query string
1.107 +which
1.108 +contains encoded parameter information; such information and its
1.109 +inspection
1.110 is discussed in <a href="parameters.html">"Request Parameters and
1.111 Uploads"</a>.</p>
1.112 -
1.113 -<h2>Paths To and Within an Application</h2>
1.114 -One thing to be aware of in the code of an application is which part of a
1.115 -path refers to the location of the application in a server environment and
1.116 -which refers to some resource within the application itself. Consider this
1.117 -path:<br />
1.118 -
1.119 -<pre>/folder/application/resource</pre>
1.120 -Let us say that the application was deployed in a Zope server instance inside
1.121 -<code>folder</code> and with the name <code>application</code>. We may then
1.122 -say that the path to the application is this:
1.123 -<pre>/folder/application</pre>
1.124 -Meanwhile, the path within the application is just this:
1.125 -<pre>/resource</pre>
1.126 -
1.127 -<div class="WebStack">
1.128 -<h3>WebStack API - Paths To Resources Within Applications</h3>
1.129 -
1.130 -<p>On transaction objects, the following methods exist to inspect paths to
1.131 -resources within applications.</p>
1.132 -<dl>
1.133 - <dt><code>get_path_info</code></dt>
1.134 - <dd>This gets the path of a resource within an application.</dd>
1.135 - <dt><code>get_virtual_path_info</code></dt>
1.136 - <dd>This gets the path of a resource within a part of an application -
1.137 - the application itself decides the scope of the path and can set the
1.138 - "virtual path info" using the <code>set_virtual_path_info</code>
1.139 - method.</dd>
1.140 -</dl>
1.141 -</div>
1.142 -
1.143 -<h2>Approaches to Path Interpretation</h2>
1.144 -
1.145 -<p>There are various differing approaches to the problem of interpreting
1.146 -paths to resources within Web applications, but these can mostly be divided
1.147 -into three categories:</p>
1.148 -
1.149 -<table border="1" cellspacing="0" cellpadding="5">
1.150 - <tbody>
1.151 - <tr>
1.152 - <th>Approach</th>
1.153 - <th>Examples</th>
1.154 - </tr>
1.155 - <tr>
1.156 - <td><a href="paths-filesystem.html">Path as filesystem</a></td>
1.157 - <td>WebDAV interface to a repository</td>
1.158 - </tr>
1.159 - <tr>
1.160 - <td><a href="paths-services.html">Path as resource or service
1.161 - identifier</a></td>
1.162 - <td>A Web shop with very simple paths, eg. <code>/products</code>,
1.163 - <code>/checkout</code>, <code>/orders</code></td>
1.164 - </tr>
1.165 - <tr>
1.166 - <td><a href="paths-opaque.html">Path as opaque reference</a></td>
1.167 - <td>An e-mail reader where the messages already have strange and
1.168 - unreadable message identifiers</td>
1.169 - </tr>
1.170 - </tbody>
1.171 -</table>
1.172 -
1.173 -<h2>Path Info Support in Server Environments</h2>
1.174 -
1.175 -<p>The following table summarises the support for paths within applications
1.176 -amongst the supported server environments or frameworks within WebStack:</p>
1.177 -
1.178 -<table border="1" cellspacing="0" cellpadding="5">
1.179 - <tbody>
1.180 - <tr>
1.181 - <th>Framework</th>
1.182 - <th>Behaviour/Level of Support</th>
1.183 - </tr>
1.184 - <tr>
1.185 - <td>BaseHTTPRequestHandler</td>
1.186 - <td>Same as path (correct)</td>
1.187 - </tr>
1.188 - <tr>
1.189 - <td>CGI</td>
1.190 - <td>Path beyond resource (correct)</td>
1.191 - </tr>
1.192 - <tr>
1.193 - <td>Java Servlet API</td>
1.194 - <td>Path beyond context (correct)</td>
1.195 - </tr>
1.196 - <tr>
1.197 - <td>mod_python</td>
1.198 - <td>Path beyond resource (correct)</td>
1.199 - </tr>
1.200 - <tr>
1.201 - <td>Twisted</td>
1.202 - <td>Same as path (correct)</td>
1.203 - </tr>
1.204 - <tr>
1.205 - <td>Webware</td>
1.206 - <td><= 0.8.1: Not supported (needs <code>ExtraPathInfo</code>
1.207 - support)<br />
1.208 - > 0.8.1: Path beyond context (correct)</td>
1.209 - </tr>
1.210 - <tr>
1.211 - <td>WSGI</td>
1.212 - <td>Path beyond resource (correct)</td>
1.213 - </tr>
1.214 - <tr>
1.215 - <td>Zope</td>
1.216 - <td>Path beyond resource (correct)</td>
1.217 - </tr>
1.218 - </tbody>
1.219 -</table>
1.220 +<h2>More About Paths</h2>
1.221 +<ul>
1.222 + <li><a href="path-info.html">Paths To and Within Applications</a></li>
1.223 + <li><a href="path-design.html">Path Design and Interpretation</a></li>
1.224 + <li><a href="path-info-support.html">Path Info Support in Server
1.225 +Environments</a></li>
1.226 +</ul>
1.227 </body>
1.228 </html>