WebStack

docs/path-info.html

396:370deefd28f4
2005-07-16 paulb [project @ 2005-07-16 18:37:44 by paulb] Added directory redirects to the ResourceMap.MapResource.
     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">     3 <head>     4   <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     5   <title>Paths To and Within Applications</title>     6   <meta name="generator"     7  content="amaya 8.1a, see http://www.w3.org/Amaya/" />     8   <link href="styles.css" rel="stylesheet" type="text/css" />     9 </head>    10 <body>    11 <h1>Paths To and    12 Within&nbsp;Applications</h1>    13 <p>One thing to be aware of in the    14 code of an application is which part    15 of    16 a    17 path refers to the location of the application in a server environment    18 and    19 which refers to some resource within the application itself. Consider    20 this    21 path:</p>    22 <pre>/folder/application/resource</pre>    23 <p>Let us say that the application    24 was deployed in a Zope server    25 instance    26 inside    27 <code>folder</code>    28 and with the name <code>application</code>.    29 We may    30 then    31 say that the path to the application is this:    32 </p>    33 <pre>/folder/application</pre>    34 <p>Meanwhile, the path within the    35 application is just this:    36 </p>    37 <pre>/resource</pre>    38 <p>In WebStack, we refer to this latter case - the path within the    39 application -&nbsp;as the "path info".</p>    40 <div class="WebStack">    41 <h3>WebStack API - Paths To    42 Resources Within Applications</h3>    43 <p>On transaction objects, the    44 following methods exist to inspect paths    45 to    46 resources within applications.</p>    47 <dl>    48   <dt><code>get_path_info</code></dt>    49   <dd>This gets the path of a    50 resource within an application. The path should always contain a    51 leading&nbsp;<code>/</code> character at the very least.</dd>    52   <dt><code>get_virtual_path_info</code></dt>    53   <dd>This gets the path of a    54 resource within a part of an application    55 - the application itself decides the scope of the path and can set the    56 "virtual path info" using the <code>set_virtual_path_info</code>    57 method. The path should always contain a leading&nbsp;<code>/</code>    58 character at the very least.</dd>    59 </dl>    60 </div>    61 <h2>Choosing the Right Path Value</h2>    62 <p>Given that the&nbsp;path&nbsp;may change depending on where an    63 application is deployed in a server environment, it may not be very    64 easy to use when determining which resources are being requested or    65 accessed within your application. Conversely, given that the "path    66 info" does not mention the full path to where the resources are,    67 it may be difficult to use that to provide references or links to those    68 resources. Here is a summary of how you might use the different path    69 values:</p>    70 <table style="text-align: left; width: 80%;" align="center" border="1"    71  cellpadding="5" cellspacing="0" width="80%">    72   <tbody>    73     <tr>    74       <th style="text-align: center;">Type of information</th>    75       <th style="text-align: center;">Possible uses</th>    76     </tr>    77     <tr>    78       <td align="undefined" valign="undefined">Path</td>    79       <td align="undefined" valign="undefined">Building links to    80 resources within an application - subtract the "path info" from    81 the end and you should get the location of the application.</td>    82     </tr>    83     <tr>    84       <td align="undefined" valign="undefined">Path info</td>    85       <td align="undefined" valign="undefined">Determining which    86 resources are being accessed within an application.</td>    87     </tr>    88     <tr>    89       <td align="undefined" valign="undefined">Virtual path info</td>    90       <td align="undefined" valign="undefined">This is an    91 application-defined version of "path info" and is discussed below.</td>    92     </tr>    93   </tbody>    94 </table>    95 <h2>Using the Virtual Path</h2>    96 <p>Although WebStack&nbsp;sets the "path info" so that applications    97 know which part of themselves are being accessed,&nbsp;you may 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 same   110 as the "path info")...</p>   111 <pre>/company/department/employee</pre>   112 <p>...a resource might extract&nbsp;<code>company</code> from the start   113 of the path as follows:</p>   114 <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>   115 <p>Then, having processed the first non-empty part (remembering that   116 the first part will be an empty string)...</p>   117 <pre>        if len(parts) &gt; 1:                      # check to see how deep we are in the path<br />            process_something(parts[1])         # process the first non-empty part</pre>   118 <p>...it will reconstruct the path, removing the processed part (but   119 remembering to preserve a leading&nbsp;<code>/</code> character)...</p>   120 <pre>            trans.set_virtual_path_info("/" + "/".join(parts[2:]))</pre>   121 <p>...and hand over control to another resource which would do the same   122 thing with the first of the other path components (<code>department</code>   123 and&nbsp;<code>employee</code>), and so on.</p>   124 <p>The compelling thing about this strategy is the way that each   125 resource would only need to take the "virtual path info" into   126 consideration, and that each resource would believe that it is running   127 independently from any "parent" resource. Moreover, such resources   128 could be deployed independently and still operate in the same way   129 without being "hardcoded" into assuming that they always reside at a   130 particular level in a resource hierarchy.</p>   131 <div class="WebStack">   132 <h3>WebStack API - Paths To   133 Resources Within Applications</h3>   134 <p>On transaction objects, the   135 following method exists to set virtual paths within applications.</p>   136 <dl>   137   <dt><code>set_virtual_path_info</code></dt>   138   <dd>This sets the virtual path, affecting subsequent calls to the <code>get_virtual_path_info</code>   139 method. The path should always contain a leading&nbsp;<code>/</code>   140 character at the very least.</dd>   141 </dl>   142 </div>   143 </body>   144 </html>