你在这里

Twig 模版的运用

原文:Working with Twig Template

Drupal允许您覆写用于生成HTML标记的所有模板,这样您就能完全控制定制主题中输出的标记。从高级HTML到小的字段,每个页面元素都有模板。

覆写模板(Overriding templates)

通过向遵循一定命名约定的主题文件夹添加模板,您就可以覆写Drupal核心模板。

要覆写模板,您:

  1. 找到想覆写的模板;
  2. 把模板文件从其基本位置复制到您的主题文件夹;
  3. (可选地)根据命名约定重新名命模板,以便针对要使用模板的更具体区域;
  4. 按您的喜好修改模板。

一旦您把模板文件复制进您的主题并清除缓存,Drupal就会开始用您的模板文件实例而不是基础模板。对于页面的任何部分,您都可以用Twig调试工具来找到其使用的模板。

主题钩子建议(Theme hook suggestions)

有时您想对模板文件进行修改,但仅限于使用到的一些地方。常见的例子是仅对特定类型的结点修改其结点模板文件。Drupal的主题层允许您遵循一定的名命约定来针对模板文件的特殊使用情况。当表现文章结点时,Drupal会首先寻找node--article.html.twig模板文件,如果它存在就加以使用。如果它不存在,Drupal就退回去使用默认的node.html.twig模板。Drupal用以决定一个模板可能使用的名称的过程叫做主题钩子建议。

主题钩子建议允许您用一定的命名约定,在您的主题中针对模板文件实现想要的覆写。

从核心、模块、主题引擎到主题的所有层次都可以提出建议。您可以用钩子来添加或修改建议:

  •     hook_theme_suggestions_HOOK(array $variables)
  •     hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
  •     hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)

重建缓存(Rebuild cache)

使用主题钩子建议时,有可能Drupal在使用自己的缓存而非新模板所建议的。如果您遇到此问题,就清除缓存。要清除缓存,选择清除Drupal缓存中描述的方法之一。

背景信息(Background information)

您可以把建议想像成命名暗示,告诉系统根据正确的环境进行挑选。模板建议通过可修改的主题建议钩子进行设定。这些钩子允许任何模块或主题提供替代主题函数或模板命称建议,并重排或移除hook_theme_suggestions_HOOK()或该钩子的早期调用所提供的建议。

Drupal如何根据路径来确定页面主题钩子建议

这里是基于theme_get_suggestions()函数的另一种解释:

一个页面可能的模板列表由Drupal通过theme_get_suggestions函数生成,该函数由sytem_theme_suggestions_page()函数调用。

该页面的Drupal路历首先分解为其组件。如上所提及,Drupal路径并非其任意的别名:一个页面只有唯一一条Drupal路径。例如,"http://www.example.com/node/1/edit"和"http://www.example.com/mysitename?q=node/1/edit",其Drupal路径为node/1/edit,而其组件为"node"、1和 "edit"。

接着,将前缀设定为”page”。然后,对每个组件,遵循以下逻辑:

  1. 如果组件为数字,则向建议列表添加前缀和”__%”。
  2. 无论组件是数字与否,都向建议列表添加前缀和”__%”。
  3. 如果组件不是数字,则向前缀附加”__”和组件。

注意,要最终把建议变成实际文件名,”__”会变为”--“,而”.html.twig”则附加在建议后。于是,对于node/1/edit,我们得到下列建议:

  1.     page.html.twig (这总是一条建议)
  2.     page--node.html.twig (前缀设定为page__node)
  3.     page--node--%.html.twig
  4.     page--node--1.html.twig (因为是数字,前缀不变)
  5.     page--node--edit.html.twig (前缀设定为 page__node__edit)
  6.     page--front.html.twig (但只有当node/1/edit是首页时)

当页面实际渲染时,查看最后的建议。如果它存在,就使用该建议。否则,查看前一条建议,如此等等。当然,如果不存在覆写建议,那么page.html.twig就是最终的建议。这也解释了为什么page--front.html.twig存在的话会为首页覆写任何其它建议:它始终是指定为首页的页面的最后建议。

与Drupal 7的区别(Differences with Drupal 7)

以前,要改变模板建议,您就在预处理函数中修改$variables['theme_hook_suggestion']和 $variables['theme_hook_suggestions']来引入建议。在Drupal 8中,现在模块和主题在自己的专用钩子中定义和修改主题建议。

更多信息(More Information)

变更记录主题建议的新钩子