dingja 2.1.2

为什么选择dingja？

仅仅因为其他任何django的jinja2集成应用都无法满足完美主义django开发者的需求。

dingja让您能够

• 在同一项目中使用django和jinja2模板，动态选择要使用的模板引擎

• 从django模板扩展和包含jinja2模板，反之亦然

• 将django模板代码插入jinja2模板中

• 使用装饰器将任何django模板标签或Python函数转换为jinja2过滤器或全局变量……而无需创建导入循环

• 使用django的 makemessages 管理命令从jinja2模板中提取翻译字符串

• 访问有用的jinja2扩展，例如HTML压缩、大多数django模板的本地标签和上下文处理器

用法

• 使用您选择的方法安装dingja

• 将‘dingja’添加到您的INSTALLED_APPS

• 将 TEMPLATE 设置为

  TEMPLATES = [
     {
        'BACKEND': 'djinga.backends.djinga.DjingaTemplates',
        'DIRS': ['your/first/template/directory',
                 'your/second/template/directory'],
        'OPTIONS': {
            ...
        },
     },
  ]

• 为jinja2和djinga添加相关选项

工作原理

默认情况下，如果模板具有.html、.htm、.djhtml或.djhtm文件扩展名，它将使用Django内置的模板引擎进行渲染。如果它具有.jjhtml或.jjhtm文件扩展名，它将使用Jinja2进行渲染，并使用django设置模块中提供的设置值。

选项

只需将以下选项添加到匹配djinga后端的"OPTIONS"部分的"TEMPLATES"项

TEMPLATES = [
   {
      'BACKEND': 'djinga.backends.djinga.DjingaTemplates',
      'OPTIONS': {
         'option1': 'value1',
         'option2': {'key1': 'val1',
                     'key2': 'val2'},
          ...
       },
   },
]

dj_exts

一个列表或元组，包含应使用Django内部模板引擎渲染的模板的文件扩展名（带或不带开头的点）。

默认为('html', 'htm', 'jjhtml', 'jjhtm')

jj_exts

一个列表或元组，包含应使用Jinja2渲染的模板的文件扩展名（带或不带开头的点）。

默认为('jjhtml', 'jjhtm')

condition

一个函数，仅接受模板文件路径作为参数，如果文件应使用Jinja2进行渲染则返回True。默认为如果扩展名在JINJA2_JJ_EXTS中，则返回True的函数。

extensions

一个元组或列表，包含jinja2将加载的扩展名（作为Python对象或指向Python对象的路径）。一些扩展在djinga下通过djinga.ext.*提供。

globals

作为字典的jinja2全局变量。

filters

作为字典的jinja2过滤器。

load_from

一个元组或列表，包含要从中加载全局和过滤器的模块路径。这有利于补充或替换globals和filters选项。有关详细信息，请参阅添加全局和过滤器。

any_jinja2_option

可以提供任何其他参数来构造jinja2环境。

Jinja2扩展

Djinga附带了一些Jinja2扩展

djinga.ext.static

提供了一个{% static 'path' %}标签，用于引用Django的staticfiles目录

djinga.ext.css

提供了一个{% css 'rel/path/to/file.css' %}标签，该标签生成一个指向在css目录中的相对路径的HTML链接元素。css目录的路径可以通过设置JINJA2_STATIC_CSS相对于Django的staticfiles目录来定义

djinga.ext.js

与djinga.ext.css相同，但生成一个指向javascript文件的HTML脚本元素。js目录的相对路径可以通过设置JINJA2_STATIC_JS来定义

djinga.ext.media

简单地将django的MEDIA_URL连接到提供的参数

djinga.ext.django

来自coffin的一个PR。提供了一个{% django %}{% enddjango %}标签，用于在jinja2模板中包含Django模板语言。要使此标签正常工作，必须启用django.core.context_processors.request上下文处理器。

djinga.ext.csrf_token

来自coffin提供了一个类似于Django的{% csrf_token %}标签。

djinga.ext.url

提供了一个用于URL反转的标签，类似于django模板中的标签。

djinga.ext.htmlcompress.HTMLCompress / SelectiveHTMLCompress

基于Armin Ronacher的版本。在模板编译时消除了无用的空白，而无需额外的开销。从版本2.0开始，它还处理内联javascript。

Django模板标签

以下标签将自动在任意Django模板中可用

extends

覆盖了标准的 {% extends %} 标签，并使其能够引用 jinja2 文件以及普通的 Django 模板文件。虽然当前文件的模板引擎仍然是 Django 的，但扩展文件的模板引擎可以是 Jinja2 或 Django，具体取决于文件扩展名（在 dj_exts 或 jj_exts）。

添加全局变量和过滤器

将全局变量和过滤器添加到设置模块中的 globals 或 filters 选项中，是使它们在您的 Jinja2 模板中可用的简单方法。

然而，这并不总是方便或可能的（导入循环），因此 Djinga 通过结合使用 jj_global 和 jj_filter 装饰器以及 load_from 选项来简化此过程。

基本来说，装饰器将函数标记为 Jinja2 全局变量或过滤器，而设置（一个模块路径列表）指示 Djinga 在何处查找它们。

一个简短的例子胜过冗长的解释，所以让我们来看看。

这是

[my_app/my_module.py]
from djinga.register import jj_filter, jj_global

@jj_global
def my_tag(*args, **kw):
   pass

@jj_filter
def my_filter(*args, **kw)
   pass

[settings.py] # django 1.8+
TEMPLATES = [
   {
      'BACKEND': 'djinga.backends.djinga.DjingaTemplates',
      'OPTIONS': {
         'load_from': ('my_app.my_module',),
       },
   },
]

[settings.py] # django < 1.8
JINJA2_LOAD_FROM = (
   'my_app.my_module',
)

等同于这样

[my_app/my_module.py]
def my_tag(*args):
   pass

def my_filter(*args, **kw)
   pass

[settings.py] # django 1.8+
from my_app.my_module import my_tag, my_filter
TEMPLATES = [
   {
      'BACKEND': 'djinga.backends.djinga.DjingaTemplates',
      'OPTIONS': {
         'globals': {'my_tag': my_tag},
         'filters': {'my_filter': my_filter},
       },
   },
]

[settings.py] # django < 1.8
from my_app.my_module import my_tag, my_filter
JINJA2_GLOBALS = {'my_tag': my_tag}
JINJA2_FILTERS = {'my_filter': my_filter}

……具有显著的优势，即不需要在 settings 模块中可能存在问题的 import 语句。

jj_global 和 jj_filter 装饰器与 Jinja2 的任何内置装饰器兼容。它们不会影响装饰函数的行为或签名，因此您可以使用它正常（例如，作为普通的 Django 模板标签或过滤器）。

收集到的全局变量和过滤器将被追加到已在 globals 和 filters 中指定的那些。

makemessages 管理命令

改编自 coffin。

Djinga 覆盖了 Django 的 makemessages 核心管理命令，以包含特定的 Jinja2 翻译标签，并确保标记为翻译的 Jinja2 模板中的字符串出现在翻译字典中。