Coffin-GaretJax 0.3.8.dev

支持的Django模板功能

Coffin目前在Jinja中提供了以下Django标签

• {% cache %} - 目前存在不兼容性：第二个参数（片段名称）需要用引号括起来，才能被视为一个字面字符串，根据Jinja2语法。否则，它将被视为一个标识符，并作为变量解析。

• {% load %} - 在Coffin中实际上是一个无操作，因为模板标签库始终被加载。另见“自定义过滤器和扩展”。

• {% spaceless %}

• {% url %} - 此外，还有一个"view"|url()过滤器可用。

• {% with %}

• {% csrf_token %}

Coffin中移植的Django过滤器

• 日期

• 浮点数格式化

• 复数（期望一个可选的第二个参数，而不是逗号语法）

• 时间

• 时间以来

• 直到时间

• 截断单词

• 截断单词HTML

请注意，大部分情况下，您可以直接在Coffin中使用为Django编写的过滤器。例如，django.contrib.markup“正常工作”（tm）。

以下贡献模块的模板相关功能已移植到Coffin中

• coffin.contrib.syndication.

Jinja 2的i18n扩展已与Django连接，并支持从Jinja2和Django模板中提取字符串的自定义版本的makemessages。

自动转义

当使用自动转义时，您会发现将某些内容标记为Django中的Safestrings并不会影响Jinja 2的渲染。要解决这个问题，您可以对Django进行猴子补丁以生成与Jinja 2兼容的Safestrings。

'''Monkeypatch Django to mimic Jinja2 behaviour'''
from django.utils import safestring
if not hasattr(safestring, '__html__'):
    safestring.SafeString.__html__ = lambda self: str(self)
    safestring.SafeUnicode.__html__ = lambda self: unicode(self)

渲染

将TEMPLATE_LOADERS设置修改为只包含以下加载器

TEMPLATE_LOADERS = (
   'coffin.template.loaders.Loader',
)

并将所有之前定义的模板加载器移动到JINJA2_TEMPLATE_LOADERS设置指令中

JINJA2_TEMPLATE_LOADERS = (
    'django.template.loaders.app_directories.Loader',
    'django.template.loaders.filesystem.Loader',
)

从现在开始，您的所有视图、通用视图和错误页面都将由Jinja2处理和渲染。

使用Django渲染引擎

如果您的项目使用某些需要原始Django模板引擎才能正确渲染模板的应用程序，您可以将它们的名称添加到JINJA2_DISABLED_TEMPLATES设置中，并且Coffin将使用Django模板引擎渲染这些模板。

如果您使用内置的admin应用，则需要添加以下设置

JINJA2_DISABLED_TEMPLATES = (
  'admin',
)

JINJA2_DISABLED_TEMPLATES可迭代中的每个条目都被视为正则表达式模式，并且每个模板都会与它们进行测试，以检查是否需要使用Jinja+Coffin或内置模板引擎进行渲染。

您可以根据以下示例定义设置

JINJA2_DISABLED_TEMPLATES = (
  r'[^/]+\.html',                           # All generic templates
  r'myapp/(registration|photos|calendar)/', # The three apps in the myapp package
  r'auth/',                                 # All auth templates
  r'(cms|menu|admin|admin_doc)/',           # The templates of these 4 apps
)

404和500处理程序

要使用Jinja渲染HTTP 404和500模板，请将以下行替换为

from django.conf.urls.defaults import *

在您的 urls.py 文件中（它应该默认存在），替换为

from coffin.conf.urls.defaults import *

自定义过滤器扩展

Coffin使用与Django相同的templatetag库方法，这意味着您的应用程序有一个 templatetags 目录，其中的每个模块代表一个“模板库”，提供新的过滤器和标签。

在 coffin.template.Library 中可以定义一个自定义 Library 类，用于注册Jinja特定的组件。

Coffin可以自动使现有的Django过滤器在Jinja中可用，但不能使用自定义标签 - 您需要手动将它们重写为Jinja扩展。

启用Jinja的模板库示例

from coffin import template
register = template.Library()

register.filter('plenk', plenk)   # Filter for both Django and Jinja
register.tag('foo', do_foo)       # Django version of the tag
register.tag(FooExtension)        # Jinja version of the tag
register.object(my_function_name) # A global function/object
register.test(my_test_name)       # A test function

您还可以通过您的 settings.py 定义额外的扩展、过滤器、测试和全局变量。

JINJA2_FILTERS = (
    'path.to.myfilter',
)
JINJA2_TESTS = {
    'test_name': 'path.to.mytest',
}
JINJA2_EXTENSIONS = (
    'jinja2.ext.do',
)

其他注意事项

当迁移Django功能时，Coffin当前试图避免Django的静默错误方法，而是选择明确地处理。在Django 1.0版本发布之前，Django正在讨论同一问题（*），但受到向后兼容性问题的限制。然而，如果您无论如何都要转换模板，这可能是一个进行这种更改的好机会。

(*) http://groups.google.com/group/django-developers/browse_thread/thread/f323338045ac2e5e

coffin.template.loader 是 django.template.loader 的一个移植版本，并附带一个启用Jinja2的 get_template() 版本。

coffin.template.Template 是一个支持Django渲染接口的Jinja2-Template（传递Context实例），并使用Coffin的全局Jinja2环境。

coffin.interop 提供了手动将Django过滤器转换为Jinja2以及相反的功能。这也是Coffin的 Library 对象所使用的。

可以在 django.template 命名空间中找到一个启用Jinja2的 add_to_builtins 版本。

您可以通过 JINJA2_ENVIRONMENT_OPTIONS 指定发送到 Environment 的额外参数。

from jinja2 import StrictUndefined
JINJA2_ENVIRONMENT_OPTIONS = {
    'autoescape': False,
    'undefined': StrictUndefined,
}

Coffin不支持的功能

这是一个不完全的列表，列出了Coffin尚未以及可能永远不会做的事情，需要您手动更改

• 切片过滤器在Jinja2和Django中的工作方式不同。将其替换为Jinja的切片语法： x[0:1]。

• Jinja2的默认过滤器本身仅测试变量是否存在。为了匹配Django的行为，您需要将True作为第二个参数传递，这样它还将为定义为False的东西提供默认值。

• Jinja2的循环变量称为loop，而Django的称为forloop。

• 实现与Django的cycle-tag等效的功能可能很困难，也可以参考Django票据#5908和#7501。Jinja自带的设施是forloop.cycle()函数和全局函数cycler。

• add过滤器可能不值得实现。{{ x+y }}是Jinja2的一个相当基本的功能，几乎可以与其他Django到Jinja2的语法更改合并。

• 通过上下文传递的Django类型安全字符串不会被转换，因此Jinja2无法识别。例如，这种情况在Django表单的HTML生成中尤为明显。

• {% autoescape %}标签移植起来非常困难，目前不支持。

• 模板内的文本字符串默认不会被Jinja2视为“安全”，这与Django不同。据Armin Ronacher所说，这是一个设计限制，不会改变，因为许多Python内置函数和方法，您可以在Jinja2中使用，期望得到原始的、未受污染的字符串，因此无法与Jinja2的Markup字符串一起工作。

运行测试

使用nose框架

http://somethingaboutorange.com/mrl/projects/nose/