Links

• Source
  • github: mitsuhiko/jinja2
    • runtime.py: Context::resolve()
• Docs
• Line Statements
  • Line statements can span multiple lines if there are open parentheses, braces or brackets:
• API:   High Level  |  Low Level  |  Meta
• Global Namespace
  • Variables stored in the Environment.globals dict are special as they are available for imported templates too, even if they are imported without context.
  • This is the place where you can put variables and functions that should be available all the time.
  • Additionally Template.globals exist that are variables available to a specific template that are available to all render() calls.
• Unicode
  • It is not possible to use Jinja2 to process non-Unicode data.
• Notes on Identifiers
• Filters and tests are looked up in separate namespaces and have slightly modified identifier syntax. Filters and tests may contain dots to group filters and tests by topic. For example it’s perfectly valid to add a function into the filter dict and call it to.unicode.
• Jinja2 uses a central object called the template Environment
• Using a template loader rather then passing strings to Template or Environment.from_string() has multiple advantages.
  • It enables template inheritance.
• The default encoding of templates is assumed to be utf-8.
• Undefined Types
• The Context
• Loaders
  • FileSystemLoader  |  FileSystemLoader  |  PackageLoader  |  DictLoader  |  FunctionLoader  |  PrefixLoader  |  ChoiceLoader  |  ModuleLoader
• Utilities
• Writing Templates
  • Variables
  • Comments
  • Filters
    • Builtin  |  Custom
    • default(value, default_value=u'', boolean=False)
  • Tests
    • Builtin Tests  |  Custom Tests
  • Global Functions
  • Expressions
  • Whitespace Control
  • Escaping  |  HTML Escaping
  • Line Statements
  • Including templates
  • Importing templates
    • Import Context Behavior
  • Template Inheritance
    • Assignments outside of blocks in child templates are global and executed before the layout template is evaluated.
    • You can print a block multiple times by calling {{ self.BLOCK_NAME }}.
    • You can render the parent's content in an overridden block by calling {{ super() }}.
    • Super Blocks
  • Control Structures
    • For loop
      • It’s not possible to break or continue in a loop.
      • However, you can enable the Loop Controls extension extension that provides {% continue %} and {% break %} to accomplish the same thing.
        • See Loop Controls
    • With Statement
      • Enabled by the with statement extension
    • Inline Expression
  • Macros
    • Inside macros you have access to three special variables: varargs, kwargs, caller
    • call
• Extensions
  • SO: example implementing an alternate include syntax
• Tips and Tricks
  • Null-Master Fallback
  • Alternating Rows
  • Highlighting Active Menu Items
  • Accessing the parent Loop
• Bytecode Cache
  • jinja2.FileSystemBytecodeCache(directory=None, pattern='__jinja2_%s.cache')
  • jinja2.MemcachedBytecodeCache(client, prefix='jinja2/bytecode/', timeout=None)
• Loaders
• Template
  • render([context])
    • Returns unicode.
  • generate([context])
    • Returns a unicode string generator.
  • stream([context])
    • Returns a TemplateStream that supports buffering multiple items (since WSGI flushes after each item) and dumping to a stream.
• Environment
  • compile_templates()
    • Remember to pass ignore_errors = False.
    • env.compile_templates('/tmp/templates.zip', extensions=('jinja',), ignore_errors=False)
      • This filters files to include only those with the ".jinja" extension.
  • list_templates()
  • add_extension(extension)
    • Adds an extension after the environment was created.
  • join_path(template, parent)
  • TemplateStream
    • enable_buffering([size=5])
    • dump(fp, encoding=None, errors='strict')
      • Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')
• Gotchas
  • My Macros are overriden by something
• Examples
  • Template from string
  • Basic loading of a template
  • Load template from app directory and some config

Basics

• Blocks start and stop with {% and %}
• Variables start and stop with {{ and }}
• Comments start and stop with {# and #}

Snippets

template.module

t = Template('{% macro foo() %}42{% endmacro %}23')
unicode(t.module)
# u'23'
t.module.foo()
# u'42'