From fec0f0614c69dc7382fba367f8269479e2682058 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 18:47:29 -0400 Subject: convert narrative docs to Pyramid --- docs/narr/static.rst | 72 ++++++++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 39 deletions(-) (limited to 'docs/narr/static.rst') diff --git a/docs/narr/static.rst b/docs/narr/static.rst index b2d481ba5..02ee68eb6 100644 --- a/docs/narr/static.rst +++ b/docs/narr/static.rst @@ -1,9 +1,9 @@ Static Resources ================ -:mod:`repoze.bfg` makes it possible to serve up "static" (non-dynamic) +:mod:`pyramid` makes it possible to serve up "static" (non-dynamic) resources from a directory on a filesystem. This chapter describes -how to configure :mod:`repoze.bfg` to do so. +how to configure :mod:`pyramid` to do so. .. index:: triple: view; zcml; static resource @@ -15,8 +15,8 @@ Serving Static Resources Using a ZCML Directive ----------------------------------------------- Use of the ``static`` ZCML directive or the -:meth:`repoze.bfg.configuration.configurator.add_static_view` method -is the preferred way to instruct :mod:`repoze.bfg` to serve static +:meth:`pyramid.configuration.configurator.add_static_view` method +is the preferred way to instruct :mod:`pyramid` to serve static resources such as JavaScript and CSS files. This mechanism makes static files available at a name relative to the application root URL, e.g. ``/static``. @@ -30,7 +30,7 @@ package will resolve to a package-qualified resource such as Here's an example of a ``static`` ZCML directive that will serve files up under the ``/static`` URL from the ``/var/www/static`` directory of -the computer which runs the :mod:`repoze.bfg` application using an +the computer which runs the :mod:`pyramid` application using an absolute path. .. code-block:: xml @@ -67,9 +67,6 @@ package-relative path. path="static" /> -.. note:: The :ref:`static_directive` ZCML directive is new in - :mod:`repoze.bfg` 1.1. - Whether you use for ``path`` a fully qualified resource specification, an absolute path, or a package-relative path, When you place your static files on the filesystem in the directory represented as the @@ -90,20 +87,20 @@ shown usage of the ``name`` argument as a view name. When ``name`` is a *URL* (or any string with a slash (``/``) in it), static resources can be served from an external webserver. In this mode, the ``name`` is used as the URL prefix when generating a URL using -:func:`repoze.bfg.url.static_url`. +:func:`pyramid.url.static_url`. .. note:: - Using :func:`repoze.bfg.url.static_url` in conjunction with a - :meth:`repoze.bfg.configuration.Configurator.add_static_view` makes + Using :func:`pyramid.url.static_url` in conjunction with a + :meth:`pyramid.configuration.Configurator.add_static_view` makes it possible to put static media on a separate webserver during production (if the ``name`` argument to - :meth:`repoze.bfg.configuration.Configurator.add_static_view` is a + :meth:`pyramid.configuration.Configurator.add_static_view` is a URL), while keeping static media package-internal and served by the development webserver during development (if the ``name`` argument - to :meth:`repoze.bfg.configuration.Configurator.add_static_view` is + to :meth:`pyramid.configuration.Configurator.add_static_view` is a view name). To create such a circumstance, we suggest using the - :func:`repoze.bfg.settings.get_settings` API in conjunction with a + :func:`pyramid.settings.get_settings` API in conjunction with a setting in the application ``.ini`` file named ``media_location``. Then set the value of ``media_location`` to either a view name or a URL depending on whether the application is being run in @@ -125,16 +122,16 @@ argument which is ``http://example.com/images``: Because the ``static`` ZCML directive is provided with a ``name`` argument that is the URL prefix ``http://example.com/images``, -subsequent calls to :func:`repoze.bfg.url.static_url` with paths that +subsequent calls to :func:`pyramid.url.static_url` with paths that start with the ``path`` argument passed to -:meth:`repoze.bfg.configuration.Configurator.add_static_view` will +:meth:`pyramid.configuration.Configurator.add_static_view` will generate a URL something like ``http://example.com/logo.png``. The external webserver listening on ``example.com`` must be itself configured to respond properly to such a request. The -:func:`repoze.bfg.url.static_url` API is discussed in more detail +:func:`pyramid.url.static_url` API is discussed in more detail later in this chapter. -The :meth:`repoze.bfg.configuration.Configurator.add_static_view` +The :meth:`pyramid.configuration.Configurator.add_static_view` method offers an imperative equivalent to the ``static`` ZCML directive. Use of the ``add_static_view`` imperative configuration method is completely equivalent to using ZCML for the same purpose. @@ -150,15 +147,12 @@ Generating Static Resource URLs When a :ref:`static_directive` ZCML directive or a call to the ``add_static_view`` method of a -:class:`repoze.bfg.configuration.Configurator` is used to register a +:class:`pyramid.configuration.Configurator` is used to register a static resource directory, a special helper API named -:func:`repoze.bfg.static_url` can be used to generate the appropriate +:func:`pyramid.static_url` can be used to generate the appropriate URL for a package resource that lives in one of the directories named by the static registration ``path`` attribute. -.. note:: The :func:`repoze.bfg.url.static_url` API is new in - :mod:`repoze.bfg` 1.1. - For example, let's assume you create a set of ``static`` declarations in ZCML like so: @@ -183,7 +177,7 @@ visits a URL which begins with ``/static1``, and the resources in the begins with ``/static2``. You needn't generate the URLs to static resources "by hand" in such a -configuration. Instead, use the :func:`repoze.bfg.url.static_url` API +configuration. Instead, use the :func:`pyramid.url.static_url` API to generate them for you. For example, let's imagine that the following code lives in a module that shares the same directory as the above ZCML file: @@ -191,8 +185,8 @@ above ZCML file: .. code-block:: python :linenos: - from repoze.bfg.url import static_url - from repoze.bfg.chameleon_zpt import render_template_to_response + from pyramid.url import static_url + from pyramid.chameleon_zpt import render_template_to_response def my_view(request): css_url = static_url('resources/1/foo.css', request) @@ -206,17 +200,17 @@ If the request "application URL" of the running system is ``http://example.com/static1/foo.css``. The ``js_url`` generated above would be ``http://example.com/static2/foo.js``. -One benefit of using the :func:`repoze.bfg.url.static_url` function +One benefit of using the :func:`pyramid.url.static_url` function rather than constructing static URLs "by hand" is that if you need to change the ``name`` of a static URL declaration in ZCML, the generated URLs will continue to resolve properly after the rename. -URLs may also be generated by :func:`repoze.bfg.url.static_url` to -static resources that live *outside* the :mod:`repoze.bfg` +URLs may also be generated by :func:`pyramid.url.static_url` to +static resources that live *outside* the :mod:`pyramid` application. This will happen when the ``name`` argument provided to the ``static`` ZCML directive or the -:meth:`repoze.bfg.configuration.Configurator.add_static_view` API -associated with the path fed to :func:`repoze.bfg.url.static_url` is a +:meth:`pyramid.configuration.Configurator.add_static_view` API +associated with the path fed to :func:`pyramid.url.static_url` is a *URL* instead of a view name. For example, the ``name`` argument given to either the ZCML directive or the configurator API may be ``http://example.com`` while the the ``path`` given may be @@ -251,23 +245,23 @@ static resources to only be available when the :term:`context` of the view is of a particular type, or when the request is of a particular type. -The :class:`repoze.bfg.view.static` helper class is used to perform +The :class:`pyramid.view.static` helper class is used to perform this task. This class creates an object that is capable acting as a -:mod:`repoze.bfg` view callable which serves static resources from a +:mod:`pyramid` view callable 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 the -:class:`repoze.bfg.view.static` class inside a ``static.py`` file in +:class:`pyramid.view.static` class inside a ``static.py`` file in your application root as below. .. ignore-next-block .. code-block:: python :linenos: - from repoze.bfg.view import static + from pyramid.view import static static_view = static('/path/to/static/dir') -.. note:: the argument to :class:`repoze.bfg.view.static` can also be +.. note:: the argument to :class:`pyramid.view.static` can also be a relative pathname, e.g. ``my/static`` (meaning relative to the Python package of the module in which the view is being defined). It can also be a :term:`resource specification` @@ -278,7 +272,7 @@ your application root as below. Subsequently, you may wire this view up to be accessible as ``/static`` using either the -:mod:`repoze.bfg.configuration.Configurator.add_view` method or the +:mod:`pyramid.configuration.Configurator.add_view` method or the ```` ZCML directive in your application's ``configure.zcml`` against either the class or interface that represents your root object. For example (ZCML): @@ -293,7 +287,7 @@ object. For example (ZCML): /> In this case, ``.models.Root`` refers to the class of which your -:mod:`repoze.bfg` application's root object is an instance. +:mod:`pyramid` application's root object is an instance. You can also provide a ``context`` of ``*`` if you want the name ``static`` to be accessible as the static view against any model. @@ -301,7 +295,7 @@ This will also allow ``/static/foo.js`` to work, but it will allow for ``/anything/static/foo.js`` too, as long as ``anything`` itself is resolvable. -Note that you cannot use the :func:`repoze.bfg.static_url` API to +Note that you cannot use the :func:`pyramid.static_url` API to generate URLs against resources made accessible by registering a custom static view. -- cgit v1.2.3