diff options
Diffstat (limited to 'docs/narr/templates.rst')
| -rw-r--r-- | docs/narr/templates.rst | 116 |
1 files changed, 56 insertions, 60 deletions
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index c1c2fe31e..c86d20935 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -10,7 +10,7 @@ provides add-on templating support through a set of bindings packages. Out of the box, :app:`Pyramid` provides templating via the :term:`Chameleon` and :term:`Mako` templating libraries. :term:`Chameleon` provides support for -two different types of templates: :term:`ZPT` templates and text templates. +two different types of templates: :term:`ZPT` templates, and text templates. Before discussing how built-in templates are used in detail, we'll discuss two ways to render templates within @@ -22,18 +22,18 @@ configuration. .. _templates_used_directly: -Templates Used Directly ------------------------ +Using Templates Directly +------------------------ The most straightforward way to use a template within :app:`Pyramid` is to cause it to be rendered directly within a :term:`view callable`. You may use whatever API is supplied by a given templating engine to do so. -:app:`Pyramid` provides various APIs that allow you to render -templates directly from within a view callable. For example, if there -is a :term:`Chameleon` ZPT template named ``foo.pt`` in a directory in -your application named ``templates``, you can render the template from +:app:`Pyramid` provides various APIs that allow you to render templates +directly from within a view callable. For example, if there is a +:term:`Chameleon` ZPT template named ``foo.pt`` in a directory named +``templates`` in your application, you can render the template from within the body of a view callable like so: .. code-block:: python @@ -58,7 +58,7 @@ within the body of a view callable like so: rendering tasks. This set of functions works to render templates for all renderer extensions registered with :app:`Pyramid`. -The ``sample_view`` :term:`view callable` above returns a +The ``sample_view`` :term:`view callable` function above returns a :term:`response` object which contains the body of the ``templates/foo.pt`` template. In this case, the ``templates`` directory should live in the same directory as the module containing @@ -67,8 +67,8 @@ the ``sample_view`` function. The template author will have the names comparison purposes. In the example above, the path ``templates/foo.pt`` is relative to the -directory in which the file which defines the view configuration -lives. In this case, this is the directory containing the file that +directory containing the file which defines the view configuration. +In this case, this is the directory containing the file that defines the ``sample_view`` function. Although a renderer path is usually just a simple relative pathname, a path named as a renderer can be absolute, starting with a slash on UNIX or a drive letter @@ -76,18 +76,17 @@ prefix on Windows. .. warning:: - The ability for a template to be named as a renderer relative to the - location of the module in which the view callable is defined is limited to - :term:`Chameleon` templates. Mako templates and other templating system - bindings work differently. In particular, Mako templates use a "lookup - path" as defined by the ``mako.directories`` configuration file instead of - treating relative paths as relative to the current view module. See - :ref:`mako_templates`. + Only :term:`Chameleon` templates support defining a renderer for a + template relative to the location of the module where the view + callable is defined. Mako templates, and other templating system + bindings work differently. In particular, Mako templates use a + "lookup path" as defined by the ``mako.directories`` configuration + file instead of treating relative paths as relative to the current + view module. See :ref:`mako_templates`. -The path can alternately be a :term:`resource specification` in the -form ``some.dotted.package_name:relative/path``, making it possible to -address template resources which live in another package. For -example: +The path can alternately be a :term:`resource specification` in the form +``some.dotted.package_name:relative/path``. This makes it possible to +address template resources which live in another package. For example: .. code-block:: python :linenos: @@ -118,29 +117,26 @@ In the examples above we pass in a keyword argument named ``request`` representing the current :app:`Pyramid` request. Passing a request keyword argument will cause the ``render_to_response`` function to supply the renderer with more correct system values (see -:ref:`renderer_system_values`), because most of the information -required to compose proper system values is present in the request. -If you care about the correct system values being provided to the -renderer being called (in particular, if your template relies on the -name ``request`` or ``context``, or if you've configured special -:term:`renderer globals` make sure to pass ``request`` as a keyword -argument in every call to to a ``pyramid.renderers.render_*`` -function. - -Every view must return a :term:`response` object (except for views -which use a :term:`renderer` named via view configuration, which we'll +:ref:`renderer_system_values`), because most of the information required +to compose proper system values is present in the request. If your +template relies on the name ``request`` or ``context``, or if you've +configured special :term:`renderer globals`, make sure to pass +``request`` as a keyword argument in every call to to a +``pyramid.renderers.render_*`` function. + +Every view must return a :term:`response` object, except for views +which use a :term:`renderer` named via view configuration (which we'll see shortly). The :func:`pyramid.renderers.render_to_response` function is a shortcut function that actually returns a response -object. +object. This allows the example view above to simply return the result +of its call to ``render_to_response()`` directly. -Obviously not all APIs you might call to get respnonse data will -return a response object. If you call a "response-ignorant" API that -returns information you'd like to use as a response (such as when you -render a template to a string), you must construct your own response -object as necessary with the string as the body. For example, the -:func:`pyramid.renderers.render` API returns a string. We can -manufacture a :term:`response` object directly, and use that string as -the body of the response: +Obviously not all APIs you might call to get response data will return a +response object. For example, you might render one or more templates to +a string that you want to use as response data. The +:func:`pyramid.renderers.render` API renders a template to a string. We +can manufacture a :term:`response` object directly, and use that string +as the body of the response: .. code-block:: python :linenos: @@ -258,7 +254,7 @@ values are provided in a dictionary to the renderer and include: ``context`` The current :app:`Pyramid` context if ``request`` was provided as - a keyword argument or ``None``. + a keyword argument, or ``None``. ``request`` The request provided as a keyword argument. @@ -267,31 +263,33 @@ values are provided in a dictionary to the renderer and include: The renderer name used to perform the rendering, e.g. ``mypackage:templates/foo.pt``. -``renderer_info`` An object implementing the - :class:`pyramid.interfaces.IRendererInfo` interface. Basically, an object - with the following attributes: ``name``, ``package`` and ``type``. +``renderer_info`` + An object implementing the :class:`pyramid.interfaces.IRendererInfo` + interface. Basically, an object with the following attributes: + ``name``, ``package`` and ``type``. You can define more values which will be passed to every template executed as a result of rendering by defining :term:`renderer globals`. -What any particular renderer does with them is up to the renderer itself, but -most template renderers, including Chameleon and Mako renderers, make these -names available as top-level template variables. +What any particular renderer does with these system values is up to the +renderer itself, but most template renderers, including Chameleon and +Mako renderers, make these names available as top-level template +variables. .. _templates_used_as_renderers: Templates Used as Renderers via Configuration --------------------------------------------- -Instead of using the :func:`pyramid.renderers.render_to_response` -API within the body of a view function directly to render a specific -template to a response, you may associate a template written in a -supported templating language with a view indirectly by specifying it -as a :term:`renderer` in *view configuration*. +An alternative to using :func:`pyramid.renderers.render_to_response` +to render templates manually in your view callable code, is +to specify the template as a :term:`renderer` in your +*view configuration*. This can be done with any of the +templating languages supported by :app:`Pyramid`. To use a renderer via view configuration, specify a template -:term:`resource specification` as the ``renderer`` argument or +:term:`resource specification` as the ``renderer`` argument, or attribute to the :term:`view configuration` of a :term:`view callable`. Then return a *dictionary* from that view callable. The dictionary items returned by the view callable will be made available @@ -314,13 +312,11 @@ template renderer: def my_view(request): return {'foo':1, 'bar':2} -.. note:: It is not necessary to supply the ``request`` value as a key +.. note:: You do not need to supply the ``request`` value as a key in the dictionary result returned from a renderer-configured view - callable in order to ensure that the "most correct" system values - are supplied to the renderer as it is when you use - :func:`pyramid.renderers.render` or - :func:`pyramid.renderers.render_to_response`. This is handled - automatically. + callable. :app:`Pyramid` automatically supplies this value for + you so that the "most correct" system values are provided to + the renderer. .. warning:: |