diff options
| -rw-r--r-- | doc/build/content/runtime.txt | 4 | ||||
| -rw-r--r-- | doc/build/content/usage.txt | 4 |
2 files changed, 4 insertions, 4 deletions
diff --git a/doc/build/content/runtime.txt b/doc/build/content/runtime.txt index 626dd32..61cfa5f 100644 --- a/doc/build/content/runtime.txt +++ b/doc/build/content/runtime.txt @@ -31,7 +31,7 @@ When your template is compiled into a Python module, the body content is enclose someval is: ${someval} % endif -Another facet of the `Context` is that its dictionary of variables is **immutable**. Whatever is set when `template.render()` is called is what stays. Of course, since its Python, you can hack around this and change values in the context's internal dictionary, but this will probably will not work as well as you'd think. The reason for this is that Mako in many cases creates copies of the `Context` object, which get sent to various elements of the template and inheriting templates used in an execution. So changing the value in your local `Context` will not necessarily make that value available in other parts of the template's execution. Examples of where Mako creates copies of the `Context` include within top-level def calls from the main body of the template (the context is used to propigate locally assigned variables into the scope of defs; since in the template's body they appear as inlined functions, Mako tries to make them act that way), and within an inheritance chain (each template in an inheritance chain has a different notion of `parent` and `next`, which are all stored in unique `Context` instances). +Another facet of the `Context` is that its dictionary of variables is **immutable**. Whatever is set when `template.render()` is called is what stays. Of course, since its Python, you can hack around this and change values in the context's internal dictionary, but this will probably will not work as well as you'd think. The reason for this is that Mako in many cases creates copies of the `Context` object, which get sent to various elements of the template and inheriting templates used in an execution. So changing the value in your local `Context` will not necessarily make that value available in other parts of the template's execution. Examples of where Mako creates copies of the `Context` include within top-level def calls from the main body of the template (the context is used to propagate locally assigned variables into the scope of defs; since in the template's body they appear as inlined functions, Mako tries to make them act that way), and within an inheritance chain (each template in an inheritance chain has a different notion of `parent` and `next`, which are all stored in unique `Context` instances). * **So what if I want to set values that are global to everyone within a template request?** - All you have to do is provide a dictionary to your `Context` when the template first runs, and everyone can just get/set variables from that. Lets say its called `attributes`. @@ -55,7 +55,7 @@ Significant members off of `Context` include: * `context[key]` / `context.get(key, default=None)` - dictionary-like accessors for the context. Normally, any variable you use in your template is automatically pulled from the context if it isnt defined somewhere already. Use the dictionary accessor and/or `get` method when you want a variable that *is* already defined somewhere else, such as in the local arguments sent to a %def call. If a key is not present, like a dictionary it raises `KeyError`. * `keys()` - all the names defined within this context. -* `kwargs` - this returns a **copy** of the context's dictionary of variables. This is useful when you want to propigate the variables in the current context to a function as keyword arguments, i.e.: +* `kwargs` - this returns a **copy** of the context's dictionary of variables. This is useful when you want to propagate the variables in the current context to a function as keyword arguments, i.e.: ${next.body(**context.kwargs)} diff --git a/doc/build/content/usage.txt b/doc/build/content/usage.txt index 1332ebe..6bb6386 100644 --- a/doc/build/content/usage.txt +++ b/doc/build/content/usage.txt @@ -160,7 +160,7 @@ The HTML render function is also available built-in to `Template` using the `for template = Template(filename="/foo/bar", format_exceptions=True) print template.render() -Note that the compile stage of the above template occurs when you construct the `Template` itself, and no output stream is defined. Therefore exceptions which occur within the lookup/parse/compile stage will not be handled and will propigate normally. While the pre-render traceback usually will not include any Mako-specific lines anyway, it will mean that exceptions which occur previous to rendering and those which occur within rendering will be handled differently...so the `try/except` patterns described previously are probably of more general use. +Note that the compile stage of the above template occurs when you construct the `Template` itself, and no output stream is defined. Therefore exceptions which occur within the lookup/parse/compile stage will not be handled and will propagate normally. While the pre-render traceback usually will not include any Mako-specific lines anyway, it will mean that exceptions which occur previous to rendering and those which occur within rendering will be handled differently...so the `try/except` patterns described previously are probably of more general use. The underlying object used by the error template functions is the `RichTraceback` object. This object can also be used directly to provide custom error views. Here's an example usage which describes its general API: @@ -190,7 +190,7 @@ The standard plugin methodology used by [Turbogears](http://www.turbogears.org) #### WSGI -A sample WSGI application is included in the distrubution in the file `examples/wsgi/run_wsgi.py`. This runner is set up to pull files from a `templates` as well as an `htdocs` directory and includes a rudimental two-file layout. The WSGI runner acts as a fully functional standalone web server, using `wsgiutils` to run itself, and propigates GET and POST arguments from the request into the `Context`, can serve images, css files and other kinds of files, and also displays errors using Mako's included exception-handling utilities. +A sample WSGI application is included in the distrubution in the file `examples/wsgi/run_wsgi.py`. This runner is set up to pull files from a `templates` as well as an `htdocs` directory and includes a rudimental two-file layout. The WSGI runner acts as a fully functional standalone web server, using `wsgiutils` to run itself, and propagates GET and POST arguments from the request into the `Context`, can serve images, css files and other kinds of files, and also displays errors using Mako's included exception-handling utilities. #### Pygments |