diff options
Diffstat (limited to 'docs/narr/static.rst')
| -rw-r--r-- | docs/narr/static.rst | 272 |
1 files changed, 111 insertions, 161 deletions
diff --git a/docs/narr/static.rst b/docs/narr/static.rst index 02ee68eb6..a60b84445 100644 --- a/docs/narr/static.rst +++ b/docs/narr/static.rst @@ -6,88 +6,65 @@ resources from a directory on a filesystem. This chapter describes how to configure :mod:`pyramid` to do so. .. index:: - triple: view; zcml; static resource single: add_static_view .. _static_resources_section: -Serving Static Resources Using a ZCML Directive ------------------------------------------------ - -Use of the ``static`` ZCML directive or the -: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``. - -Note that the ``path`` provided to ``static`` may be a fully qualified -:term:`resource specification`, a package-relative path, or an -*absolute path*. The ``path`` with the value ``a/b/c/static`` of a -``static`` directive in a ZCML file that resides in the "mypackage" -package will resolve to a package-qualified resource such as -``some_package:a/b/c/static``. - -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:`pyramid` application using an -absolute path. - -.. code-block:: xml - :linenos: +Serving Static Resources +------------------------ + +Use the :meth:`pyramid.configuration.Configurator.add_static_view` 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``. - <static - name="static" - path="/var/www/static" - /> +Note that the ``path`` provided to +:meth:`pyramid.configuration.Configurator.add_static_view` may be a fully +qualified :term:`resource specification` or an *absolute path*. -Here's an example of a ``static`` directive that will serve files up -under the ``/static`` URL from the ``a/b/c/static`` directory of the -Python package named ``some_package`` using a fully qualified -:term:`resource specification`. +Here's an example of a use of +:meth:`pyramid.configuration.Configurator.add_static_view` that will serve +files up under the ``/static`` URL from the ``/var/www/static`` directory of +the computer which runs the :mod:`pyramid` application using an absolute +path. -.. code-block:: xml +.. code-block:: python :linenos: - <static - name="static" - path="some_package:a/b/c/static" - /> + # config is an instance of pyramid.configuration.Configurator + config.add_static_view(name='static', path='/var/www/static') -Here's an example of a ``static`` directive that will serve files up -under the ``/static`` URL from the ``static`` directory of the Python -package in which the ``configure.zcml`` file lives using a -package-relative path. +Here's an example of +:meth:`pyramid.configuration.Configurator.add_static_view` that will serve +files up under the ``/static`` URL from the ``a/b/c/static`` directory of the +Python package named ``some_package`` using a fully qualified :term:`resource +specification`. -.. code-block:: xml +.. code-block:: python :linenos: - <static - name="static" - path="static" - /> - -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 -``path`` of the directive, you will then be able to view the static -files in this directory via a browser at URLs prefixed with the -directive's ``name``. For instance if the ``static`` directive's + # config is an instance of pyramid.configuration.Configurator + config.add_static_view(name='static', path='some_package:a/b/c/static') + +Whether you use for ``path`` a fully qualified resource specification, or an +absolute path, when you place your static files on the filesystem in the +directory represented as the ``path`` of the directive, you will then be able +to view the static files in this directory via a browser at URLs prefixed +with the directive's ``name``. For instance if the ``static`` directive's ``name`` is ``static`` and the static directive's ``path`` is -``/path/to/static``, ``http://localhost:6543/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. - -While the ``path`` argument can be a number of different things, the -``name`` argument of the ``static`` ZCML directive can also be one of -a number of things: a *view name* or a *URL*. The above examples have -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:`pyramid.url.static_url`. +``/path/to/static``, ``http://localhost:6543/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. + +While the ``path`` argument can be a number of different things, the ``name`` +argument of the call to +:meth:`pyramid.configuration.Configurator.add_static_view` can also be one of +a number of things: a *view name* or a *URL*. The above examples have 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:`pyramid.url.static_url`. .. note:: @@ -109,32 +86,30 @@ is used as the URL prefix when generating a URL using for a pattern; any setting name other than ``media_location`` could be used. -For example, the ``static`` ZCML directive may be fed a ``name`` -argument which is ``http://example.com/images``: +For example, :meth:`pyramid.configuration.Configurator.add_static_view` may +be fed a ``name`` argument which is ``http://example.com/images``: -.. code-block:: xml +.. code-block:: python :linenos: - <static - name="http://example.com/images" - path="mypackage: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:`pyramid.url.static_url` with paths that -start with the ``path`` argument passed to -: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:`pyramid.url.static_url` API is discussed in more detail -later in this chapter. - -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. + # config is an instance of pyramid.configuration.Configurator + config.add_static_view(name='http://example.com/images', + path='mypackage:images') + +Because :meth:`pyramid.configuration.Configurator.add_static_view` is +provided with a ``name`` argument that is the URL prefix +``http://example.com/images``, subsequent calls to +:func:`pyramid.url.static_url` with paths that start with the ``path`` +argument passed to :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:`pyramid.url.static_url` API +is discussed in more detail later in this chapter. + +The :ref:`static_directive` ZCML directive offers an declarative equivalent +to :meth:`pyramid.configuration.Configurator.add_static_view`. Use of the +:ref:`static_directive` ZCML directive is completely equivalent to using +imperative configuration for the same purpose. .. index:: single: generating static resource urls @@ -145,42 +120,30 @@ method is completely equivalent to using ZCML for the same purpose. Generating Static Resource URLs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a :ref:`static_directive` ZCML directive or a call to the -``add_static_view`` method of a -:class:`pyramid.configuration.Configurator` is used to register a -static resource directory, a special helper API named -: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. +When a :meth:`pyramid.configuration.Configurator.add_static_view`` method is +used to register a static resource directory, a special helper API named +: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. -For example, let's assume you create a set of ``static`` declarations -in ZCML like so: +For example, let's assume you create a set of static declarations like so: -.. code-block:: xml +.. code-block:: python :linenos: - <static - name="static1" - path="resources/1" - /> - - <static - name="static2" - path="resources/2" - /> + config.add_static_view(name='static1', path='mypackage:resources/1') + config.add_static_view(name='static2', path='mypackage:resources/2') -These declarations create URL-accessible directories which have URLs -which begin, respectively, with ``/static1`` and ``/static2``. The -resources in the ``resources/1`` directory are consulted when a user -visits a URL which begins with ``/static1``, and the resources in the -``resources/2`` directory are consulted when a user visits a URL which -begins with ``/static2``. +These declarations create URL-accessible directories which have URLs which +begin, respectively, with ``/static1`` and ``/static2``. The resources in +the ``resources/1`` directory of the ``mypackage`` package are consulted when +a user visits a URL which begins with ``/static1``, and the resources in the +``resources/2`` directory of the ``mypackage`` package are consulted when a +user visits a URL which begins with ``/static2``. You needn't generate the URLs to static resources "by hand" in such a 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: +to generate them for you. For example: .. code-block:: python :linenos: @@ -189,8 +152,8 @@ above ZCML file: from pyramid.chameleon_zpt import render_template_to_response def my_view(request): - css_url = static_url('resources/1/foo.css', request) - js_url = static_url('resources/2/foo.js', request) + css_url = static_url('mypackage:resources/1/foo.css', request) + js_url = static_url('mypackage:resources/2/foo.js', request) return render_template_to_response('templates/my_template.pt', css_url = css_url, js_url = js_url) @@ -200,29 +163,23 @@ 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:`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:`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:`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 +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, the generated URLs will continue to resolve +properly after the rename. + +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 :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 may be ``http://example.com`` while the the ``path`` given may be ``mypackage:images``: -.. code-block:: xml +.. code-block:: python :linenos: - <static - name="static1" - path="mypackage:images" - /> + config.add_static_view(name='static1', path='mypackage:images') Under such a configuration, the URL generated by ``static_url`` for resources which begin with ``mypackage:images`` will be prefixed with @@ -270,34 +227,27 @@ your application root as below. "here-relative", it is relative to the package of the module in which the static view is defined. -Subsequently, you may wire this view up to be accessible as -``/static`` using either the -:mod:`pyramid.configuration.Configurator.add_view` method or the -``<view>`` ZCML directive in your application's ``configure.zcml`` -against either the class or interface that represents your root -object. For example (ZCML): - -.. code-block:: xml +Subsequently, you may wire this view up to be accessible as ``/static`` using +the :mod:`pyramid.configuration.Configurator.add_view` method in your +application's startup code against either the class or interface that +represents your root object. + +.. code-block:: python :linenos: - <view - context=".models.Root" - view=".static.static_view" - name="static" - /> + config.add_view('mypackage.static.static_view', name='static', + context='mypackage.models.Root') -In this case, ``.models.Root`` refers to the class of which your +In this case, ``mypackage.models.Root`` refers to the class of which your :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. -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. +You can also omit the ``context`` argument if you want the name ``static`` to +be accessible as the static view against any model. 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:`pyramid.static_url` API to -generate URLs against resources made accessible by registering a -custom static view. +Note that you cannot use the :func:`pyramid.static_url` API to generate URLs +against resources made accessible by registering a custom static view. .. warning:: |