paulb@515 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@515 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"><head><meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
paulb@515 | 3 | |
paulb@515 | 4 | <title>DirectoryResource - Serving Static Content</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@515 | 5 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
paulb@515 | 6 | <body> |
paulb@515 | 7 | <h1>DirectoryResource - Serving Static Content</h1> |
paulb@515 | 8 | <p>The <code>DirectoryResource</code> class provides a means to |
paulb@515 | 9 | serve static files from within a particular directory in the |
paulb@515 | 10 | filesystem. By inspecting the remainder of the path information |
paulb@515 | 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 |
paulb@515 | 12 | stylesheets, script files and images employed by Web pages which may |
paulb@515 | 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> |
paulb@515 | 14 | document), it should be possible to retain control of the serving of |
paulb@515 | 15 | static content within a WebStack application. Note, however, that the |
paulb@515 | 16 | performance of a system can be improved if the job of serving static |
paulb@515 | 17 | content is delegated to a specialised Web server solution - one might, |
paulb@515 | 18 | for example, set up an Apache Web server to serve things like |
paulb@515 | 19 | stylesheets, script files and images, and then link to the locations of |
paulb@515 | 20 | such things in the Web pages generated by the WebStack application.</p><div class="WebStack"><h3>WebStack API - The DirectoryResource Class</h3> |
paulb@515 | 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 |
paulb@515 | 22 | no file exists in the specified directory with the identified |
paulb@515 | 23 | name, a "file not found" response code is set by the resource and a |
paulb@515 | 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 |
paulb@515 | 25 | that a file exists in the specified directory, it is usually critical |
paulb@515 | 26 | that the file is served along with special file type information so |
paulb@515 | 27 | that a user's Web browser may understand the nature of the file's |
paulb@515 | 28 | content. For example, a file containing a Web page must be served with |
paulb@515 | 29 | a file type indicating that the contents of the file are HTML (or some |
paulb@515 | 30 | variant thereof). Instances of <code>DirectoryResource</code> employ |
paulb@515 | 31 | a special registry mapping filename extensions to file types in order |
paulb@564 | 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> |
paulb@564 | 33 | character is omitted from the filename extension. Where it is tedious |
paulb@564 | 34 | to create content type objects and where the same character encoding |
paulb@564 | 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> |
paulb@564 | 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 |
paulb@515 | 37 | specified, this parameter forces a particular interpretation of "URL |
paulb@515 | 38 | encoded" character values in the path. Otherwise, the default encoding |
paulb@564 | 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> |