1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"><head> 4 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Paths To and Within Applications</title> 5 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 6 <body><h1>Paths To and Within Applications</h1> 7 <p>One thing to be aware of, in the 8 code of an application, is which part 9 of 10 a 11 path refers to the location of the application in a server environment, 12 and 13 which refers to some resource within the application itself. Consider 14 this 15 path:</p> 16 <pre>/folder/application/resource/operation</pre><p>Let us say 17 that the application 18 was deployed in a Zope server 19 instance 20 inside 21 <code>folder</code> 22 and with the name <code>application</code>. 23 We may 24 then 25 say that the path to the application is this: 26 </p><pre>/folder/application</pre><p>Meanwhile, 27 the path <span style="font-style: italic;">within</span> 28 the 29 application is just this: 30 </p><pre>/resource/operation</pre><p>In WebStack, we 31 refer to this latter case - the path within 32 the 33 application - as the "path info".</p> 34 <div class="WebStack"><h3>WebStack API - Paths To 35 Resources Within Applications</h3> 36 <p>On transaction objects, the 37 following methods exist to inspect paths 38 to 39 resources within applications.</p> 40 <dl> <dt><code>get_path_info</code></dt> 41 <dd>This gets the path of a 42 resource within an application. The path should always contain a 43 leading <code>/</code> character at the very least.<br /> 44 An optional <code>encoding</code> parameter may be 45 used to assist the process of converting the path to a Unicode object - 46 see <a href="encodings.html">"Character Encodings"</a> 47 for more information.</dd> <dt><code>get_virtual_path_info</code></dt> 48 <dd>This gets the path of a 49 resource within a part of an application 50 - the application itself decides the scope of the path and can set the 51 "virtual path info" using the <code>set_virtual_path_info</code> 52 method. The path should either contain a leading <code>/</code> 53 character optionally followed by other characters, or an empty string.<br /> 54 An optional <code>encoding</code> parameter may be 55 used to assist the process of converting the path to a Unicode object - 56 see <a href="encodings.html">"Character Encodings"</a> 57 for more information.</dd><dt><code>get_processed_virtual_path_info</code></dt> 58 <dd>This gets the virtual path information which is considered to 59 have been processed or traversed, and consists of the part of the path 60 info which does not appear in the virtual path info. In other words, 61 when components at the start of the virtual path info are removed, such 62 components will appear at the end of the processed virtual path info.<br /> 63 An optional <code>encoding</code> parameter may be 64 used to assist the process of converting the path to a Unicode object - 65 see <a href="encodings.html">"Character Encodings"</a> 66 for more information.</dd> 67 </dl></div><h2>Choosing the Right Path Value</h2> 68 <p>Given that the path may change depending on 69 where an 70 application is deployed in a server environment, it may not be very 71 easy to use when determining which resources are being requested or 72 accessed within your application. Conversely, given that the "path 73 info" does not mention the full path to where the resources are, 74 it may be difficult to use that to provide references or links to those 75 resources. Here is a summary of how you might use the different path 76 values:</p> 77 <table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%"> <tbody> <tr> <th style="text-align: center;">Type of information</th> <th style="text-align: center;">Possible uses</th> </tr> 78 <tr> <td align="undefined" valign="undefined">Path</td> 79 <td align="undefined" valign="undefined">Building 80 links to 81 resources within an application.</td> </tr> <tr><td align="undefined" valign="undefined">Path without 82 path info</td><td align="undefined" valign="undefined">Finding 83 the location of the application in a server environment. (This is the 84 path with the "path info" subtracted from 85 the end.)</td></tr><tr> <td align="undefined" valign="undefined">Path info</td> <td align="undefined" valign="undefined">Determining 86 which 87 resources are being accessed within an application.</td> </tr> 88 <tr> <td align="undefined" valign="undefined">Virtual 89 path info</td> <td align="undefined" valign="undefined">This 90 is an 91 application-defined version of "path info" and is discussed below.</td> 92 </tr> </tbody></table><h2>Using the Virtual 93 Path</h2> 94 <p>Although WebStack sets the "path info" so that 95 applications 96 know which part of themselves are being accessed, you may 97 decide 98 that upon 99 processing the request, these different parts of your application 100 should be 101 presented with different path information. For example, in a 102 hierarchical 103 structure of resources, each resource might use the first part of the 104 "path info" as an input to some kind of processing, but then have the 105 need to remove the 106 part they used, passing on a modified path to the other resources. For 107 such approaches, the "virtual path info" may be used instead, since it 108 permits modification within an application.</p> 109 <p>So starting with a virtual path like this (which would be the 110 same 111 as the "path info")...</p> 112 <pre>/company/department/employee</pre><p>...a 113 resource might extract <code>company</code> from 114 the start 115 of the path as follows:</p> 116 <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><p>Then, 117 having processed the first non-empty part (remembering that 118 the first part will be an empty string)...</p> 119 <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><p>...it 120 will reconstruct the path, removing the processed part (but 121 remembering to preserve a leading <code>/</code> 122 character)...</p> 123 <pre> trans.set_virtual_path_info("/" + "/".join(parts[2:]))</pre><p>...and 124 hand over control to another resource which would do the same 125 thing with the first of the other path components (<code>department</code> 126 and <code>employee</code>), and so on.</p> 127 <p>The compelling thing about this strategy is the way that each 128 resource would only need to take the "virtual path info" into 129 consideration, and that each resource would believe that it is running 130 independently from any "parent" resource. Moreover, such resources 131 could be deployed independently and still operate in the same way 132 without being "hardcoded" into assuming that they always reside at a 133 particular level in a resource hierarchy.</p><div class="WebStack"> 134 <h3>WebStack API - Paths To 135 Resources Within Applications</h3> 136 <p>On transaction objects, the 137 following method exists to set virtual paths within applications.</p> 138 <dl><dt><code>set_virtual_path_info</code></dt><dd>This 139 sets the virtual path, affecting subsequent calls to the <code>get_virtual_path_info</code> 140 method. The path should either contain a leading <code>/</code> 141 character optionally followed by other characters, or an empty string.</dd></dl> 142 </div><h2>Summary</h2><p>The following illustration hopefully provides a more memorable way of representing the structure of paths:</p> 143 <table style="text-align: left; width: 80%;" align="center" border="1" cellpadding="5" cellspacing="0" width="80%"> 144 <tbody> 145 <tr> 146 <th colspan="6" rowspan="1">URL</th> 147 </tr> 148 <tr> 149 <th colspan="1" rowspan="4">Protocol, host, port</th> 150 <th colspan="5" rowspan="1">Path</th> 151 </tr> 152 <tr> 153 <th colspan="3" rowspan="1">Path without query</th> 154 <th rowspan="3"></th> 155 <th colspan="1" rowspan="3">Query</th> 156 </tr> 157 <tr> 158 <th colspan="1" rowspan="2">Path without path info</th> 159 <th colspan="2">Path info</th> 160 </tr> 161 <tr> 162 <th>Processed virtual path info</th> 163 <th>Virtual path info</th> 164 </tr> 165 <tr> 166 <td>http://www.python.org</td> 167 <td>/folder/application</td> 168 <td>/resource</td> 169 <td>/operation</td> 170 <td>?</td> 171 <td>a=1&b=2</td> 172 </tr> 173 </tbody> 174 </table> 175 </body></html>