diff options
Diffstat (limited to 'docs/narr/assets.rst')
| -rw-r--r-- | docs/narr/assets.rst | 60 |
1 files changed, 31 insertions, 29 deletions
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index e609a3eab..c8508f1b5 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -165,7 +165,8 @@ Instead of representing a URL prefix, the ``name`` argument of a call to *URL*. Each of examples we've seen so far have shown usage of the ``name`` argument as a URL prefix. However, when ``name`` is a *URL*, static assets 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`. +as the URL prefix when generating a URL using +:meth:`pyramid.request.Request.static_url`. For example, :meth:`~pyramid.config.Configurator.add_static_view` may be fed a ``name`` argument which is ``http://example.com/images``: @@ -179,13 +180,13 @@ be fed a ``name`` argument which is ``http://example.com/images``: Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with a ``name`` argument that is the URL ``http://example.com/images``, subsequent -calls to :func:`~pyramid.url.static_url` with paths that start with the -``path`` argument passed to +calls to :meth:`~pyramid.request.Request.static_url` with paths that start +with the ``path`` argument passed to :meth:`~pyramid.config.Configurator.add_static_view` will generate a URL something like ``http://example.com/images/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. +properly to such a request. The :meth:`~pyramid.request.Request.static_url` +API is discussed in more detail later in this chapter. .. index:: single: generating static asset urls @@ -199,9 +200,9 @@ Generating Static Asset URLs When a :meth:`~pyramid.config.Configurator.add_static_view` method is used to register a static asset directory, a special helper API named -:func:`pyramid.url.static_url` can be used to generate the appropriate URL -for an asset that lives in one of the directories named by the static -registration ``path`` attribute. +:meth:`pyramid.request.Request.static_url` can be used to generate the +appropriate URL for an asset 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 like so: @@ -219,18 +220,17 @@ visits a URL which begins with ``/static1``, and the assets in the visits a URL which begins with ``/static2``. You needn't generate the URLs to static assets "by hand" in such a -configuration. Instead, use the :func:`~pyramid.url.static_url` API to -generate them for you. For example: +configuration. Instead, use the :meth:`~pyramid.request.Request.static_url` +API to generate them for you. For example: .. code-block:: python :linenos: - from pyramid.url import static_url from pyramid.chameleon_zpt import render_template_to_response def my_view(request): - css_url = static_url('mypackage:assets/1/foo.css', request) - js_url = static_url('mypackage:assets/2/foo.js', request) + css_url = request.static_url('mypackage:assets/1/foo.css') + js_url = request.static_url('mypackage:assets/2/foo.js') return render_template_to_response('templates/my_template.pt', css_url = css_url, js_url = js_url) @@ -240,17 +240,18 @@ 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, the generated URLs will continue to resolve -properly after the rename. +One benefit of using the :meth:`~pyramid.request.Request.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 assets -that live *outside* the :app:`Pyramid` application. This will happen when -the :meth:`~pyramid.config.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``: +URLs may also be generated by :meth:`~pyramid.request.Request.static_url` to +static assets that live *outside* the :app:`Pyramid` application. This will +happen when the :meth:`~pyramid.config.Configurator.add_static_view` API +associated with the path fed to :meth:`~pyramid.request.Request.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:: python :linenos: @@ -265,14 +266,14 @@ assets which begin with ``mypackage:images`` will be prefixed with .. code-block:: python :linenos: - static_url('mypackage:images/logo.png', request) + request.static_url('mypackage:images/logo.png') # -> http://example.com/images/logo.png -Using :func:`~pyramid.url.static_url` in conjunction with a +Using :meth:`~pyramid.request.Request.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:`~pyramid.config.Configurator.add_static_view` is a -URL), while keeping static media package-internal and served by the +``name`` argument to :meth:`~pyramid.config.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:`~pyramid.config.Configurator.add_static_view` is a URL prefix). To create such a circumstance, we suggest using the @@ -298,8 +299,9 @@ dispatch`, you may want static assets to only be available as a fallback if no previous route matches. Alternately, you might like to serve a particular static asset manually, because its download requires authentication. -Note that you cannot use the :func:`~pyramid.url.static_url` API to generate -URLs against assets made accessible by registering a custom static view. +Note that you cannot use the :meth:`~pyramid.request.Request.static_url` API +to generate URLs against assets made accessible by registering a custom +static view. Root-Relative Custom Static View (URL Dispatch Only) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |