1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/path-info.html Tue Apr 26 18:33:06 2005 +0000
1.3 @@ -0,0 +1,144 @@
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">
1.6 +<head>
1.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Paths To and Within Applications</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Paths To and
1.15 +Within Applications</h1>
1.16 +<p>One thing to be aware of in the
1.17 +code of an application is which part
1.18 +of
1.19 +a
1.20 +path refers to the location of the application in a server environment
1.21 +and
1.22 +which refers to some resource within the application itself. Consider
1.23 +this
1.24 +path:</p>
1.25 +<pre>/folder/application/resource</pre>
1.26 +<p>Let us say that the application
1.27 +was deployed in a Zope server
1.28 +instance
1.29 +inside
1.30 +<code>folder</code>
1.31 +and with the name <code>application</code>.
1.32 +We may
1.33 +then
1.34 +say that the path to the application is this:
1.35 +</p>
1.36 +<pre>/folder/application</pre>
1.37 +<p>Meanwhile, the path within the
1.38 +application is just this:
1.39 +</p>
1.40 +<pre>/resource</pre>
1.41 +<p>In WebStack, we refer to this latter case - the path within the
1.42 +application - as the "path info".</p>
1.43 +<div class="WebStack">
1.44 +<h3>WebStack API - Paths To
1.45 +Resources Within Applications</h3>
1.46 +<p>On transaction objects, the
1.47 +following methods exist to inspect paths
1.48 +to
1.49 +resources within applications.</p>
1.50 +<dl>
1.51 + <dt><code>get_path_info</code></dt>
1.52 + <dd>This gets the path of a
1.53 +resource within an application. The path should always contain a
1.54 +leading <code>/</code> character at the very least.</dd>
1.55 + <dt><code>get_virtual_path_info</code></dt>
1.56 + <dd>This gets the path of a
1.57 +resource within a part of an application
1.58 +- the application itself decides the scope of the path and can set the
1.59 +"virtual path info" using the <code>set_virtual_path_info</code>
1.60 +method. The path should always contain a leading <code>/</code>
1.61 +character at the very least.</dd>
1.62 +</dl>
1.63 +</div>
1.64 +<h2>Choosing the Right Path Value</h2>
1.65 +<p>Given that the path may change depending on where an
1.66 +application is deployed in a server environment, it may not be very
1.67 +easy to use when determining which resources are being requested or
1.68 +accessed within your application. Conversely, given that the "path
1.69 +info" does not mention the full path to where the resources are,
1.70 +it may be difficult to use that to provide references or links to those
1.71 +resources. Here is a summary of how you might use the different path
1.72 +values:</p>
1.73 +<table style="text-align: left; width: 80%;" align="center" border="1"
1.74 + cellpadding="5" cellspacing="0" width="80%">
1.75 + <tbody>
1.76 + <tr>
1.77 + <th style="text-align: center;">Type of information</th>
1.78 + <th style="text-align: center;">Possible uses</th>
1.79 + </tr>
1.80 + <tr>
1.81 + <td align="undefined" valign="undefined">Path</td>
1.82 + <td align="undefined" valign="undefined">Building links to
1.83 +resources within an application - subtract the "path info" from
1.84 +the end and you should get the location of the application.</td>
1.85 + </tr>
1.86 + <tr>
1.87 + <td align="undefined" valign="undefined">Path info</td>
1.88 + <td align="undefined" valign="undefined">Determining which
1.89 +resources are being accessed within an application.</td>
1.90 + </tr>
1.91 + <tr>
1.92 + <td align="undefined" valign="undefined">Virtual path info</td>
1.93 + <td align="undefined" valign="undefined">This is an
1.94 +application-defined version of "path info" and is discussed below.</td>
1.95 + </tr>
1.96 + </tbody>
1.97 +</table>
1.98 +<h2>Using the Virtual Path</h2>
1.99 +<p>Although WebStack sets the "path info" so that applications
1.100 +know which part of themselves are being accessed, you may decide
1.101 +that upon
1.102 +processing the request, these different parts of your application
1.103 +should be
1.104 +presented with different path information. For example, in a
1.105 +hierarchical
1.106 +structure of resources, each resource might use the first part of the
1.107 +"path info" as an input to some kind of processing, but then have the
1.108 +need to remove the
1.109 +part they used, passing on a modified path to the other resources. For
1.110 +such approaches, the "virtual path info" may be used instead, since it
1.111 +permits modification within an application.</p>
1.112 +<p>So starting with a virtual path like this (which would be the same
1.113 +as the "path info")...</p>
1.114 +<pre>/company/department/employee</pre>
1.115 +<p>...a resource might extract <code>company</code> from the start
1.116 +of the path as follows:</p>
1.117 +<pre> # Inside a respond method...<br /> path = trans.get_virtual_path_info() # get the virtual path<br /> parts = path.split("/") # split the path into components - the first will be empty</pre>
1.118 +<p>Then, having processed the first non-empty part (remembering that
1.119 +the first part will be an empty string)...</p>
1.120 +<pre> if len(parts) > 1: # check to see how deep we are in the path<br /> process_something(parts[1]) # process the first non-empty part</pre>
1.121 +<p>...it will reconstruct the path, removing the processed part (but
1.122 +remembering to preserve a leading <code>/</code> character)...</p>
1.123 +<pre> trans.set_virtual_path_info("/" + "/".join(parts[2:]))</pre>
1.124 +<p>...and hand over control to another resource which would do the same
1.125 +thing with the first of the other path components (<code>department</code>
1.126 +and <code>employee</code>), and so on.</p>
1.127 +<p>The compelling thing about this strategy is the way that each
1.128 +resource would only need to take the "virtual path info" into
1.129 +consideration, and that each resource would believe that it is running
1.130 +independently from any "parent" resource. Moreover, such resources
1.131 +could be deployed independently and still operate in the same way
1.132 +without being "hardcoded" into assuming that they always reside at a
1.133 +particular level in a resource hierarchy.</p>
1.134 +<div class="WebStack">
1.135 +<h3>WebStack API - Paths To
1.136 +Resources Within Applications</h3>
1.137 +<p>On transaction objects, the
1.138 +following method exists to set virtual paths within applications.</p>
1.139 +<dl>
1.140 + <dt><code>set_virtual_path_info</code></dt>
1.141 + <dd>This sets the virtual path, affecting subsequent calls to the <code>get_virtual_path_info</code>
1.142 +method. The path should always contain a leading <code>/</code>
1.143 +character at the very least.</dd>
1.144 +</dl>
1.145 +</div>
1.146 +</body>
1.147 +</html>