| ==================== |
| Developer Quickstart |
| ==================== |
| |
| This part of the documentation shows you how to embed Jinja into your |
| application. |
| |
| Starting Up |
| =========== |
| |
| Here the quickest way to create a template from a string and render it: |
| |
| .. sourcecode:: python |
| |
| from jinja import Environment |
| env = Environment() |
| tmpl = env.from_string('Hello {{ name }}!') |
| print tmpl.render(name='John Doe') |
| |
| This example should output the following string after execution:: |
| |
| Hello John Doe! |
| |
| If you receive an error, check if you have a typo in your code. If not, have |
| a look at the `installation`_ page for troubleshooting. |
| |
| Basically the important method on a template is the `render` method. It |
| takes either a dict or keyword arguments. All keyword arguments appear |
| in the template as variables. |
| |
| So these two snippets do the same: |
| |
| .. sourcecode:: python |
| |
| tmpl.render( |
| knights='we say nih', |
| spam='and eggs' |
| ) |
| |
| .. sourcecode:: python |
| |
| tmpl.render({ |
| 'knights': 'we say nih', |
| 'spam': 'and eggs' |
| }) |
| |
| The Environment |
| =============== |
| |
| [[environment_doc]] |
| |
| The environment provides the following useful functions and properties in |
| addition to the initialization values: |
| |
| =========================== ================================================== |
| ``parse(source, filename)`` Parse the sourcecode and return the abstract |
| syntax tree. This tree of nodes is used by the |
| `translators`_ to convert the template into |
| executable source- or bytecode. |
| ``lex(source, filename)`` Tokenize the given sourcecode and return a |
| generator of tuples in the form |
| ``(lineno, token, value)``. The filename is just |
| used in the exceptions raised. |
| **New in Jinja 1.1** |
| ``from_string(source)`` Load and parse a template source and translate it |
| into eval-able Python code. This code is wrapped |
| within a `Template` class that allows you to |
| render it. |
| ``get_template(name)`` Load a template from a loader. If the template |
| does not exist, you will get a `TemplateNotFound` |
| exception. |
| =========================== ================================================== |
| |
| There are also some internal functions on the environment used by the template |
| evaluation code to keep it sandboxed. |
| |
| Undefined Values |
| ================ |
| |
| If a template designer tries to access a not defined value the return value |
| will be the `undefined_singleton` specified in the environment. The default |
| one is the `SilentUndefined` which fails in no case. Additionally there is |
| a special undefined type called the `ComplainingUndefined` which is located |
| in the `jinja.datastructure` module. It will raise exceptions when compared |
| with other types, or when rendered. |
| |
| Theoretically you can provide your own singleton by subclassing |
| `AbstractUndefindedType` and creating an instance of it using `make_undefined` |
| (both located in `jinja.datastructure`) but those two types should cover |
| the basic use cases. The `Undefined` object in that module exists for |
| backwards compatibility and is an alias for `SilentUndefined`. |
| |
| To create your own undefined singleton do something like this: |
| |
| .. sourcecode:: jinja |
| |
| from jinja.datastructure import AbstractUndefinedType, make_undefined |
| |
| class MyUndefinedType(AbstractUndefindedType): |
| __slots__ = () |
| |
| def __iter__(self): |
| return iter(int, 0) |
| |
| def __reduce__(self): |
| return 'MyUndefined' |
| |
| MyUndefined = make_undefined(MyUndefinedType) |
| |
| The only thing you have to do is to override `__reduce__` so that it returns |
| the name of the singleton instance and create the instance using |
| `make_undefined`. Everything else is up to you. Note that currently attributes |
| on undefined objects are available in the Jinja layer too which however |
| will change in one of the next Jinja versions. So if you put a `foo` attribute |
| on your undefined singleton you will be able to do ``{{ undefined.foo }}`` |
| by now but certainly not in the future. |
| |
| This limitation currently exists because undefined is treated as normal object |
| and thus affected by normal getattr calls. |
| |
| |
| Automatic Escaping |
| ================== |
| |
| Jinja provides a way for automatic escaping, but we do not recommend using it. |
| Because Jinja was designed as multi purpose template engine there are some |
| issues with automatic escaping. For example filters don't deal with markup |
| data. Also you can easily bypass the automatic escaping so it's not something |
| you can expect to "just work". Also there is a huge overhead when escaping |
| everything. |
| |
| The best idea is to think about which data already contains html, which will |
| probably contain (eg: every user input, etc) etc. And live with self escaping. |
| |
| That's usually a much better idea. |
| |
| |
| Loading Templates From Files |
| ============================ |
| |
| Loading templates from a string is always a bad idea. It doesn't allow template |
| inheritance and is also slow since it parses and compiles the template again |
| and again whereas loaders can cache the template code. |
| |
| All you have to do is to define a loader and use the `get_template` function. |
| |
| .. sourcecode:: python |
| |
| from jinja import Environment, FileSystemLoader |
| env = Environment(loader=FileSystemLoader('templates')) |
| tmpl = env.get_template('index.html') |
| print tmpl.render(name='John Doe') |
| |
| This tells jinja to look for templates in the ``templates`` folder. It's a |
| better idea to use an absolute path here though. For a list of supported |
| loaders or how to write your own, head over to the `loader`_ documentation. |
| |
| Adding Filters |
| ============== |
| |
| If you want to add additional filters to the environment, the best way is to |
| modify the ``filters`` attribute and not to pass a dict to the environment. |
| If you pass it a dict it will not include the default filters! |
| |
| .. sourcecode:: python |
| |
| from mylib import my_cool_filter |
| env.filters['mycoolfilter'] = my_cool_filter |
| |
| Writing filter functions is explained in the `filter development`_ section. |
| |
| Adding Tests |
| ============ |
| |
| Adding additional tests works analogous to filters: |
| |
| .. sourcecode:: python |
| |
| from mylib import my_cool_test |
| env.tests['mycooltest'] = my_cool_test |
| |
| Writing tests is explained in the `test development`_ section. |
| |
| |
| .. _installation: installation.txt |
| .. _context documentation: contextenv.txt |
| .. _loader: loaders.txt |
| .. _translators: translators.txt |
| .. _filter development: filters.txt |
| .. _test development: tests.txt |