[svn] various updates i haven't checked in so far (see the diff of the changelog) and fixed critical bug reported by Alexey Melchakov
--HG--
branch : trunk
diff --git a/docs/generate.py b/docs/generate.py
index d6a4180..8acf5b7 100755
--- a/docs/generate.py
+++ b/docs/generate.py
@@ -246,7 +246,7 @@
data,
writer=writer,
settings_overrides={
- 'initial_header_level': 3,
+ 'initial_header_level': 2,
'field_name_limit': 50,
}
)
diff --git a/docs/src/contextenv.txt b/docs/src/contextenv.txt
index f362a64..6257d10 100644
--- a/docs/src/contextenv.txt
+++ b/docs/src/contextenv.txt
@@ -40,6 +40,12 @@
Get the translations for the template `name`. Only works if a loader
is present. See the `i18n`_ section for more details.
+**def** `get_translations_for_string` *(self, string)*:
+
+ Get the translations for the string `string`. This works also if no
+ loader is present and can be used to lookup translation strings from
+ templates that are loaded from dynamic resources like databases.
+
**def** `apply_filters` *(self, value, context, filters)*:
Now this function is a bit tricky and you usually don't have to override
@@ -57,7 +63,7 @@
unicode. The filters for the names are stored on ``self.filters`` in a
dict. Missing filters should raise a `FilterNotFound` exception.
- **Warning** this is a jinja internal method. The actual implementation
+ **Warning** this is a Jinja internal method. The actual implementation
and function signature might change.
**def** `perform_test` *(self, context, testname, args, value, invert)*:
@@ -72,7 +78,7 @@
Missing tests should raise a `TestNotFound` exception.
- **Warning** this is a jinja internal method. The actual implementation
+ **Warning** this is a Jinja internal method. The actual implementation
and function signature might change.
**def** `get_attribute` *(self, obj, attribute)*:
@@ -80,9 +86,14 @@
Get `attribute` from the object provided. The default implementation
performs security tests.
- **Warning** this is a jinja internal method. The actual implementation
+ **Warning** this is a Jinja internal method. The actual implementation
and function signature might change.
+**def** `get_attributes` *(self, obj, attributes)*:
+
+ Get some attributes from the object. If `attributes` is an empty
+ sequence the object itself is returned unchanged.
+
**def** `call_function` *(self, f, context, args, kwargs, dyn_args, dyn_kwargs)*:
Call a function `f` with the arguments `args`, `kwargs`, `dyn_args` and
@@ -92,21 +103,21 @@
The default implementation performs some security checks.
- **Warning** this is a jinja internal method. The actual implementation
+ **Warning** this is a Jinja internal method. The actual implementation
and function signature might change.
**def** `call_function_simple` *(self, f, context)*:
Like `call_function` but without arguments.
- **Warning** this is a jinja internal method. The actual implementation
+ **Warning** this is a Jinja internal method. The actual implementation
and function signature might change.
**def** `finish_var` *(self, value, ctx)*:
Postprocess a variable before it's sent to the template.
- **Warning** this is a jinja internal method. The actual implementation
+ **Warning** this is a Jinja internal method. The actual implementation
and function signature might change.
.. admonition:: Note
diff --git a/docs/src/designerdoc.txt b/docs/src/designerdoc.txt
index 2f5dcc7..dcdb5ab 100644
--- a/docs/src/designerdoc.txt
+++ b/docs/src/designerdoc.txt
@@ -922,5 +922,19 @@
one user found.
{% endif %}
+*New in Jinja 1.1*: It's now possible to use the marker name as implicit
+default:
+
+.. sourcecode:: jinja
+
+ instead of this version:
+
+ {% trans username=username %}Hello {{ username }}!{% endtrans %}
+
+ you can now write this:
+
+ {% trans username %}Hello {{ username }}!{% endtrans %}
+
+
.. _slicing chapter: http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
.. _range function: http://docs.python.org/tut/node6.html#SECTION006300000000000000000
diff --git a/docs/src/frameworks.txt b/docs/src/frameworks.txt
index 6d576db..952dd00 100644
--- a/docs/src/frameworks.txt
+++ b/docs/src/frameworks.txt
@@ -2,6 +2,119 @@
Framework Integration
=====================
-Because the buffet template interface does not support more complex usage
-cases there is currently no built in framework support. This however will
-hopefully change before the Jinja release.
+Starting with Jinja 1.1 it's possible to embed Jinja into some of the existing
+frameworks a lot easier. When speaking of frameworks we only refer to `Pylons`_
+which has a working implementation of the TurboGears template specification.
+
+Since the whole situation is problematic because of various reasons (kid
+specific, uses dotted names for template loading, package name prefix etc.)
+we worked around some of the problems by using pylons specific workarounds.
+
+Jinja also ships an implementation for a hypothetical template abstraction layer
+called `General Template Interface`_ which isn't implemented by any existing
+framework so far. This specification however tries to solve the problems that
+exist in Buffet.
+
+Buffet
+======
+
+The buffet specification proposes that templates are named in dotted names. That
+means `foo.bar` and not `foo/bar.html`. The dotted notation has the disadvantage
+that you cannot specify the filename extension. In recent pylons versions it's
+however possible to load templates with their native path too if you prefix the
+template name with a foreslash (`/foo/bar.html`). If you don't specify the
+extension it will assume `.html` for the dotted notation.
+
+Here the list of configuration values:
+
+======================= ======================================================
+``jinja.extension`` The template extension when templates are loaded using
+ the dotted notation. Defaults to ``html``.
+``jinja.environment`` If this is provided it must be the only configuration
+ value and it's used as jinja environment. In that
+ case all other configuration parameters except of
+ ``jinja.extension`` are ignored.
+``jinja.searchpath`` If provided a new file system loader with this
+ search path is instanciated.
+``jinja.package`` Name of the python package containing the
+ templates. If this and ``package_path`` is
+ defined a `PackageLoader` is used.
+``jinja.package_path`` Path to the templates inside of a package.
+``jinja.loader_func`` Function that takes the name of the template to
+ load. If it returns a string or unicode object
+ it's used to load a template. If the return
+ value is None it's considered missing.
+``jinja.getmtime_func`` Function used to check if templates requires
+ reloading. Has to return the UNIX timestamp of
+ the last template change or 0 if this template
+ does not exist or requires updates at any cost.
+``jinja.use_memcache`` Set this to ``True`` to enable memory caching.
+ This is usually a good idea in production mode,
+ but disable it during development since it won't
+ reload template changes automatically.
+ This only works in persistent environments like
+ FastCGI.
+``jinja.memcache_size`` Number of template instance you want to cache.
+ Defaults to ``40``.
+``jinja.cache_folder`` Set this to an existing directory to enable
+ caching of templates on the file system. Note
+ that this only affects templates transformed
+ into python code. Default is ``None`` which means
+ that caching is disabled.
+``jinja.auto_reload`` Set this to `False` for a slightly better
+ performance. In that case of `getmtime_func`
+ not being provided this won't have an effect.
+======================= ======================================================
+
+All other options that start with `jinja.` are automatically forwarded to the
+environment constructor.
+
+In pylons for example you can use jinja as buffet plugin like this:
+
+Edit the `yourproject/config/middleware.py` and add this to `config.init_app`:
+
+.. sourcecode:: python
+
+ config.add_template_engine('jinja', '', {
+ 'jinja.package': 'yourapplication',
+ 'jinja.package_path': 'res/templates',
+ 'jinja.use_memcache': True
+ })
+
+Note that it's a good idea to set the second parameter to an empty string.
+It's meant to be used as replacement for the turbogears package name but
+Jinja assumes that the name of the template does not include the package
+path.
+
+You can then render the template in the view like this:
+
+.. sourcecode:: python
+
+ class ExampleController(BaseController):
+
+ def index(self):
+ c.title = "Your Page"
+ c.message = 'hi'
+ return render_response('jinja', 'test_template')
+
+ def download(self):
+ c.title = "Downloads"
+ c.downloads = [1, 2, 3]
+ return render_response('jinja', '/downloads.html')
+
+With the settings from above rendering the `index` action will result in
+rendering the template ``res/templates/test_template.html`` where res is
+a folder in the ``yourapplication`` python package.
+
+The `downloads` action uses the pylons specific leading foreslash notation.
+
+General Template Interface
+==========================
+
+Because nobody implemented this specification so far it's not documented here
+but in the sourcecode of the `plugin module`_. The specification itself is
+explained on the pocoo trac on the `General Template Interface`_ wiki page.
+
+.. _Pylons: http://www.pylonshq.com/
+.. _General Template Interface: http://trac.pocoo.org/wiki/GeneralTemplateInterface
+.. _plugin module: http://trac.pocoo.org/browser/jinja/trunk/jinja/plugin.py
diff --git a/docs/src/i18n.txt b/docs/src/i18n.txt
index 18bd86f..621cc91 100644
--- a/docs/src/i18n.txt
+++ b/docs/src/i18n.txt
@@ -70,3 +70,8 @@
Because Jinja is not bound to gettext you can now use these strings to
create translation files for any translation system.
+
+*New in Jinja 1.1* You can now extract translations from strings according
+to the current envrionment settings too by using the environment method
+`get_translations_for_string` which takes a string containing a template
+as only argument. The return value is the same as for `get_translations`.
diff --git a/docs/src/index.txt b/docs/src/index.txt
index a369274..f911449 100644
--- a/docs/src/index.txt
+++ b/docs/src/index.txt
@@ -30,6 +30,8 @@
- `Internationalization <i18n.txt>`_
+ - `Alternative Syntax <altsyntax.txt>`_
+
- `Developer Recipies <devrecipies.txt>`_
- Template Designer Documentation: