WebStack

docs/directory-resource.html

732:7f1f02b485f8
2007-11-12 paulb [project @ 2007-11-12 00:50:03 by paulb] Introduced base classes for common authentication activities. Made cookie usage "safe" for usernames containing ":" characters. Added support for OpenID signatures.
     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><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     4   <title>DirectoryResource - Serving Static Content</title>     5   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     6 <body>     7 <h1>DirectoryResource - Serving Static Content</h1>     8 <p>The <code>DirectoryResource</code> class provides a means to     9 serve static files from within a particular directory in the    10 filesystem. By inspecting the remainder of the path information    11 supplied in an incoming request, instances of  <code>DirectoryResource</code> may identify files and serve their contents as a response to such a request.</p><p>There are various situations where providing static content is virtually essential:</p><ul><li>Providing    12 stylesheets, script files and images employed by Web pages which may    13 themselves have been produced by WebStack resources.</li><li>Providing static documents for Web pages which are not "dynamic".</li></ul><p>By instantiating  <code>DirectoryResource</code> classes and deploying them in conjunction with  <code>MapResource</code> objects (see the <a href="resource-map.html">"ResourceMap - Simple Mappings from Names to Resources"</a>    14 document), it should be possible to retain control of the serving of    15 static content within a WebStack application. Note, however, that the    16 performance of a system can be improved if the job of serving static    17 content is delegated to a specialised Web server solution - one might,    18 for example, set up an Apache Web server to serve things like    19 stylesheets, script files and images, and then link to the locations of    20 such things in the Web pages generated by the WebStack application.</p><div class="WebStack"><h3>WebStack API - The DirectoryResource Class</h3>    21 <p>Given a directory from which files shall be  served,  <code>DirectoryResource</code> uses a simple method to identify files to serve. First, it examines the <a href="path-info.html">virtual "path info"</a> and takes the first component of that information. For example, consider the following path information:</p><pre>/styles.css</pre><p>Here, <code>DirectoryResource</code>  identifies the file to be served as having the name  <code>styles.css</code>. Note that any trailing path information would be ignored; for example:</p><pre>/styles/abc</pre><p>Here, the file to be served would be identified as having the name  <code>styles</code>.</p><h4>Handling Missing Files</h4><p>Where    22 no file exists  in the specified directory with the identified    23 name, a "file not found" response code is set by the resource and a    24 message is emitted. To modify the simple behaviour of <code>DirectoryResource</code> in this regard, it is recommended that a subclass of <code>DirectoryResource</code> is defined with its own implementation of the  <code>not_found</code> method.</p><h4>Types of Served Files</h4><p>Given    25 that a file exists in the specified directory, it is usually critical    26 that the file is served along with special file type information so    27 that a user's Web browser may understand the nature of the file's    28 content. For example, a file containing a Web page must be served with    29 a file type indicating that the contents of the file are HTML (or some    30 variant thereof). Instances of  <code>DirectoryResource</code> employ    31 a special registry mapping filename extensions to file types in order    32 to automate the process of deciding what type a file might be.</p><p>Using the <code>content_types</code> parameter (see below), one might choose to serve all files whose names have the  <code>.html</code> extension with the HTML file (or content) type. This would be expressed with the following dictionary:</p><pre>{"html" : WebStack.Generic.ContentType("text/html", "utf-8")}</pre><p>Note that the  <code>.</code>    33 character is omitted from the filename extension. Where it is tedious    34 to create content type objects and where the same character encoding    35 applies for all types of files, it is possible to use the  <code>media_types</code> and  <code>default_encoding</code> parameters instead.<br /></p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Static.DirectoryResource-class.html">API documentation</a> for the <code>DirectoryResource</code> class provides more information on the usage of the class.</p><h4>Initialisation</h4><p>The <span style="font-family: monospace;">Directory</span><code>Resource</code> class (found in the  <code>WebStack.Resources.Static</code> module) accepts the following parameters  when being initialised:</p>    36 <dl><dt><code>directory</code></dt><dd>The directory from which static files shall be served.</dd><dt><code>media_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to media types.</dd><dt><code>unrecognised_media_type</code></dt><dd>An optional parameter setting the media type for files whose extensions do not map to any media type according to the  <code>media_types</code> parameter.</dd><dt><code>content_types</code></dt><dd>A dictionary or dictionary-like object mapping filename extensions to content type objects (such as  <code>WebStack.Generic.ContentType</code>).</dd><dt><code>unrecognised_content_type</code></dt><dd>An optional parameter setting the content type for files whose extensions do not map to any content type according to the <code>content_types</code> parameter.</dd><dt><code>default_encoding</code></dt><dd>An optional parameter setting the character encoding for all media types defined in the <code>media_types</code>  and <code>unrecognised_media_type</code>  parameters. If not specified, no character encoding will be stated for content associated with such media types.</dd><dt><code>urlencoding</code></dt><dd>When    37 specified, this parameter forces a particular interpretation of "URL    38 encoded" character values in the path. Otherwise, the default encoding    39 is employed to interpret such values. (See <a href="paths.html">"URLs and Paths"</a> for an explanation of "URL encoded" values.)</dd></dl></div><h2>Combining MapResource with DirectoryResource</h2><p>One might combine  <code>MapResource</code> with  <code>DirectoryResource</code> to provide stylesheet and script file directories for an application as follows:</p><pre>from WebStack.Resources.ResourceMap import MapResource<br />from WebStack.Resources.Static import DirectoryResource<br /><br /># This is where the application's resources would be obtained.<br /><br />app_resource = ...<br /><br /># Here is where we combine MapResource and DirectoryResource.<br /># Note that one would not necessarily hard-code directory paths into the application.<br /><br />top_resource = MapResource({<br />    "styles" : DirectoryResource("/usr/share/apps/MyApp/styles", media_types={"css" : "text/css"}),<br />    "scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", media_types={"js" : "text/javascript"}),<br />    "" : app_resource<br />    })</pre><p>In the above example, any file in  the  <code>styles</code> directory whose name ends with  <code>.css</code> is served as  <code>text/css</code>. Similarly, any file in the  <code>scripts</code> directory whose name ends with  <code>.js</code>  is served as  <code>text/javascript</code>.</p></body></html>