Added ZCML directive to serve up static files from a directory.

4 files changed, 62 insertions, 49 deletions

diff --git a/docs/narr/MyProject/myproject/configure.zcml b/docs/narr/MyProject/myproject/configure.zcml
index 89bf74525..aa98296c5 100644
--- a/docs/narr/MyProject/myproject/configure.zcml
+++ b/docs/narr/MyProject/myproject/configure.zcml
@@ -8,10 +8,9 @@
      view=".views.my_view"
      />
 
-  <view
-     for=".models.MyModel"
-     view=".views.static_view"
+  <static
      name="static"
+     path="templates/static"
      />
 
 </configure>
diff --git a/docs/narr/MyProject/myproject/views.py b/docs/narr/MyProject/myproject/views.py
index d4de33b6d..486019bd7 100644
--- a/docs/narr/MyProject/myproject/views.py
+++ b/docs/narr/MyProject/myproject/views.py
@@ -1,7 +1,4 @@
 from repoze.bfg.chameleon_zpt import render_template_to_response
-from repoze.bfg.view import static
-
-static_view = static('templates/static')
 
 def my_view(context, request):
     return render_template_to_response('templates/mytemplate.pt',
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index e2fc69435..131a8ff48 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -565,10 +565,8 @@ registry`. It looks like so:
    ``.views.my_view`` could be replaced with
    ``myproject.views.my_view``.
 
-#. Lines 11-15 register a view named ``static``.  This view
-   declaration points at the ``static_view``, which is a view
-   implementation that serves static files from the filesystem for the
-   default application.
+#. Lines 11-14 register a static view, which will register a view
+   which serves up the files from the static directory in the package.
 
 ``views.py``
 ~~~~~~~~~~~~
@@ -582,13 +580,7 @@ in the model, and the response given back to a browser.
 
 #. Lines 1-2 import required functions.
 
-#. Line 4 sets up a ``static_view`` which will be consulted when
-   visitors visit ``/static/<something>``.  This view will serve up
-   CSS and images in our default application.  This view is registered
-   in ``configure.zcml`` as the ``static`` view name for the class
-   ``MyModel`` (the root).
-
-#. Lines 6-9 provide the ``my_view`` that was registered as the view.
+#. Lines 3-6 provide the ``my_view`` that was registered as the view.
    ``configure.zcml`` said that the default URL for instances that are
    of the class ``MyModel`` should run this ``my_view`` function.
 
@@ -622,11 +614,6 @@ in the model, and the response given back to a browser.
   retrieve the template object without rendering it at all, for
   additional control.
 
-.. note::
-
-   For more information about the ``static`` view helper function see
-   :ref:`static_resources_section`.
-
 .. _modelspy_project_section:
 
 ``models.py``
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index b5db0ca63..795fa61a6 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -630,18 +630,66 @@ includes other response types for Unauthorized, etc.
 
 .. _static_resources_section:
 
+Serving Static Resources Using a ZCML directive
+-----------------------------------------------
+
+Using the ``static`` ZCML directive is the preferred way to serve
+static resources (like JavaScript and CSS files) within
+:mod:`repoze.bfg`. This directive makes static files available at a
+name relative to the application root URL, e.g. ``/static``.
+
+You can either use a package-relative path to a directory or a path
+relative to the ZCML file (or an absolute path).
+
+.. code-block:: xml
+   :linenos:
+
+   <static
+      name="static"
+      path="some_package:static"
+      />
+
+   <static
+      name="static"
+      path="static"
+      />
+
+   <static
+      name="static"
+      path="/var/www/static"
+      />
+
+Now put your static files (JS, etc) on your filesystem in the
+directory represented as ``/path/to/static/dir``.  After this is done,
+you should be able to view the static files in this directory via a
+browser at URLs prefixed with ``/static/``, for instance
+``/static/foo.js`` will return the file
+``/path/to/static/dir/foo.js``.  The static directory may contain
+subdirectories recursively, and any subdirectories may hold files;
+these will be resolved by the static view as you would expect.
+
+.. note:: To ensure that model objects contained in the root don't
+   "shadow" your static view (model objects take precedence during
+   traversal), or to ensure that your root object's ``__getitem__`` is
+   never called when a static resource is requested, you can refer to
+   your static resources as registered above in URLs as,
+   e.g. ``/@@static/foo.js``.  This is completely equivalent to
+   ``/static/foo.js``.  See :ref:`traversal_chapter` for information
+   about "goggles" (``@@``).
+
 Serving Static Resources Using a View
 -------------------------------------
 
-Using the :mod:`repoze.bfg.view` ``static`` helper class is the
-preferred way to serve static resources (like JavaScript and CSS
-files) within :mod:`repoze.bfg`.  This class creates a callable that
-is capable acting as a :mod:`repoze.bfg` view which serves static
-resources from a directory.  For instance, to serve files within a
-directory located on your filesystem at ``/path/to/static/dir``
-mounted at the URL path ``/static`` in your application, create an
-instance of :mod:`repoze.bfg.view` 's ``static`` class inside a
-``static.py`` file in your application root as below.
+For more flexibility, static resources can be served by a view which
+you register manually. The :mod:`repoze.bfg.view` ``static`` helper
+class is the preferred way to go about this. This class creates a
+callable that is capable acting as a :mod:`repoze.bfg` view which
+serves static resources from a directory.  For instance, to serve
+files within a directory located on your filesystem at
+``/path/to/static/dir`` mounted at the URL path ``/static`` in your
+application, create an instance of :mod:`repoze.bfg.view` 's
+``static`` class inside a ``static.py`` file in your application root
+as below.
 
 .. code-block:: python
    :linenos:
@@ -671,24 +719,6 @@ In this case, ``.models.Root`` refers to the class of which your
    for ``/anything/static/foo.js`` too, as long as ``anything`` itself
    is resolveable.
 
-Now put your static files (JS, etc) on your filesystem in the
-directory represented as ``/path/to/static/dir``.  After this is done,
-you should be able to view the static files in this directory via a
-browser at URLs prefixed with ``/static/``, for instance
-``/static/foo.js`` will return the file
-``/path/to/static/dir/foo.js``.  The static directory may contain
-subdirectories recursively, and any subdirectories may hold files;
-these will be resolved by the static view as you would expect.
-
-.. note:: To ensure that model objects contained in the root don't
-   "shadow" your static view (model objects take precedence during
-   traversal), or to ensure that your root object's ``__getitem__`` is
-   never called when a static resource is requested, you can refer to
-   your static resources as registered above in URLs as,
-   e.g. ``/@@static/foo.js``.  This is completely equivalent to
-   ``/static/foo.js``.  See :ref:`traversal_chapter` for information
-   about "goggles" (``@@``).
-
 Using Views to Handle Form Submissions (Unicode and Character Set Issues)
 -------------------------------------------------------------------------