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