1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/paths.html Fri Apr 08 22:33:56 2005 +0000
1.3 @@ -0,0 +1,120 @@
1.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.5 +<html>
1.6 +<head>
1.7 + <meta http-equiv="Content-Type" content="text/html">
1.8 + <title>URLs and Paths</title>
1.9 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/">
1.10 + <link href="styles.css" rel="stylesheet" type="text/css">
1.11 +</head>
1.12 +
1.13 +<body>
1.14 +<h1>URLs and Paths</h1>
1.15 +
1.16 +<p>The URL at which your application shall appear is arguably the first part
1.17 +of the application's user interface that any user will see. In this context,
1.18 +a user can be any of the following things:</p>
1.19 +<ul>
1.20 + <li>A real person entering the URL into a browser's address bar.</li>
1.21 + <li>A real person linking to your application by writing the URL in a
1.22 + separate Web page.</li>
1.23 + <li>A program which has the URL defined within it and which may manipulate
1.24 + the URL to perform certain kinds of operations.</li>
1.25 +</ul>
1.26 +
1.27 +<h2>Interpreting Path Information</h2>
1.28 +
1.29 +<p>What the URL is supposed to do is to say where (on the Internet or on an
1.30 +intranet) your application resides and which resource or service is being
1.31 +accessed, and these look like this:</p>
1.32 +<pre>http://www.boddie.org.uk/python/WebStack.html</pre>
1.33 +
1.34 +<p>With WebStack, we also talk about a "path" as being just the part of the
1.35 +URL which refers to the resource or service, ignoring the actual Internet
1.36 +address, and so these look like this:</p>
1.37 +<pre>/python/WebStack.html</pre>
1.38 +
1.39 +<p>When writing a Web application, most of the time you just need to
1.40 +concentrate on the path because the address doesn't usually tell you anything
1.41 +you don't already know. What you need to do is to interpret the path
1.42 +specified in the request in order to work out which resource or service the
1.43 +request is destined for.<br>
1.44 +</p>
1.45 +
1.46 +<div class="WebStack">
1.47 +<h3>WebStack API - Path Methods in Transaction Objects</h3>
1.48 +
1.49 +<p>WebStack provides the following transaction methods for inspecting path
1.50 +information:</p>
1.51 +<dl>
1.52 + <dt><code>get_path</code></dt>
1.53 + <dd>This gets the entire path of a resource including parameter
1.54 + information - see <a href="parameters.html">"Request Parameters and
1.55 + Uploads"</a>.</dd>
1.56 + <dt><code>get_path_without_query</code></dt>
1.57 + <dd>This gets the entire path of a resource but without any parameter
1.58 + information.</dd>
1.59 +</dl>
1.60 +</div>
1.61 +
1.62 +<h2>Paths To and Within an Application</h2>
1.63 +One thing to be aware of in the code of an application is which part of a
1.64 +path refers to the location of the application in a server environment and
1.65 +which refers to some resource within the application itself. Consider this
1.66 +path:<br>
1.67 +
1.68 +<pre>/folder/application/resource</pre>
1.69 +Let us say that the application was deployed in a Zope server instance inside
1.70 +<code>folder</code> and with the name <code>application</code>. We may then
1.71 +say that the path to the application is this:
1.72 +<pre>/folder/application</pre>
1.73 +Meanwhile, the path within the application is just this:
1.74 +<pre>/resource</pre>
1.75 +
1.76 +<div class="WebStack">
1.77 +<h3>WebStack API - Paths To Resources Within Applications</h3>
1.78 +
1.79 +<p>On transaction objects, the following methods exist to inspect paths to
1.80 +resources within applications.</p>
1.81 +<dl>
1.82 + <dt><code>get_path_info</code></dt>
1.83 + <dd>This gets the path of a resource within an application.</dd>
1.84 + <dt><code>get_virtual_path_info</code></dt>
1.85 + <dd>This gets the path of a resource within a part of an application -
1.86 + the application itself decides the scope of the path and can set the
1.87 + "virtual path info" using the <code>set_virtual_path_info</code>
1.88 + method.</dd>
1.89 +</dl>
1.90 +</div>
1.91 +
1.92 +<h2>Approaches to Path Interpretation<br>
1.93 +</h2>
1.94 +
1.95 +<p>There are various differing approaches to the problem of interpreting
1.96 +paths to resources within Web applications, but these can mostly be divided
1.97 +into three categories:</p>
1.98 +
1.99 +<table border="1" cellspacing="0" cellpadding="5">
1.100 + <tbody>
1.101 + <tr>
1.102 + <th>Approach</th>
1.103 + <th>Examples</th>
1.104 + </tr>
1.105 + <tr>
1.106 + <td><a href="paths-filesystem.html">Path as filesystem</a></td>
1.107 + <td>WebDAV interface to a repository</td>
1.108 + </tr>
1.109 + <tr>
1.110 + <td><a href="paths-services.html">Path as resource or service
1.111 + identifier</a></td>
1.112 + <td>A Web shop with very simple paths, eg. <code>/products</code>,
1.113 + <code>/checkout</code>, <code>/orders</code></td>
1.114 + </tr>
1.115 + <tr>
1.116 + <td><a href="paths-opaque.html">Path as opaque reference</a></td>
1.117 + <td>An e-mail reader where the messages already have strange and
1.118 + unreadable message identifiers</td>
1.119 + </tr>
1.120 + </tbody>
1.121 +</table>
1.122 +</body>
1.123 +</html>