diff options
Diffstat (limited to 'docs/narr/resources.rst')
| -rw-r--r-- | docs/narr/resources.rst | 24 |
1 files changed, 12 insertions, 12 deletions
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 621db577d..e98c34595 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -22,7 +22,7 @@ example, each of the following is a resource: in it (if it possessed an ``__init__.py`` it would *be* a package). The use of resources is quite common in most web development projects. -For example, when you create a :mod:`pyramid` application using one +For example, when you create a :app:`Pyramid` application using one of the available "paster" templates, as described in :ref:`creating_a_project`, the directory representing the application contains a Python :term:`package`. Within that Python package, there @@ -36,7 +36,7 @@ files. Understanding Resources ----------------------- -Let's imagine you've created a :mod:`pyramid` application that uses +Let's imagine you've created a :app:`Pyramid` application that uses a :term:`Chameleon` ZPT template via the :func:`pyramid.chameleon_zpt.render_template_to_response` API. For example, the application might address the resource named @@ -50,20 +50,20 @@ file inside a ``myapp`` package: from pyramid.chameleon_zpt import render_template_to_response render_template_to_response('templates/some_template.pt') -"Under the hood", when this API is called, :mod:`pyramid` attempts +"Under the hood", when this API is called, :app:`Pyramid` attempts to make sense out of the string ``templates/some_template.pt`` provided by the developer. To do so, it first finds the "current" package. The "current" package is the Python package in which the ``views.py`` module which contains this code lives. This would be the ``myapp`` package, according to our example so far. By resolving the -current package, :mod:`pyramid` has enough information to locate +current package, :app:`Pyramid` has enough information to locate the actual template file. These are the elements it needs: - The *package name* (``myapp``) - The *resource name* (``templates/some_template.pt``) -:mod:`pyramid` uses the :term:`pkg_resources` API to resolve the +:app:`Pyramid` uses the :term:`pkg_resources` API to resolve the package name and resource name to an absolute (operating-system-specific) file name. It eventually passes this resolved absolute filesystem path to the Chameleon templating engine, @@ -82,8 +82,8 @@ Overriding Resources -------------------- It can often be useful to override specific resources "from outside" a -given :mod:`pyramid` application. For example, you may wish to -reuse an existing :mod:`pyramid` application more or less +given :app:`Pyramid` application. For example, you may wish to +reuse an existing :app:`Pyramid` application more or less unchanged. However, some specific template file owned by the application might have inappropriate HTML, or some static resource (such as a logo file or some CSS file) might not be appropriate. You @@ -95,7 +95,7 @@ customers (such as a CMS application, or some bug tracking application), and you want to make arbitrary visual modifications to a particular application deployment without forking the underlying code. -To this end, :mod:`pyramid` contains a feature that makes it +To this end, :app:`Pyramid` contains a feature that makes it possible to "override" one resource with one or more other resources. In support of this feature, a :term:`ZCML` directive exists named ``resource``. The ``resource`` directive allows you to *override* the @@ -118,7 +118,7 @@ Usually, overriding a resource in an existing application means performing the following steps: - Create a new Python package. The easiest way to do this is to - create a new :mod:`pyramid` application using the "paster" + create a new :app:`Pyramid` application using the "paster" template mechanism. See :ref:`creating_a_project` for more information. @@ -129,7 +129,7 @@ performing the following steps: - Change the ``configure.zcml`` in the new package to include one or more ``resource`` ZCML directives (see :ref:`resource_directive` below). The new package's ``configure.zcml`` should then include - the original :mod:`pyramid` application's ``configure.zcml`` via + the original :app:`Pyramid` application's ``configure.zcml`` via an include statement, e.g. ``<include package="theoriginalpackage"/>``. @@ -142,7 +142,7 @@ performing the following steps: for more information about this setting. Note that overriding resources is not the only way to extend or modify -the behavior of an existing :mod:`pyramid` application. A "heavier +the behavior of an existing :app:`Pyramid` application. A "heavier hammer" way to do the same thing is explained in :ref:`extending_chapter`. The heavier hammer way allows you to replace a :term:`view` wholesale rather than resources that might be @@ -250,7 +250,7 @@ Instead of using all the tasks described above within :term:`ZCML`. The ZCML ``resource`` tag is a frontend to using ``override_resource``. -An individual :mod:`pyramid` ``resource`` ZCML statement can +An individual :app:`Pyramid` ``resource`` ZCML statement can override a single resource. For example: .. code-block:: xml |