WebStack

Annotated docs/path-info.html

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