1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/directory-resource.html Sun Nov 20 02:37:06 2005 +0000
1.3 @@ -0,0 +1,39 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.6 +
1.7 + <title>DirectoryResource - Serving Static Content</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.8 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.9 +<body>
1.10 +<h1>DirectoryResource - Serving Static Content</h1>
1.11 +<p>The <code>DirectoryResource</code> class provides a means to
1.12 +serve static files from within a particular directory in the
1.13 +filesystem. By inspecting the remainder of the path information
1.14 +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
1.15 +stylesheets, script files and images employed by Web pages which may
1.16 +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>
1.17 +document), it should be possible to retain control of the serving of
1.18 +static content within a WebStack application. Note, however, that the
1.19 +performance of a system can be improved if the job of serving static
1.20 +content is delegated to a specialised Web server solution - one might,
1.21 +for example, set up an Apache Web server to serve things like
1.22 +stylesheets, script files and images, and then link to the locations of
1.23 +such things in the Web pages generated by the WebStack application.</p><div class="WebStack"><h3>WebStack API - The DirectoryResource Class</h3>
1.24 +<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
1.25 +no file exists in the specified directory with the identified
1.26 +name, a "file not found" response code is set by the resource and a
1.27 +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
1.28 +that a file exists in the specified directory, it is usually critical
1.29 +that the file is served along with special file type information so
1.30 +that a user's Web browser may understand the nature of the file's
1.31 +content. For example, a file containing a Web page must be served with
1.32 +a file type indicating that the contents of the file are HTML (or some
1.33 +variant thereof). Instances of <code>DirectoryResource</code> employ
1.34 +a special registry mapping filename extensions to file types in order
1.35 +to automate the process of deciding what type a file might be.</p><p>Using the <code>media_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" : "text/html"}</pre><p>Note that the <code>.</code>
1.36 +character is omitted from the filename extension and that the file type
1.37 +(or more correctly, the media type) does not include character set
1.38 +information.<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>
1.39 +<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 MIME types.</dd><dt><code>unrecognised_media_type</code></dt><dd>An optional parameter setting the MIME type for files whose extensions do not map to any MIME type according to the <code>media_types</code> parameter.</dd><dt><code>urlencoding</code></dt><dd>When
1.40 +specified, this parameter forces a particular interpretation of "URL
1.41 +encoded" character values in the path. Otherwise, the default encoding
1.42 +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", {"css" : "text/css"}),<br /> "scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", {"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>
1.43 \ No newline at end of file