Permalink
Browse files

Templates chapter and more examples.

  • Loading branch information...
1 parent 752f278 commit 870ce4ed9dcce695e4b3824e34d98e6dd387feab @mikeorr mikeorr committed May 31, 2012
Showing with 181 additions and 0 deletions.
  1. +9 −0 pylons/examples.rst
  2. +1 −0 pylons/index.rst
  3. +166 −0 pylons/templates.rst
  4. +5 −0 pylons/views.rst
View
@@ -78,6 +78,15 @@ Here are the most common kinds of routes and views.
The 'pyramid_handlers' package provides an alternative for this.
+Other Pyramid examples::
+
+ # Home route.
+ config.add_route("home", "/")
+
+ # Multi-action route, excluding certain static URLs.
+ config.add_route("main", "/{action}",
+ path_info=r"/(?!favicon\.ico|robots\.txt|w3c)")
+
pyramid_handlers
View
@@ -32,6 +32,7 @@ skim through the rest of the manual to see which sections cover which topics.
views
examples
request
+ templates
exceptions
sessions
migrate
View
@@ -0,0 +1,166 @@
+Templates
++++++++++
+
+Pyramid includes adapters for two template engines, Mako and Chameleon. Mako is
+Pylons' default engine so it will be familiar. Third-party adapters are
+available for other engines: "pyramid_jinja2" (a Jinja2 adapter),
+"pyramid_chameleon_gensi" (a partial Genshi emulator), etc.
+
+Mako configuration
+==================
+
+In order to use Mako as in Pylons, you must specify a template search path
+in the settings:
+
+.. code-block:: ini
+
+ [app:main]
+ ...
+ mako.directories = pyramidapp:templates
+
+This enables relative template paths like ``renderer="/mytemplate.mak"`` and
+quasi-URL paths like ``renderer="/mytemplate.mak"``. It also allows templates
+to inherit from other templates, import other templates, and include other
+templates. Without this setting, the renderer arg will have to be in asset
+spec syntax, and templates won't be able to invoke other templates.
+
+All settings with the "mako." prefix are passed to Mako's ``TemplateLookup``
+constructor. E.g.,
+
+.. code-block:: ini
+
+ mako.strict_undefined = true
+ mako.imports =
+ from mypackage import myfilter
+ mako.filters = myfilter
+ mako.module_directory = %(here)s/data/templates
+ mako.preprocessor = mypackage.mako_preprocessor
+
+Template filenames ending in ".mak" or ".mako" are sent to the Mako renderer.
+If you prefer a different extension such as ".html", you can put this
+in your main function::
+
+ config.add_renderer(".html", "pyramid.mako_templating.renderer_factory")
+
+If you have further questions about exactly how the Mako renderer is
+implemented, it's best to look at the source: ``pyramid.mako_templating``. You
+can reconcile that with the Mako documentation to confirm what argument values
+cause what.
+
+*Caution:* When I set "mako.strict_undefined" to true in an application that
+didn't have Beacon sessons configured, it broke the debug toolbar. The toolbar
+templates may have some sloppy placeholders not guarded by "% if".
+
+*Caution 2:* Supposedly you can pass an asset spec instead of a template path
+but I couldn't get it to work.
+
+
+Chameleon
+=========
+
+Chameleon is an XML-based template language descended from Zope. It has some
+similarities with Genshi. Its filename extension is .pt ("page template").
+
+Advantages of Chameleon:
+
+* XML-based syntax.
+* Template must be well-formed XHTML, suggesting (but not guaranteeing) that the
+ output will be well-formed. If any variable placeholder is marked
+ "structure", it's possible to insert invalid XML into the template.
+* Good internationalization support in Pyramid.
+* Speed is as fast as Mako. (Unusual for XML template languages.)
+* Placeholder syntax "${varname or expression}" is common to Chameleon, Mako,
+ and Genshi.
+* Chameleon does have a text mode which accepts non-XML input, but you lose all
+ control structures except "${varname}".
+
+Disadvantages of Chameleon:
+
+* XML-based syntax.
+* Filenames must be in asset spec syntax, not relative paths:
+ ``renderer="mypackage:templates/foo.pt"``, ``renderer="templates/foo.pt"``.
+ You can't get rid of that "templates/" prefix without writing a wrapper
+ ``view_config`` decorator.
+* No template lookup, so you can't invoke one template from inside another
+ without pre-loading the template into a variable.
+* If template is not well-formed XML, the user will get an unconditional
+ "Internal Server Error" rather than something that might look fine in the
+ browser and which the user can at least read some content from.
+* It doesn't work on all platforms Mako and Pyramid do. (Only CPython and
+ Google App Engine.)
+
+Renderer globals
+================
+
+Whenever a renderer invokes a template, the template namespace includes all the
+variables in the view's return dict, plus the following system variables:
+
+.. attribute:: request, req
+ :noindex:
+
+ The current request.
+
+.. attribute:: view
+
+ The view instance (for class-based views) or function (for function-based
+ views). You can read instance attributes directly: ``view.foo``.
+
+.. attribute:: context
+ :noindex:
+
+ The context (same as ``request.context``). (Not visible in Mako because
+ Mako has a built-in variable with this name; use ``request.context``
+ instead.)
+
+.. attribute:: renderer_name
+ :noindex:
+
+ The fully-qualified renderer name; e.g., "zzz:templates/foo.mako".
+
+.. attribute:: renderer_info
+ :noindex:
+
+ An object with attributes ``name``, ``package``, and ``type``.
+
+
+The Akhet demo shows how to inject other variables into all templates, such as
+a helpers module ``h``, a URL generator ``url``, the session variable
+``session``, etc.
+
+
+Site template
+=============
+
+Most sites will use a site template combined with page templates to ensure
+that all the pages have the same look and feel (header, sidebars, and footer).
+Mako's inheritance makes it easy to make page templates inherit from a site
+template. Here's a very simple site template:
+
+.. code-block:: mako
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>My Application</title>
+ </head>
+ <body>
+
+ <!-- *** BEGIN page content *** -->
+ ${self.body()}
+ <!-- *** END page content ***-->
+
+ </body>
+ </html>
+
+... and a page template that uses it:
+
+.. code-block:: mako
+
+ <%inherit file="/site.html" />
+
+ <p>
+ Welcome to <strong>${project}</strong>, an application ...
+ </p>
+
+
+A more elaborate example is in the Akhet demo.
View
@@ -252,6 +252,11 @@ same. ::
def template(request):
return {}
+ @view_config(route_name="info", renderer="info.mak")
+ @view-config(route_name="info_json", renderer="json")
+ def info(request):
+ return {}
+
.. include:: ../links.rst

0 comments on commit 870ce4e

Please sign in to comment.