From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/templates.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 150b173e3..7c575b9bf 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -241,6 +241,9 @@ of :func:`~pyramid.renderers.render` (a string): single: renderer (template) +.. index:: + pair: renderer; system values + .. _renderer_system_values: System Values Used During Rendering @@ -277,6 +280,9 @@ renderer itself, but most template renderers, including Chameleon and Mako renderers, make these names available as top-level template variables. +.. index:: + pair: renderer; templates + .. _templates_used_as_renderers: Templates Used as Renderers via Configuration @@ -426,7 +432,7 @@ See also :ref:`built_in_renderers` for more general information about renderers, including Chameleon ZPT renderers. .. index:: - single: sample template + single: ZPT template (sample) A Sample ZPT Template ~~~~~~~~~~~~~~~~~~~~~ @@ -596,6 +602,9 @@ Note that I always name my Chameleon ZPT template files with a ``.pt`` extension and my Chameleon text template files with a ``.txt`` extension so that these ``svn:ignore`` patterns work. +.. index:: + pair: debugging; templates + .. _debug_templates_section: Nicer Exceptions in Chameleon Templates @@ -724,6 +733,9 @@ in the ``templates`` subdirectory of the ``mypackage`` Python package. See ``mako.directories`` setting and other Mako-related settings that can be placed into the application's ``ini`` file. +.. index:: + single: Mako template (sample) + A Sample Mako Template ~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 39e88a1f2903f840feeff77e572c7bf3efebb875 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 21 Jul 2011 23:08:31 -0400 Subject: - Change all scaffolding templates that point to docs.pylonsproject.org to use ``/projects/pyramid/current`` rather than ``/projects/pyramid/dev``. --- docs/narr/templates.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 7c575b9bf..af7257466 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -454,7 +454,7 @@ Here's what a simple :term:`Chameleon` ZPT template used under

Welcome to `${project}`, an application generated by the pyramid web application framework.

@@ -752,7 +752,7 @@ look like:

Welcome to `${project}`, an application generated by the pyramid web application framework.

-- cgit v1.2.3 From 875ded31e7fdd0c85d1c91458248581b9dd729d7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 30 Jul 2011 01:50:24 -0600 Subject: Updated all of the docs to reflect the new pyramid.* settings prefix. --- docs/narr/templates.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index af7257466..0f46f6422 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -632,15 +632,15 @@ variable set to ``1``, For example: $ PYRAMID_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini To use a setting in the application ``.ini`` file for the same -purpose, set the ``debug_templates`` key to ``true`` within the -application's configuration section, e.g.: +purpose, set the ``pyramid.debug_templates`` key to ``true`` within +the application's configuration section, e.g.: .. code-block:: ini :linenos: [app:MyProject] use = egg:MyProject#app - debug_templates = true + pyramid.debug_templates = true With template debugging off, a :exc:`NameError` exception resulting from rendering a template with an undefined variable @@ -677,7 +677,7 @@ displaying the arguments passed to the template itself. .. note:: - Turning on ``debug_templates`` has the same effect as using the + Turning on ``pyramid.debug_templates`` has the same effect as using the Chameleon environment variable ``CHAMELEON_DEBUG``. See `Chameleon Environment Variables `_ @@ -793,7 +793,7 @@ variable set to ``1``, For example: $ PYRAMID_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini To use a setting in the application ``.ini`` file for the same -purpose, set the ``reload_templates`` key to ``true`` within the +purpose, set the ``pyramid.reload_templates`` key to ``true`` within the application's configuration section, e.g.: .. code-block:: ini @@ -801,7 +801,7 @@ application's configuration section, e.g.: [app:main] use = egg:MyProject#app - reload_templates = true + pyramid.reload_templates = true .. index:: single: template system bindings -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/narr/templates.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 0f46f6422..d5caed4be 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -638,8 +638,8 @@ the application's configuration section, e.g.: .. code-block:: ini :linenos: - [app:MyProject] - use = egg:MyProject#app + [app:main] + use = egg:MyProject pyramid.debug_templates = true With template debugging off, a :exc:`NameError` exception resulting @@ -800,7 +800,7 @@ application's configuration section, e.g.: :linenos: [app:main] - use = egg:MyProject#app + use = egg:MyProject pyramid.reload_templates = true .. index:: -- cgit v1.2.3 From 55ce9d632f828d285360c1abee9f56042243cac9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 28 Aug 2011 22:15:48 -0400 Subject: clean up inappropriate discussions of ZCML --- docs/narr/templates.rst | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d5caed4be..6412c070d 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -335,9 +335,8 @@ template renderer: function. View-configuration-relative asset specifications work only in Chameleon, not in Mako templates. -Similar renderer configuration can be done imperatively and via -:term:`ZCML`. See :ref:`views_which_use_a_renderer`. See also -:ref:`built_in_renderers`. +Similar renderer configuration can be done imperatively. See +:ref:`views_which_use_a_renderer`. See also :ref:`built_in_renderers`. 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 @@ -366,12 +365,7 @@ templates as renderers. See :ref:`available_template_system_bindings`. with renderers externally via view configuration typically return a dictionary, as above. Making assertions about results returned in a dictionary is almost always more direct and straightforward than - needing to parse HTML. Specifying a renderer from within - :term:`ZCML` (as opposed to imperatively or via a ``view_config`` - decorator, or using a template directly from within a view callable) - also makes it possible for someone to modify the template used to - render a view without needing to fork your code to do so. See - :ref:`extending_chapter` for more information. + needing to parse HTML. By default, views rendered via a template renderer return a :term:`Response` object which has a *status code* of ``200 OK``, and a *content-type* of -- cgit v1.2.3 From 012b9762cd0b114b6afbf2d6356554b51706804a Mon Sep 17 00:00:00 2001 From: michr Date: Fri, 23 Sep 2011 18:48:28 -0700 Subject: fixed up all the warning dealing ..note and ..warn added a hide toc for glossary to prevent warnings --- docs/narr/templates.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6412c070d..052843a23 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -46,7 +46,9 @@ within the body of a view callable like so: {'foo':1, 'bar':2}, request=request) -.. warning:: Earlier iterations of this documentation +.. warning:: + + Earlier iterations of this documentation (pre-version-1.3) encouraged the application developer to use ZPT-specific APIs such as :func:`pyramid.chameleon_zpt.render_template_to_response` and -- cgit v1.2.3 From cfb2b5596b8ef366aeef3bce5b61eafc7a2f175d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:05:29 -0400 Subject: remove all reference to the paster command-line utility --- docs/narr/templates.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 052843a23..fb9dd56c2 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -625,7 +625,7 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini + $ PYRAMID_DEBUG_TEMPLATES=1 bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.debug_templates`` key to ``true`` within @@ -786,7 +786,7 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini + $ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.reload_templates`` key to ``true`` within the -- cgit v1.2.3 From 56f1d2ea13f93b46161d12112e75125efee2120b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 21 Nov 2011 12:03:47 -0500 Subject: de-jythonify --- docs/narr/templates.rst | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index fb9dd56c2..11318d9eb 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -403,14 +403,6 @@ The language definition documentation for Chameleon ZPT-style templates is available from `the Chameleon website `_. -.. warning:: - - :term:`Chameleon` only works on :term:`CPython` platforms and - :term:`Google App Engine`. On :term:`Jython` and other non-CPython - platforms, you should use Mako (see :ref:`mako_templates`) or - ``pyramid_jinja2`` instead. See - :ref:`available_template_system_bindings`. - Given a :term:`Chameleon` ZPT template named ``foo.pt`` in a directory in your application named ``templates``, you can render the template as a :term:`renderer` like so: -- cgit v1.2.3 From 488ea03753d0434b1ddf0c3b2204463c229e7244 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 15 Mar 2012 09:02:18 -0700 Subject: remove debug_templates untruths related to issue #491 --- docs/narr/templates.rst | 63 ++++--------------------------------------------- 1 file changed, 5 insertions(+), 58 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 11318d9eb..ed700f7b4 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -593,56 +593,11 @@ extension so that these ``svn:ignore`` patterns work. .. index:: pair: debugging; templates -.. _debug_templates_section: +Debugging Templates +------------------- -Nicer Exceptions in Chameleon Templates ---------------------------------------- - -The exceptions raised by Chameleon templates when a rendering fails -are sometimes less than helpful. :app:`Pyramid` allows you to -configure your application development environment so that exceptions -generated by Chameleon during template compilation and execution will -contain nicer debugging information. - -.. warning:: Template-debugging behavior is not recommended for - production sites as it slows renderings; it's usually - only desirable during development. - -In order to turn on template exception debugging, you can use an -environment variable setting or a configuration file setting. - -To use an environment variable, start your application under a shell -using the ``PYRAMID_DEBUG_TEMPLATES`` operating system environment -variable set to ``1``, For example: - -.. code-block:: text - - $ PYRAMID_DEBUG_TEMPLATES=1 bin/pserve myproject.ini - -To use a setting in the application ``.ini`` file for the same -purpose, set the ``pyramid.debug_templates`` key to ``true`` within -the application's configuration section, e.g.: - -.. code-block:: ini - :linenos: - - [app:main] - use = egg:MyProject - pyramid.debug_templates = true - -With template debugging off, a :exc:`NameError` exception resulting -from rendering a template with an undefined variable -(e.g. ``${wrong}``) might end like this: - -.. code-block:: text - - File "...", in __getitem__ - raise NameError(key) - NameError: wrong - -Note that the exception has no information about which template was -being rendered when the error occured. But with template debugging -on, an exception resulting from the same problem might end like so: +A :exc:`NameError` exception resulting from rendering a template with an +undefined variable (e.g. ``${wrong}``) might will end like this: .. code-block:: text @@ -660,17 +615,9 @@ on, an exception resulting from the same problem might end like so: NameError: wrong -The latter tells you which template the error occurred in, as well as +The output tells you which template the error occurred in, as well as displaying the arguments passed to the template itself. -.. note:: - - Turning on ``pyramid.debug_templates`` has the same effect as using the - Chameleon environment variable ``CHAMELEON_DEBUG``. See `Chameleon - Environment Variables - `_ - for more information. - .. index:: single: template internationalization single: internationalization (of templates) -- cgit v1.2.3 From eb33944d0d861bbb3aebdf069cce64f8c1c3faef Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 21 Mar 2012 18:58:22 -0400 Subject: flesh out system values --- docs/narr/templates.rst | 49 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 16 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index ed700f7b4..9db0b1c4d 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -253,16 +253,26 @@ System Values Used During Rendering When a template is rendered using :func:`~pyramid.renderers.render_to_response` or -:func:`~pyramid.renderers.render`, the renderer representing the -template will be provided with a number of *system* values. These -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``. +:func:`~pyramid.renderers.render`, or a ``renderer=`` argument to view +configuration (see :ref:`templates_used_as_renderers`), the renderer +representing the template will be provided with a number of *system* values. +These values are provided to the template: ``request`` - The request provided as a keyword argument. + The value provided as the ``request`` keyword argument to + ``render_to_response`` or ``render`` *or* the request object passed to the + view when the ``renderer=`` argument to view configuration is being used to + render the template. + +``req`` + An alias for ``request``. + +``context`` + The current :app:`Pyramid` :term:`context` if ``request`` was provided as a + keyword argument to ``render_to_response`` or ``render``, or ``None`` if + the ``request`` keyword argument was not provided. This value will always + be provided if the template is rendered as the result of a ``renderer=`` + argument to view configuration being used. ``renderer_name`` The renderer name used to perform the rendering, @@ -270,17 +280,24 @@ values are provided in a dictionary to the renderer and include: ``renderer_info`` An object implementing the :class:`pyramid.interfaces.IRendererInfo` - interface. Basically, an object with the following attributes: - ``name``, ``package`` and ``type``. + interface. Basically, an object with the following attributes: ``name``, + ``package`` and ``type``. + +``view`` + The view callable object that was used to render this template. If the + view callable is a method of a class-based view, this will be an instance + of the class that the method was defined on. If the view callable is a + function or instance, it will be that function or instance. Note that this + value will only be automatically present when a template is rendered as a + result of a ``renderer=`` argument; it will be ``None`` when the + ``render_to_response`` or ``render`` APIs are used. -You can define more values which will be passed to every template -executed as a result of rendering by defining :term:`renderer -globals`. +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 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. +renderer itself, but most template renderers, including Chameleon and Mako +renderers, make these names available as top-level template variables. .. index:: pair: renderer; templates -- cgit v1.2.3 From ea009a6d4a1ffa8585faa85581848f6e74a57dfc Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Tue, 19 Jun 2012 20:12:55 -0400 Subject: added docs and changes for using defs in mako renderer --- docs/narr/templates.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 9db0b1c4d..4ac01c96e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -714,6 +714,22 @@ This template doesn't use any advanced features of Mako, only the :term:`renderer globals`. See the `the Mako documentation `_ to use more advanced features. +Using def inside Mako Templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use a def inside a Mako template, given a :term:`Mako` template file named +``foo.mak`` and a def named ``bar``, you can configure the template as a +:term:`renderer` like so: + +.. code-block:: python + :linenos: + + from pyramid.view import view_config + + @view_config(renderer='foo#defname.mak') + def my_view(request): + return {'project':'my project'} + .. index:: single: automatic reloading of templates single: template automatic reload -- cgit v1.2.3 From 6cea47e9c34841cdf109899e8d965c67af3a5ce9 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Tue, 19 Jun 2012 20:20:17 -0400 Subject: fixed typos --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 4ac01c96e..5656026ae 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -718,7 +718,7 @@ Using def inside Mako Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To use a def inside a Mako template, given a :term:`Mako` template file named -``foo.mak`` and a def named ``bar``, you can configure the template as a +``foo.mak`` and a defname ``bar``, you can configure the template as a :term:`renderer` like so: .. code-block:: python -- cgit v1.2.3 From c2d65ff71dac6a9b15119db8c2fb09884f4060e3 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Tue, 19 Jun 2012 20:22:34 -0400 Subject: fixed typos --- docs/narr/templates.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 5656026ae..860010a1a 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -718,7 +718,7 @@ Using def inside Mako Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To use a def inside a Mako template, given a :term:`Mako` template file named -``foo.mak`` and a defname ``bar``, you can configure the template as a +``foo.mak`` and a def named ``bar``, you can configure the template as a :term:`renderer` like so: .. code-block:: python @@ -726,7 +726,7 @@ To use a def inside a Mako template, given a :term:`Mako` template file named from pyramid.view import view_config - @view_config(renderer='foo#defname.mak') + @view_config(renderer='foo#bar.mak') def my_view(request): return {'project':'my project'} -- cgit v1.2.3 From eecaa867d72d06fec45dd151fcd2e93d02927cef Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 29 Aug 2012 16:07:54 -0400 Subject: add docs about chameleon zpt macro feature --- docs/narr/templates.rst | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 860010a1a..adc671766 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -534,6 +534,30 @@ And ``templates/mytemplate.pt`` might look like so: + +Using A Chameleon Macro Name Within a Chameleon ZPT Template +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sommetime you'd like to render a macro inside of a Chameleon ZPT template +instead of the full Chameleon ZPT template. To render the content of a +``define-macro`` field inside a Chameleon ZPT template, given a Chameleon +template file named ``foo.pt`` and a macro named ``bar`` defined within it +(e.g. ``

...

``, you can configure the +template as a :term:`renderer` like so: + +.. code-block:: python + :linenos: + + from pyramid.view import view_config + + @view_config(renderer='foo#bar.pt') + def my_view(request): + return {'project':'my project'} + +The above will render the ``bar`` macro from within the ``foo.pt`` template +instead of the entire template. + + .. index:: single: Chameleon text templates @@ -714,12 +738,13 @@ This template doesn't use any advanced features of Mako, only the :term:`renderer globals`. See the `the Mako documentation `_ to use more advanced features. -Using def inside Mako Templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using A Mako def name Within a Renderer Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To use a def inside a Mako template, given a :term:`Mako` template file named -``foo.mak`` and a def named ``bar``, you can configure the template as a -:term:`renderer` like so: +Sommetime you'd like to render a ``def`` inside of a Mako template instead of +the full Mako template. To render a def inside a Mako template, given a +:term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can +configure the template as a :term:`renderer` like so: .. code-block:: python :linenos: @@ -730,6 +755,9 @@ To use a def inside a Mako template, given a :term:`Mako` template file named def my_view(request): return {'project':'my project'} +The above will render the ``bar`` def from within the ``foo.mak`` template +instead of the entire template. + .. index:: single: automatic reloading of templates single: template automatic reload -- cgit v1.2.3 From 3a9232533139456c86483a9a53001b8500e433e9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 29 Aug 2012 16:10:26 -0400 Subject: wording --- docs/narr/templates.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index adc671766..4e6570865 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -535,8 +535,8 @@ And ``templates/mytemplate.pt`` might look like so: -Using A Chameleon Macro Name Within a Chameleon ZPT Template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using A Chameleon Macro Name Within a Renderer Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sommetime you'd like to render a macro inside of a Chameleon ZPT template instead of the full Chameleon ZPT template. To render the content of a -- cgit v1.2.3 From cc8962d5da32bb30bbfc37c96286282b5ed751ff Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 29 Aug 2012 17:21:14 -0400 Subject: add newness markers --- docs/narr/templates.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 4e6570865..656cf4773 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -557,6 +557,9 @@ template as a :term:`renderer` like so: The above will render the ``bar`` macro from within the ``foo.pt`` template instead of the entire template. +.. note:: + + This feature is new in Pyramid 1.4. .. index:: single: Chameleon text templates @@ -758,6 +761,10 @@ configure the template as a :term:`renderer` like so: The above will render the ``bar`` def from within the ``foo.mak`` template instead of the entire template. +.. note:: + + This feature is new in Pyramid 1.4. + .. index:: single: automatic reloading of templates single: template automatic reload -- cgit v1.2.3 From 3aeb794d49655e7cd81b7d553f0da275b0cde3a9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 29 Aug 2012 18:05:52 -0400 Subject: close paren --- docs/narr/templates.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 656cf4773..5930bb379 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -542,7 +542,7 @@ Sommetime you'd like to render a macro inside of a Chameleon ZPT template instead of the full Chameleon ZPT template. To render the content of a ``define-macro`` field inside a Chameleon ZPT template, given a Chameleon template file named ``foo.pt`` and a macro named ``bar`` defined within it -(e.g. ``

...

``, you can configure the +(e.g. ``

...

``), you can configure the template as a :term:`renderer` like so: .. code-block:: python @@ -554,8 +554,8 @@ template as a :term:`renderer` like so: def my_view(request): return {'project':'my project'} -The above will render the ``bar`` macro from within the ``foo.pt`` template -instead of the entire template. +The above will render only the ``bar`` macro defined within the ``foo.pt`` +template instead of the entire template. .. note:: -- cgit v1.2.3 From b72ba1a98ebc6fc6c8d9a11ab1c340b89015e644 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 13 Sep 2012 02:05:19 -0400 Subject: add upgrading chapter, make docs render again --- docs/narr/templates.rst | 30 ++++++------------------------ 1 file changed, 6 insertions(+), 24 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 656cf4773..9a825c2ab 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -46,20 +46,6 @@ within the body of a view callable like so: {'foo':1, 'bar':2}, request=request) -.. warning:: - - Earlier iterations of this documentation - (pre-version-1.3) encouraged the application developer to use - ZPT-specific APIs such as - :func:`pyramid.chameleon_zpt.render_template_to_response` and - :func:`pyramid.chameleon_zpt.render_template` to render templates - directly. This style of rendering still works, but at least for - purposes of this documentation, those functions are deprecated. - Application developers are encouraged instead to use the functions - available in the :mod:`pyramid.renderers` module to perform - rendering tasks. This set of functions works to render templates - for all renderer extensions registered with :app:`Pyramid`. - 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`` @@ -79,12 +65,12 @@ prefix on Windows. .. warning:: 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`. + 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:`asset specification` in the form ``some.dotted.package_name:relative/path``. This makes it possible to @@ -600,10 +586,6 @@ When the template is rendered, it will show: Hello, world! -If you'd rather use templates directly within a view callable (without -the indirection of using a renderer), see :ref:`chameleon_text_module` -for the API description. - See also :ref:`built_in_renderers` for more general information about renderers, including Chameleon text renderers. -- cgit v1.2.3 From 043ccddb909327106264d10ed5d413760a51770d Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 2 Jan 2013 02:22:52 +0200 Subject: eliminate other repeated words --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index ba72ebfbf..1cec26fbc 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -109,7 +109,7 @@ supply the renderer with more correct system values (see 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 +``request`` as a keyword argument in every call to a ``pyramid.renderers.render_*`` function. Every view must return a :term:`response` object, except for views -- cgit v1.2.3 From 40dbf42a2df1783c3d803adf950380c21512bb91 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 30 Jan 2013 00:41:23 +0200 Subject: use the more appropriate directives --- docs/narr/templates.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 1cec26fbc..6a1fbf916 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -543,9 +543,7 @@ template as a :term:`renderer` like so: The above will render only the ``bar`` macro defined within the ``foo.pt`` template instead of the entire template. -.. note:: - - This feature is new in Pyramid 1.4. +.. versionadded:: 1.4 .. index:: single: Chameleon text templates @@ -743,9 +741,7 @@ configure the template as a :term:`renderer` like so: The above will render the ``bar`` def from within the ``foo.mak`` template instead of the entire template. -.. note:: - - This feature is new in Pyramid 1.4. +.. versionadded:: 1.4 .. index:: single: automatic reloading of templates -- cgit v1.2.3 From 16f2011492d96f1e6169bfbd05cd003192b07329 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 26 Feb 2013 23:08:10 +0200 Subject: grammar --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6a1fbf916..89024a34e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -621,7 +621,7 @@ Debugging Templates ------------------- A :exc:`NameError` exception resulting from rendering a template with an -undefined variable (e.g. ``${wrong}``) might will end like this: +undefined variable (e.g. ``${wrong}``) might end up looking like this: .. code-block:: text -- cgit v1.2.3 From 58577149d79ed4e5aae6a90423c5b43edd811987 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 6 Mar 2013 01:11:12 +0200 Subject: fix typo, and change meaning --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 89024a34e..08fa9883e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -524,7 +524,7 @@ And ``templates/mytemplate.pt`` might look like so: Using A Chameleon Macro Name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sommetime you'd like to render a macro inside of a Chameleon ZPT template +At times, you may want to render a macro inside of a Chameleon ZPT template instead of the full Chameleon ZPT template. To render the content of a ``define-macro`` field inside a Chameleon ZPT template, given a Chameleon template file named ``foo.pt`` and a macro named ``bar`` defined within it -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 08fa9883e..1f1c07027 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -771,7 +771,7 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini + $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.reload_templates`` key to ``true`` within the -- cgit v1.2.3 From 1ad8de2b9032b5a452b75274b8f908645c732e57 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 22 Mar 2013 17:24:32 +0200 Subject: remove unused ignore-next-block directive --- docs/narr/templates.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 1f1c07027..d4cf20b93 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -150,7 +150,6 @@ string, then return that string as the body of a :app:`Pyramid` For example, here's an example of using "raw" `Mako `_ from within a :app:`Pyramid` :term:`view`: -.. ignore-next-block .. code-block:: python :linenos: -- cgit v1.2.3 From efcf8f1c8b1e1140a5e9d9bb6fea558150ae7c29 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sat, 3 Aug 2013 11:34:05 -0400 Subject: Some more occurrences of "application framework". --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d4cf20b93..f1e1634b8 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -711,7 +711,7 @@ look like:

Welcome to `${project}`, an application generated by the pyramid web application framework.

+ >pyramid web framework. -- cgit v1.2.3 From 7683e22a93a3df2a541dddb9afac540ef9094f49 Mon Sep 17 00:00:00 2001 From: Jeff Szusz Date: Mon, 12 Aug 2013 11:10:09 -0400 Subject: #967 fixed 'Sommetime' -> 'Sometime' in templates.rst --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d4cf20b93..ddebb3fa2 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -723,7 +723,7 @@ This template doesn't use any advanced features of Mako, only the Using A Mako def name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sommetime you'd like to render a ``def`` inside of a Mako template instead of +Sometime you'd like to render a ``def`` inside of a Mako template instead of the full Mako template. To render a def inside a Mako template, given a :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can configure the template as a :term:`renderer` like so: -- cgit v1.2.3 From fc9d4cbc8b3ccbd2c2b5c942595bf420eeae4596 Mon Sep 17 00:00:00 2001 From: Jeff Szusz Date: Mon, 12 Aug 2013 11:28:53 -0400 Subject: Update templates.rst --- docs/narr/templates.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index ddebb3fa2..af5ad6c5c 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -723,7 +723,7 @@ This template doesn't use any advanced features of Mako, only the Using A Mako def name Within a Renderer Name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sometime you'd like to render a ``def`` inside of a Mako template instead of +Sometimes you'd like to render a ``def`` inside of a Mako template instead of the full Mako template. To render a def inside a Mako template, given a :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can configure the template as a :term:`renderer` like so: -- cgit v1.2.3 From 49d634bd813e63c3db5e56d29376126c2646182a Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Mon, 12 Aug 2013 19:29:23 -0400 Subject: All wrapped up, pre-merge. --- docs/narr/templates.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index f1e1634b8..a70398c80 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -616,6 +616,8 @@ extension so that these ``svn:ignore`` patterns work. .. index:: pair: debugging; templates +.. _debugging_templates: + Debugging Templates ------------------- -- cgit v1.2.3 From a50494f22bc0e4ee1e2546a192e5a60b0ff46aa3 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 5 Sep 2013 22:46:40 -0500 Subject: remove chameleon and mako template-specific documentation --- docs/narr/templates.rst | 337 +----------------------------------------------- 1 file changed, 1 insertion(+), 336 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 26bb6b6cd..24973f253 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -8,10 +8,6 @@ dynamic data provided by a :term:`view`. :app:`Pyramid` offers a number of ways to perform templating tasks out of the box, and 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. - Before discussing how built-in templates are used in detail, we'll discuss two ways to render templates within :app:`Pyramid` in general: directly, and via renderer @@ -32,7 +28,7 @@ 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 named +: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: @@ -383,236 +379,6 @@ The same set of system values are provided to templates rendered via a renderer view configuration as those provided to templates rendered imperatively. See :ref:`renderer_system_values`. - -.. index:: - single: Chameleon ZPT templates - single: ZPT templates (Chameleon) - -.. _chameleon_zpt_templates: - -:term:`Chameleon` ZPT Templates -------------------------------- - -Like :term:`Zope`, :app:`Pyramid` uses :term:`ZPT` (Zope Page -Templates) as its default templating language. However, -:app:`Pyramid` uses a different implementation of the :term:`ZPT` -specification than Zope does: the :term:`Chameleon` templating -engine. The Chameleon engine complies largely with the `Zope Page -Template `_ template -specification. However, it is significantly faster. - -The language definition documentation for Chameleon ZPT-style -templates is available from `the Chameleon website -`_. - -Given a :term:`Chameleon` ZPT template named ``foo.pt`` in a directory -in your application named ``templates``, you can render the template as -a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='templates/foo.pt') - def my_view(request): - return {'foo':1, 'bar':2} - -See also :ref:`built_in_renderers` for more general information about -renderers, including Chameleon ZPT renderers. - -.. index:: - single: ZPT template (sample) - -A Sample ZPT Template -~~~~~~~~~~~~~~~~~~~~~ - -Here's what a simple :term:`Chameleon` ZPT template used under -:app:`Pyramid` might look like: - -.. code-block:: xml - :linenos: - - - - - - ${project} Application - - -

Welcome to `${project}`, an - application generated by the pyramid web - application framework.

- - - -Note the use of :term:`Genshi` -style ``${replacements}`` above. This -is one of the ways that :term:`Chameleon` ZPT differs from standard -ZPT. The above template expects to find a ``project`` key in the set -of keywords passed in to it via :func:`~pyramid.renderers.render` or -:func:`~pyramid.renderers.render_to_response`. Typical ZPT -attribute-based syntax (e.g. ``tal:content`` and ``tal:replace``) also -works in these templates. - -.. index:: - single: ZPT macros - single: Chameleon ZPT macros - -Using ZPT Macros in :app:`Pyramid` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When a :term:`renderer` is used to render a template, :app:`Pyramid` makes at -least two top-level names available to the template by default: ``context`` -and ``request``. One of the common needs in ZPT-based templates is to use -one template's "macros" from within a different template. In Zope, this is -typically handled by retrieving the template from the ``context``. But the -context in :app:`Pyramid` is a :term:`resource` object, and templates cannot -usually be retrieved from resources. To use macros in :app:`Pyramid`, you -need to make the macro template itself available to the rendered template by -passing the macro template, or even the macro itself, *into* the rendered -template. To do this you can use the :func:`pyramid.renderers.get_renderer` -API to retrieve the macro template, and pass it into the template being -rendered via the dictionary returned by the view. For example, using a -:term:`view configuration` via a :class:`~pyramid.view.view_config` decorator -that uses a :term:`renderer`: - -.. code-block:: python - :linenos: - - from pyramid.renderers import get_renderer - from pyramid.view import view_config - - @view_config(renderer='templates/mytemplate.pt') - def my_view(request): - main = get_renderer('templates/master.pt').implementation() - return {'main':main} - -Where ``templates/master.pt`` might look like so: - -.. code-block:: xml - :linenos: - - - -

- Hello Fred! -

- - - -And ``templates/mytemplate.pt`` might look like so: - -.. code-block:: xml - :linenos: - - - - Chris - - - - -Using A Chameleon Macro Name Within a Renderer Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -At times, you may want to render a macro inside of a Chameleon ZPT template -instead of the full Chameleon ZPT template. To render the content of a -``define-macro`` field inside a Chameleon ZPT template, given a Chameleon -template file named ``foo.pt`` and a macro named ``bar`` defined within it -(e.g. ``

...

``), you can configure the -template as a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='foo#bar.pt') - def my_view(request): - return {'project':'my project'} - -The above will render only the ``bar`` macro defined within the ``foo.pt`` -template instead of the entire template. - -.. versionadded:: 1.4 - -.. index:: - single: Chameleon text templates - -.. _chameleon_text_templates: - -Templating with :term:`Chameleon` Text Templates ------------------------------------------------- - -:app:`Pyramid` also allows for the use of templates which are -composed entirely of non-XML text via :term:`Chameleon`. To do so, -you can create templates that are entirely composed of text except for -``${name}`` -style substitution points. - -Here's an example usage of a Chameleon text template. Create a file -on disk named ``mytemplate.txt`` in your project's ``templates`` -directory with the following contents: - -.. code-block:: text - - Hello, ${name}! - -Then in your project's ``views.py`` module, you can create a view -which renders this template: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='templates/mytemplate.txt') - def my_view(request): - return {'name':'world'} - -When the template is rendered, it will show: - -.. code-block:: text - - Hello, world! - -See also :ref:`built_in_renderers` for more general information about -renderers, including Chameleon text renderers. - -.. index:: - single: template renderer side effects - -Side Effects of Rendering a Chameleon Template ----------------------------------------------- - -When a Chameleon template is rendered from a file, the templating -engine writes a file in the same directory as the template file itself -as a kind of cache, in order to do less work the next time the -template needs to be read from disk. If you see "strange" ``.py`` -files showing up in your ``templates`` directory (or otherwise -directly "next" to your templates), it is due to this feature. - -If you're using a version control system such as Subversion, you -should configure it to ignore these files. Here's the contents of the -author's ``svn propedit svn:ignore .`` in each of my ``templates`` -directories. - -.. code-block:: text - - *.pt.py - *.txt.py - -Note that I always name my Chameleon ZPT template files with a ``.pt`` -extension and my Chameleon text template files with a ``.txt`` -extension so that these ``svn:ignore`` patterns work. - .. index:: pair: debugging; templates @@ -643,107 +409,6 @@ undefined variable (e.g. ``${wrong}``) might end up looking like this: The output tells you which template the error occurred in, as well as displaying the arguments passed to the template itself. -.. index:: - single: template internationalization - single: internationalization (of templates) - -:term:`Chameleon` Template Internationalization ------------------------------------------------ - -See :ref:`chameleon_translation_strings` for information about -supporting internationalized units of text within :term:`Chameleon` -templates. - -.. index:: - single: Mako - -.. _mako_templates: - -Templating With Mako Templates ------------------------------- - -:term:`Mako` is a templating system written by Mike Bayer. :app:`Pyramid` -has built-in bindings for the Mako templating system. The language -definition documentation for Mako templates is available from `the Mako -website `_. - -To use a Mako template, given a :term:`Mako` template file named ``foo.mak`` -in the ``templates`` subdirectory in your application package named -``mypackage``, you can configure the template as a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='foo.mak') - def my_view(request): - return {'project':'my project'} - -For the above view callable to work, the following setting needs to be -present in the application stanza of your configuration's ``ini`` file: - -.. code-block:: ini - - mako.directories = mypackage:templates - -This lets the Mako templating system know that it should look for templates -in the ``templates`` subdirectory of the ``mypackage`` Python package. See -:ref:`mako_template_renderer_settings` for more information about the -``mako.directories`` setting and other Mako-related settings that can be -placed into the application's ``ini`` file. - -.. index:: - single: Mako template (sample) - -A Sample Mako Template -~~~~~~~~~~~~~~~~~~~~~~ - -Here's what a simple :term:`Mako` template used under :app:`Pyramid` might -look like: - -.. code-block:: xml - :linenos: - - - - ${project} Application - - -

Welcome to `${project}`, an - application generated by the pyramid web framework.

- - - -This template doesn't use any advanced features of Mako, only the -``${}`` replacement syntax for names that are passed in as -:term:`renderer globals`. See the `the Mako documentation -`_ to use more advanced features. - -Using A Mako def name Within a Renderer Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes you'd like to render a ``def`` inside of a Mako template instead of -the full Mako template. To render a def inside a Mako template, given a -:term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can -configure the template as a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='foo#bar.mak') - def my_view(request): - return {'project':'my project'} - -The above will render the ``bar`` def from within the ``foo.mak`` template -instead of the entire template. - -.. versionadded:: 1.4 - .. index:: single: automatic reloading of templates single: template automatic reload -- cgit v1.2.3 From 7a60e44961309f5453fba84c7f606af6b19ab096 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 5 Sep 2013 22:57:37 -0500 Subject: whitespace fixes --- docs/narr/templates.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 24973f253..46d836813 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -318,7 +318,9 @@ template renderer: def my_view(request): return {'foo':1, 'bar':2} -.. note:: You do not need 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. :app:`Pyramid` automatically supplies this value for you so that the "most correct" system values are provided to @@ -424,9 +426,11 @@ appear immediately without needing to restart the application process. environment so that a change to a template will be automatically detected, and the template will be reloaded on the next rendering. -.. warning:: Auto-template-reload behavior is not recommended for - production sites as it slows rendering slightly; it's - usually only desirable during development. +.. warning:: + + Auto-template-reload behavior is not recommended for + production sites as it slows rendering slightly; it's + usually only desirable during development. In order to turn on automatic reloading of templates, you can use an environment variable, or a configuration file setting. @@ -437,18 +441,18 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini + $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.reload_templates`` key to ``true`` within the application's configuration section, e.g.: .. code-block:: ini - :linenos: + :linenos: - [app:main] - use = egg:MyProject - pyramid.reload_templates = true + [app:main] + use = egg:MyProject + pyramid.reload_templates = true .. index:: single: template system bindings -- cgit v1.2.3 From b9ce00bee0b6f1f5b0174960f2087a418c1488a7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 5 Sep 2013 22:57:46 -0500 Subject: move templating bindings back into the templating chapter --- docs/narr/templates.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 46d836813..af8f9150a 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -456,16 +456,33 @@ application's configuration section, e.g.: .. index:: single: template system bindings + single: Chameleon single: Jinja2 + single: Mako .. _available_template_system_bindings: Available Add-On Template System Bindings ----------------------------------------- -Jinja2 template bindings are available for :app:`Pyramid` in the -``pyramid_jinja2`` package. You can get the latest release of -this package from the -`Python package index `_ -(pypi). +The Pylons Project maintains several packages providing bindings to different +templating languages including the following: ++------------------------------+------------------------------+ +| Template Language | Pyramid Bindings | ++==============================+==============================+ +| Chameleon_ | pyramid_chameleon_ | ++------------------------------+------------------------------+ +| Jinja2_ | pyramid_jinja2_ | ++------------------------------+------------------------------+ +| Mako_ | pyramid_mako_ | ++------------------------------+------------------------------+ + +.. _Chameleon: http://chameleon.readthedocs.org/en/latest/ +.. _pyramid_chameleon: https://pypi.python.org/pypi/pyramid_chameleon + +.. _Jinja2: http://jinja.pocoo.org/docs/ +.. _pyramid_jinja2: https://pypi.python.org/pypi/pyramid_jinja2 + +.. _Mako: http://www.makotemplates.org/ +.. _pyramid_mako: https://pypi.python.org/pypi/pyramid_mako -- cgit v1.2.3 From f1aaf1577dfeb9e094a5a9d7130984b95531d5cb Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 5 Sep 2013 23:40:27 -0500 Subject: remove some more mako/chameleon references --- docs/narr/templates.rst | 50 ++++++++++++++----------------------------------- 1 file changed, 14 insertions(+), 36 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index af8f9150a..3e19f7198 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -56,19 +56,8 @@ 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 -prefix on Windows. - -.. warning:: - - 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:`asset specification` in the form +prefix on Windows. The path can alternately be a +:term:`asset specification` in the form ``some.dotted.package_name:relative/path``. This makes it possible to address template assets which live in another package. For example: @@ -86,16 +75,9 @@ An asset specification points at a file within a Python *package*. In this case, it points at a file named ``foo.pt`` within the ``templates`` directory of the ``mypackage`` package. Using a asset specification instead of a relative template name is usually -a good idea, because calls to ``render_to_response`` using asset -specifications will continue to work properly if you move the code -containing them around. - -.. note:: - - Mako templating system bindings also respect absolute asset - specifications as an argument to any of the ``render*`` commands. If a - template name defines a ``:`` (colon) character and is not an absolute - path, it is treated as an absolute asset specification. +a good idea, because calls to :func:`~pyramid.renderers.render_to_response` +using asset specifications will continue to work properly if you move the +code containing them around. In the examples above we pass in a keyword argument named ``request`` representing the current :app:`Pyramid` request. Passing a request @@ -143,8 +125,8 @@ import its API functions into your views module, use those APIs to generate a string, then return that string as the body of a :app:`Pyramid` :term:`Response` object. -For example, here's an example of using "raw" `Mako -`_ from within a :app:`Pyramid` :term:`view`: +For example, here's an example of using "raw" Mako_ from within a +:app:`Pyramid` :term:`view`: .. code-block:: python :linenos: @@ -159,10 +141,10 @@ For example, here's an example of using "raw" `Mako return response You probably wouldn't use this particular snippet in a project, because it's -easier to use the Mako renderer bindings which already exist in -:app:`Pyramid`. But if your favorite templating system is not supported as a -renderer extension for :app:`Pyramid`, you can create your own simple -combination as shown above. +easier to use the supported +:ref:`Mako bindings `. But if your +favorite templating system is not supported as a renderer extension for +:app:`Pyramid`, you can create your own simple combination as shown above. .. note:: @@ -277,8 +259,8 @@ 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 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. +renderer itself, but most template renderers make these names available as +top-level template variables. .. index:: pair: renderer; templates @@ -348,11 +330,7 @@ it possible to address template assets which live in another package. Not just any template from any arbitrary templating system may be used as a renderer. Bindings must exist specifically for :app:`Pyramid` to use a -templating language template as a renderer. Currently, :app:`Pyramid` has -built-in support for two Chameleon templating languages: ZPT and text, and -the Mako templating system. See :ref:`built_in_renderers` for a discussion -of their details. :app:`Pyramid` also supports the use of :term:`Jinja2` -templates as renderers. See :ref:`available_template_system_bindings`. +templating language template as a renderer. .. sidebar:: Why Use A Renderer via View Configuration -- cgit v1.2.3 From 3687465ab87b82b83b7ffa2f216425136d71ebec Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 30 Dec 2013 02:49:18 -0800 Subject: grammar fixes --- docs/narr/templates.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 3e19f7198..00fc21634 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -38,8 +38,8 @@ within the body of a view callable like so: from pyramid.renderers import render_to_response def sample_view(request): - return render_to_response('templates/foo.pt', - {'foo':1, 'bar':2}, + return render_to_response('templates/foo.pt', + {'foo':1, 'bar':2}, request=request) The ``sample_view`` :term:`view callable` function above returns a @@ -56,7 +56,7 @@ 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 -prefix on Windows. The path can alternately be a +prefix on Windows. The path can alternately be an :term:`asset specification` in the form ``some.dotted.package_name:relative/path``. This makes it possible to address template assets which live in another package. For example: @@ -73,11 +73,11 @@ address template assets which live in another package. For example: An asset specification points at a file within a Python *package*. In this case, it points at a file named ``foo.pt`` within the -``templates`` directory of the ``mypackage`` package. Using a +``templates`` directory of the ``mypackage`` package. Using an asset specification instead of a relative template name is usually a good idea, because calls to :func:`~pyramid.renderers.render_to_response` using asset specifications will continue to work properly if you move the -code containing them around. +code containing them to another location. In the examples above we pass in a keyword argument named ``request`` representing the current :app:`Pyramid` request. Passing a request @@ -94,8 +94,8 @@ 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. This allows the example view above to simply return the result -of its call to ``render_to_response()`` directly. +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 response data will return a response object. For example, you might render one or more templates to @@ -111,8 +111,8 @@ as the body of the response: from pyramid.response import Response def sample_view(request): - result = render('mypackage:templates/foo.pt', - {'foo':1, 'bar':2}, + result = render('mypackage:templates/foo.pt', + {'foo':1, 'bar':2}, request=request) response = Response(result) return response @@ -194,7 +194,7 @@ of :func:`~pyramid.renderers.render` (a string): def sample_view(request): result = render('mypackage:templates/foo.pt', - {'foo':1, 'bar':2}, + {'foo':1, 'bar':2}, request=request) response = Response(result) response.content_type = 'text/plain' @@ -241,7 +241,7 @@ These values are provided to the template: The renderer name used to perform the rendering, e.g. ``mypackage:templates/foo.pt``. -``renderer_info`` +``renderer_info`` An object implementing the :class:`pyramid.interfaces.IRendererInfo` interface. Basically, an object with the following attributes: ``name``, ``package`` and ``type``. @@ -273,7 +273,7 @@ Templates Used as Renderers via 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 +*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 -- cgit v1.2.3 From 2033eeb3602f330930585678aac926749b9c22f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 10 Feb 2014 03:22:33 -0600 Subject: - Garden PR #1121 --- docs/narr/templates.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 00fc21634..038dd2594 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -320,7 +320,11 @@ template renderer: in Chameleon, not in Mako templates. Similar renderer configuration can be done imperatively. See -:ref:`views_which_use_a_renderer`. See also :ref:`built_in_renderers`. +:ref:`views_which_use_a_renderer`. + +.. seealso:: + + See also :ref:`built_in_renderers`. 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 -- cgit v1.2.3 From 739fbc26639a06900a8638d0e5de7441e41ff810 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 16 May 2014 10:32:42 -0500 Subject: Docs: narr/templates.rst: Doc default extensions of each template system. --- docs/narr/templates.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 038dd2594..cd13afde8 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -450,15 +450,15 @@ Available Add-On Template System Bindings The Pylons Project maintains several packages providing bindings to different templating languages including the following: -+------------------------------+------------------------------+ -| Template Language | Pyramid Bindings | -+==============================+==============================+ -| Chameleon_ | pyramid_chameleon_ | -+------------------------------+------------------------------+ -| Jinja2_ | pyramid_jinja2_ | -+------------------------------+------------------------------+ -| Mako_ | pyramid_mako_ | -+------------------------------+------------------------------+ ++---------------------------+----------------------------+--------------------+ +| Template Language | Pyramid Bindings | Default Extensions | ++===========================+============================+====================+ +| Chameleon_ | pyramid_chameleon_ | .pt, .txt | ++---------------------------+----------------------------+--------------------+ +| Jinja2_ | pyramid_jinja2_ | .jinja2 | ++---------------------------+----------------------------+--------------------+ +| Mako_ | pyramid_mako_ | .mak, .mako | ++---------------------------+----------------------------+--------------------+ .. _Chameleon: http://chameleon.readthedocs.org/en/latest/ .. _pyramid_chameleon: https://pypi.python.org/pypi/pyramid_chameleon -- cgit v1.2.3 From e858454e9cc375a633bfb7b39bdd4391f79e2531 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 16 May 2014 17:18:00 -0500 Subject: Docs: narr/templates.rst: Link template bindings to pyramid docs. --- docs/narr/templates.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index cd13afde8..460cda8ee 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -461,10 +461,13 @@ templating languages including the following: +---------------------------+----------------------------+--------------------+ .. _Chameleon: http://chameleon.readthedocs.org/en/latest/ -.. _pyramid_chameleon: https://pypi.python.org/pypi/pyramid_chameleon +.. _pyramid_chameleon: + http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/ .. _Jinja2: http://jinja.pocoo.org/docs/ -.. _pyramid_jinja2: https://pypi.python.org/pypi/pyramid_jinja2 +.. _pyramid_jinja2: + http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/ .. _Mako: http://www.makotemplates.org/ -.. _pyramid_mako: https://pypi.python.org/pypi/pyramid_mako +.. _pyramid_mako: + http://docs.pylonsproject.org/projects/pyramid-mako/en/latest/ -- cgit v1.2.3 From 7a479d270d654f61fca00f8a27b64fd2bf99d35d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 13 Jul 2014 23:39:38 -0400 Subject: remove lie --- docs/narr/templates.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 460cda8ee..4c1364493 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -316,8 +316,7 @@ template renderer: we're using a Chameleon renderer, it means "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 defines the ``my_view`` - function. View-configuration-relative asset specifications work only - in Chameleon, not in Mako templates. + function. Similar renderer configuration can be done imperatively. See :ref:`views_which_use_a_renderer`. -- cgit v1.2.3 From ac568b72d0f8214b169f28c5bbebb78c571c0a07 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 11 Oct 2015 01:24:08 -0700 Subject: minor grammar, wrap 79 cols --- docs/narr/templates.rst | 309 +++++++++++++++++++++++------------------------- 1 file changed, 147 insertions(+), 162 deletions(-) (limited to 'docs/narr/templates.rst') diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 4c1364493..9e3a31845 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -3,15 +3,14 @@ Templates ========= -A :term:`template` is a file on disk which can be used to render -dynamic data provided by a :term:`view`. :app:`Pyramid` offers a -number of ways to perform templating tasks out of the box, and -provides add-on templating support through a set of bindings packages. +A :term:`template` is a file on disk which can be used to render dynamic data +provided by a :term:`view`. :app:`Pyramid` offers a number of ways to perform +templating tasks out of the box, and provides add-on templating support through +a set of bindings packages. -Before discussing how built-in templates are used in -detail, we'll discuss two ways to render templates within -:app:`Pyramid` in general: directly, and via renderer -configuration. +Before discussing how built-in templates are used in detail, we'll discuss two +ways to render templates within :app:`Pyramid` in general: directly and via +renderer configuration. .. index:: single: templates used directly @@ -21,16 +20,15 @@ configuration. 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. +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 named -``templates`` in your application, you can render the template from -within the body of a view callable like 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 named ``templates`` in your +application, you can render the template from within the body of a view +callable like so: .. code-block:: python :linenos: @@ -43,23 +41,21 @@ within the body of a view callable like so: request=request) 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 -the ``sample_view`` function. The template author will have the names -``foo`` and ``bar`` available as top-level names for replacement or -comparison purposes. +: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 the ``sample_view`` function. The template +author will have the names ``foo`` and ``bar`` available as top-level names for +replacement or comparison purposes. In the example above, the path ``templates/foo.pt`` is relative to the -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 -prefix on Windows. The path can alternately be an -:term:`asset specification` in the form -``some.dotted.package_name:relative/path``. This makes it possible to -address template assets which live in another package. For example: +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 prefix on Windows. The path can alternatively +be an :term:`asset specification` in the form +``some.dotted.package_name:relative/path``. This makes it possible to address +template assets which live in another package. For example: .. code-block:: python :linenos: @@ -71,38 +67,36 @@ address template assets which live in another package. For example: {'foo':1, 'bar':2}, request=request) -An asset specification points at a file within a Python *package*. -In this case, it points at a file named ``foo.pt`` within the -``templates`` directory of the ``mypackage`` package. Using an -asset specification instead of a relative template name is usually -a good idea, because calls to :func:`~pyramid.renderers.render_to_response` -using asset specifications will continue to work properly if you move the -code containing them to another location. +An asset specification points at a file within a Python *package*. In this +case, it points at a file named ``foo.pt`` within the ``templates`` directory +of the ``mypackage`` package. Using an asset specification instead of a +relative template name is usually a good idea, because calls to +:func:`~pyramid.renderers.render_to_response` using asset specifications will +continue to work properly if you move the code containing them to another +location. 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 your -template relies on the name ``request`` or ``context``, or if you've -configured special :term:`renderer globals`, make sure to pass +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 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 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. This allows the example view above to simply return the result -of its call to ``render_to_response()`` directly. +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. 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 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: +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: @@ -119,10 +113,10 @@ as the body of the response: Because :term:`view callable` functions are typically the only code in :app:`Pyramid` that need to know anything about templates, and because view -functions are very simple Python, you can use whatever templating system you're -most comfortable with within :app:`Pyramid`. Install the templating system, -import its API functions into your views module, use those APIs to generate a -string, then return that string as the body of a :app:`Pyramid` +functions are very simple Python, you can use whatever templating system with +which you're most comfortable within :app:`Pyramid`. Install the templating +system, import its API functions into your views module, use those APIs to +generate a string, then return that string as the body of a :app:`Pyramid` :term:`Response` object. For example, here's an example of using "raw" Mako_ from within a @@ -141,34 +135,32 @@ For example, here's an example of using "raw" Mako_ from within a return response You probably wouldn't use this particular snippet in a project, because it's -easier to use the supported -:ref:`Mako bindings `. But if your -favorite templating system is not supported as a renderer extension for -:app:`Pyramid`, you can create your own simple combination as shown above. +easier to use the supported :ref:`Mako bindings +`. But if your favorite templating system +is not supported as a renderer extension for :app:`Pyramid`, you can create +your own simple combination as shown above. .. note:: If you use third-party templating languages without cooperating :app:`Pyramid` bindings directly within view callables, the - auto-template-reload strategy explained in - :ref:`reload_templates_section` will not be available, nor will the - template asset overriding capability explained in - :ref:`overriding_assets_section` be available, nor will it be - possible to use any template using that language as a - :term:`renderer`. However, it's reasonably easy to write custom - templating system binding packages for use under :app:`Pyramid` so - that templates written in the language can be used as renderers. - See :ref:`adding_and_overriding_renderers` for instructions on how - to create your own template renderer and - :ref:`available_template_system_bindings` for example packages. - -If you need more control over the status code and content-type, or -other response attributes from views that use direct templating, you -may set attributes on the response that influence these values. - -Here's an example of changing the content-type and status of the -response object returned by -:func:`~pyramid.renderers.render_to_response`: + auto-template-reload strategy explained in :ref:`reload_templates_section` + will not be available, nor will the template asset overriding capability + explained in :ref:`overriding_assets_section` be available, nor will it be + possible to use any template using that language as a :term:`renderer`. + However, it's reasonably easy to write custom templating system binding + packages for use under :app:`Pyramid` so that templates written in the + language can be used as renderers. See + :ref:`adding_and_overriding_renderers` for instructions on how to create + your own template renderer and :ref:`available_template_system_bindings` + for example packages. + +If you need more control over the status code and content-type, or other +response attributes from views that use direct templating, you may set +attributes on the response that influence these values. + +Here's an example of changing the content-type and status of the response +object returned by :func:`~pyramid.renderers.render_to_response`: .. code-block:: python :linenos: @@ -183,8 +175,8 @@ response object returned by response.status_int = 204 return response -Here's an example of manufacturing a response object using the result -of :func:`~pyramid.renderers.render` (a string): +Here's an example of manufacturing a response object using the result of +:func:`~pyramid.renderers.render` (a string): .. code-block:: python :linenos: @@ -214,9 +206,8 @@ of :func:`~pyramid.renderers.render` (a string): System Values Used During Rendering ----------------------------------- -When a template is rendered using -:func:`~pyramid.renderers.render_to_response` or -:func:`~pyramid.renderers.render`, or a ``renderer=`` argument to view +When a template is rendered using :func:`~pyramid.renderers.render_to_response` +or :func:`~pyramid.renderers.render`, or a ``renderer=`` argument to view configuration (see :ref:`templates_used_as_renderers`), the renderer representing the template will be provided with a number of *system* values. These values are provided to the template: @@ -232,31 +223,31 @@ These values are provided to the template: ``context`` The current :app:`Pyramid` :term:`context` if ``request`` was provided as a - keyword argument to ``render_to_response`` or ``render``, or ``None`` if - the ``request`` keyword argument was not provided. This value will always - be provided if the template is rendered as the result of a ``renderer=`` - argument to view configuration being used. + keyword argument to ``render_to_response`` or ``render``, or ``None`` if the + ``request`` keyword argument was not provided. This value will always be + provided if the template is rendered as the result of a ``renderer=`` + argument to the view configuration being used. ``renderer_name`` - The renderer name used to perform the rendering, - e.g. ``mypackage:templates/foo.pt``. + 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``. + ``package``, and ``type``. ``view`` - The view callable object that was used to render this template. If the - view callable is a method of a class-based view, this will be an instance - of the class that the method was defined on. If the view callable is a - function or instance, it will be that function or instance. Note that this - value will only be automatically present when a template is rendered as a - result of a ``renderer=`` argument; it will be ``None`` when the - ``render_to_response`` or ``render`` APIs are used. + The view callable object that was used to render this template. If the view + callable is a method of a class-based view, this will be an instance of the + class that the method was defined on. If the view callable is a function or + instance, it will be that function or instance. Note that this value will + only be automatically present when a template is rendered as a result of a + ``renderer=`` argument; it will be ``None`` when the ``render_to_response`` + or ``render`` APIs are used. -You can define more values which will be passed to every template executed as -a result of rendering by defining :term:`renderer globals`. +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 these system values is up to the renderer itself, but most template renderers make these names available as @@ -270,26 +261,23 @@ top-level template variables. Templates Used as Renderers via 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 +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:`asset 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 -to the renderer template as top-level names. +To use a renderer via view configuration, specify a template :term:`asset +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 to the renderer template as top-level names. -The association of a template as a renderer for a :term:`view -configuration` makes it possible to replace code within a :term:`view -callable` that handles the rendering of a template. +The association of a template as a renderer for a :term:`view configuration` +makes it possible to replace code within a :term:`view callable` that handles +the rendering of a template. -Here's an example of using a :class:`~pyramid.view.view_config` -decorator to specify a :term:`view configuration` that names a -template renderer: +Here's an example of using a :class:`~pyramid.view.view_config` decorator to +specify a :term:`view configuration` that names a template renderer: .. code-block:: python :linenos: @@ -302,11 +290,10 @@ template renderer: .. note:: - You do not need to supply the ``request`` value as a key - in the dictionary result returned from a renderer-configured view - callable. :app:`Pyramid` automatically supplies this value for - you so that the "most correct" system values are provided to - the renderer. + You do not need to supply the ``request`` value as a key in the dictionary + result returned from a renderer-configured view callable. :app:`Pyramid` + automatically supplies this value for you, so that the "most correct" system + values are provided to the renderer. .. warning:: @@ -314,7 +301,7 @@ template renderer: shown above is the template *path*. In the example above, the path ``templates/foo.pt`` is *relative*. Relative to what, you ask? Because we're using a Chameleon renderer, it means "relative to the directory in - which the file which defines the view configuration lives". In this case, + which the file that defines the view configuration lives". In this case, this is the directory containing the file that defines the ``my_view`` function. @@ -327,7 +314,7 @@ Similar renderer configuration can be done imperatively. See 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 prefix on Windows. The path can alternately be an :term:`asset +letter prefix on Windows. The path can alternatively be an :term:`asset specification` in the form ``some.dotted.package_name:relative/path``, making it possible to address template assets which live in another package. @@ -335,32 +322,31 @@ Not just any template from any arbitrary templating system may be used as a renderer. Bindings must exist specifically for :app:`Pyramid` to use a templating language template as a renderer. -.. sidebar:: Why Use A Renderer via View Configuration - - Using a renderer in view configuration is usually a better way to - render templates than using any rendering API directly from within a - :term:`view callable` because it makes the view callable more - unit-testable. Views which use templating or rendering APIs directly - must return a :term:`Response` object. Making testing assertions - about response objects is typically an indirect process, because it - means that your test code often needs to somehow parse information - out of the response body (often HTML). View callables configured - with renderers externally via view configuration typically return a - dictionary, as above. Making assertions about results returned in a - dictionary is almost always more direct and straightforward than - needing to parse HTML. +.. sidebar:: Why Use a Renderer via View Configuration + + Using a renderer in view configuration is usually a better way to render + templates than using any rendering API directly from within a :term:`view + callable` because it makes the view callable more unit-testable. Views + which use templating or rendering APIs directly must return a + :term:`Response` object. Making testing assertions about response objects + is typically an indirect process, because it means that your test code often + needs to somehow parse information out of the response body (often HTML). + View callables configured with renderers externally via view configuration + typically return a dictionary, as above. Making assertions about results + returned in a dictionary is almost always more direct and straightforward + than needing to parse HTML. By default, views rendered via a template renderer return a :term:`Response` object which has a *status code* of ``200 OK``, and a *content-type* of ``text/html``. To vary attributes of the response of a view that uses a -renderer, such as the content-type, headers, or status attributes, you must -use the API of the :class:`pyramid.response.Response` object exposed as +renderer, such as the content-type, headers, or status attributes, you must use +the API of the :class:`pyramid.response.Response` object exposed as ``request.response`` within the view before returning the dictionary. See :ref:`request_response_attr` for more information. -The same set of system values are provided to templates rendered via a -renderer view configuration as those provided to templates rendered -imperatively. See :ref:`renderer_system_values`. +The same set of system values are provided to templates rendered via a renderer +view configuration as those provided to templates rendered imperatively. See +:ref:`renderer_system_values`. .. index:: pair: debugging; templates @@ -401,32 +387,31 @@ displaying the arguments passed to the template itself. Automatically Reloading Templates --------------------------------- -It's often convenient to see changes you make to a template file -appear immediately without needing to restart the application process. -:app:`Pyramid` allows you to configure your application development -environment so that a change to a template will be automatically -detected, and the template will be reloaded on the next rendering. +It's often convenient to see changes you make to a template file appear +immediately without needing to restart the application process. :app:`Pyramid` +allows you to configure your application development environment so that a +change to a template will be automatically detected, and the template will be +reloaded on the next rendering. .. warning:: - Auto-template-reload behavior is not recommended for - production sites as it slows rendering slightly; it's - usually only desirable during development. + Auto-template-reload behavior is not recommended for production sites as it + slows rendering slightly; it's usually only desirable during development. In order to turn on automatic reloading of templates, you can use an -environment variable, or a configuration file setting. +environment variable or a configuration file setting. -To use an environment variable, start your application under a shell -using the ``PYRAMID_RELOAD_TEMPLATES`` operating system environment -variable set to ``1``, For example: +To use an environment variable, start your application under a shell using the +``PYRAMID_RELOAD_TEMPLATES`` operating system environment variable set to +``1``, For example: .. code-block:: text $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini -To use a setting in the application ``.ini`` file for the same -purpose, set the ``pyramid.reload_templates`` key to ``true`` within the -application's configuration section, e.g.: +To use a setting in the application ``.ini`` file for the same purpose, set the +``pyramid.reload_templates`` key to ``true`` within the application's +configuration section, e.g.: .. code-block:: ini :linenos: -- cgit v1.2.3

Welcome to ${project}, an application generated by the pyramid web application framework.

Welcome to ${project}, an application generated by the pyramid web application framework.

Welcome to ${project}, an application generated by the pyramid web application framework.

Welcome to ${project}, an - application generated by the pyramid web - application framework.

- Hello Fred! -

Welcome to ${project}, an - application generated by the pyramid web framework.

Welcome to `${project}`, an application generated by the pyramid web application framework.

Welcome to `${project}`, an application generated by the pyramid web application framework.

Welcome to `${project}`, an application generated by the pyramid web application framework.

Welcome to `${project}`, an - application generated by the pyramid web - application framework.

Welcome to `${project}`, an - application generated by the pyramid web framework.