WebStack

Annotated docs/path-info.html

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