给主题添加区域

由 jieyyal 提交于 5 July 2015
原文链接：Adding Regions to a Theme

给主题添加区域（Region）需要满足以下两点：

- 给你的THEMENAME.info.yml文件添加区域标记。

- 编辑你的page.html.twig文件并输出新的区域。

在info文件里添加区域

首先需要在你的THEMENAME.info.yml文件里声明新的区域。区域的声明方式如下（声明在“regions:”下方）：

# Regions
regions:
  header: 'Header'
  content: 'Content'
  footer: 'Footer'

区域的键名必须是字母或数字，可以包含下划线（_）。键名必须以英文字母开头。在你的THEMENAME.info.yml文件中引用区域时，键名会被作为区域机器名，当然在代码里引用时也是如此。键值则作为人类可读的名字会被使用在区域的管理界面上。

在模板文件里添加区域：

为了把区域里的内容显示出来，你首先要确保你的区域已经添加到了page.html.twig文件中。

区域需要用Twig变量代替，以字符串page拼接区域的键名。

例如:

header: 'Header'

在你的Twig模板里会变成:

{{ page.header }}

这之后，你就可以把区域当作任何Twig变量一样，把内容输出到任何你需要输出的地方，以及用任何有意义的结构包裹。

默认的区域

在page.html.twig文档中可以看到一系列默认区域。

  • page.header: header区域。
  • page.primary_menu: 主导航菜单区域。
  • page.secondary_menu: 副导航菜单区域.
  • page.highlighted: 高亮内容区域。
  • page.help: 动态帮助文字，大多数给后台页面。
  • page.content: 当前页面的内容。
  • page.sidebar_first: 第一个边栏。
  • page.sidebar_second: 第二个边栏。
  • page.footer: footer的区域。
  • page.breadcrumb: 面包屑区域。

现在主导航菜单、副导航菜单和面包屑都有他们自己的区域了。

如果你的主题没有声明任何区域那么Drupal会使用这些默认区域。这些默认区域和默认的core/modules/system/templates/page.html.twig模板文件相对应。还有两个额外的区域，page_top和page_bottom,他们是在默认的html.html.twig模板里输出的。

如果你在自己的主题里声明了任何区域，哪怕是一个，所有默认的区域就不会有效了。你必须要声明你需要用到的所有区域。注意：大多数情况下你需要确保你声明了page_top和page_bottom这两个区域，因为它们是在html.html.twig文件里输出的并且有些模块需要他们存在。

以下是英文原文，可对照阅读：

Last updated May 26, 2015. Created on April 11, 2015. Edited by camorim, Verscienta, eojthebrave. You can edit this page, too.

Adding regions to a theme requires:

- Adding region meta-data to your THEMENAME.info.yml file - Editing your page.html.twig file and printing the new regions

Adding Regions to Your Info File

Start by declaring any new regions in your THEMENAME.info.yml file. Regions are declared as children of the regions key like so:

# Regions
regions:
  header: 'Header'
  content: 'Content'
  footer: 'Footer'

Region keys should be alphanumeric, and and include underscores (_). Keys should begin with a letter. When referencing regions the key from your THEMENAME.info.yml file will be used as the machine readable name of the region, and is how you will reference the region in code. The value is the human readable name of the region is what will be used in the user interface for anyone administering regions.

Adding Regions to Your Templates

In order for regions to display any content placed into them you'll need to make sure your new regions are also added to your page.html.twig file. Regions will be represented as Twig variables whose name corresponds with the key used in your THEMENAME.info.yml file with the string page. prepended.

Example:

header: 'Header'

Will become:

{{ page.header }}

In your Twig templates.

Beyond that, you can treat them just likey any other Twig variable, output the content wherever you need to, and wrap them with whatever markup makes sense for your use case.

Default Regions

See the page.html.twig documentation for a list of default regions.

  • page.header: Items for the header region.
  • page.primary_menu: Items for the primary menu region.
  • page.secondary_menu: Items for the secondary menu region.
  • page.highlighted: Items for the highlighted content region.
  • page.help: Dynamic help text, mostly for admin pages.
  • page.content: The main content of the current page.
  • page.sidebar_first: Items for the first sidebar.
  • page.sidebar_second: Items for the second sidebar.
  • page.footer: Items for the footer region.
  • page.breadcrumb: Items for the breadcrumb region.

Now, main menu, secondary menu and breadcrumb have their own regions. If your theme does not declare any regions Drupal will assume a set of default regions. These regions correspond with what the default core/modules/system/templates/page.html.twig file expects, as well as two additional regions, page_top, and page_bottom, which are output in the default html.html.twig template.

If you declare any regions in your theme, even just one, all the default regions will no longer be applied and you assume resopnsibility for declaring any and all regions you want to use. Note: in most cases you'll want to make sure you declare the page_top and page_bottom regions in your theme since those are output by the html.html.twig file and some modules might expect them to be present.

分类

最新话题