区域配置

区域定义在模板原型的页面定义里配置。STK > 网站定义 /default/templates/prototype/areas内容节点包含可用的页面区域的定义。区域可作为内容映射。区域定义使区域对模板可用，定义区域的行为，以及哪些组件（如果有的话）在区域里可用。

本页为区域定义配置的概述。STK区域页有更为深层的关于每个STK区域的讨论。

可用区域

原型模板定义可用的区域。单个具体模板使用大多数但非全部的区域。

页面脚本，main.ftl，决定了区域绘制的顺序，以及在哪里落入边框（wrappers）内。这样，区域节点顺序在配置中就变得不重要了。页面脚本使用[cms.area name="<area name>"]标签来引用区域。

在以下表格中，您可以看到在原型中配置的父区域，以及页面上区域的位置和边框。

简单来说，每个区域都有以下内容和功能。参看STK区域页里更为详尽的讨论。

• htmlHeader在HTML的head元素里插入管理元素，用来表示关键词、描述等，创建标题元素，以及到样式表和JavaScript的链接。
• branding包含标志、品牌口号、搜索框以及内部登录链接。
• sectionHeader只在章节页面上使用，包含章节的横幅正文。除非特意配置，否则sectionHeader会被所有子页面继承。
• stage只在主页使用，包含一个较大的要点组件。
• platform不被使用，但可以添加到任何模板，包含一个页面要点。
• main包含页面的主要内容。用在一个文章页面时，主内容为文章故事，在新闻页面时则为新闻项等。在章节页面和主页上，主内容为链接到内容页面的要点。
• extras为要点组件而使用。通常这些都与主内容有关。例如，如果主内容是事件，那么附加物可以是日历、通信录以及新事件要点组件，提供一个可点击的日历、通信录信息和一个即将发生的事件列表。
• promos通常被用来推广特殊事件或交易。窗口够宽时，该区域浮在main和extras右方；窗口较窄时，则会在下方。
• base占用页面的整个宽度，可包含一个大的圆盘幻灯片或分类云组件。
• footer包含链接、样板文件和版权声明。

嵌套区域

区域可以嵌套子区域，而子区域也可反过来有它们自己的嵌套区域。嵌套区域在/default/templates/areas/<parent area name>/areas/<child area name>节点下配置。第二（或第三）个areas内容节点名标志着子配置为一个区域。父区域和子区域支持相同的属性和配置选项。

区域定义

以下列出了区域可包含的最少的属性。唯一必须的属性为type。

• description设置区域描述的消息包关键字。
• enabled是一个布尔属性，有true和false两个值可选，来启用或禁用该区域。该属性默认值为true，故当此属性被忽略时，区域默认被启用。模板原型里启用的区域可通过在具体模板里修改原型的值来禁用。
• templateScript设置到绘制区域的脚本的路径。专用脚本仅在做简单绘制区域以外的事时才需要。除非模板定义里引用了另一个脚本，否则所有的具体模板使用原型里定义的脚本。例如，除了stkSection和stkHome使用/templating-kit/pages/section/mainArea.ftl之外，所有具体模板使用STK > 模板 /templating-kit/pages/global/mainArea.ftl绘制main区域。
• title为区域名设置消息包关键字。该值在区域工具栏里绘制。

• type定义可在区域里绘制的组件数量（如果可以有组件的话）。可用的选项在以下的区域类型中讨论。

  节点名	值
  prototype
  areas
  base
  availableComponents
  description	areas.templates.base.description
  enabled	true
  templateScript	/templating-kit/pages/global/baseArea.ftl
  title	areas.templates.base.title
  type	list

很多STK区域定义也使用以下的一个或多个属性：

• class定义具体的用来实例化的Java类。
• dialog以<module name>:<path to dialog>格式设置到对话框定义的路径。
• editable为一个布尔属性，有true和false两个选项值，用来定义编辑者是否可以编辑此区域内容。
• modelClass定义包含此区域业务逻辑的Java类。

• optional为一个布尔属性，有true和false两个选项值，用来定义编辑者是否可以删除此区域。

  节点名	值
  prototype
  areas
  sectionHeader
  description	areas.templates.sectionHeader.description
  dialog	standard-templating-kit:pages/section/stkSectionHeader
  editable	false
  enabled	true
  modelClass	info.magnolia.module.templatingkit.templates.areas.SectionHeaderAreaModel
  templateScript	/templating-kit/pages/content/sectionHeader.ftl
  title	areas.templates.sectionHeader.title
  type	noComponent

您可以在参考资料部分找到区域属性的完整列表。

区域类型

type属性决定可以在区域内绘制的内容，有三个选项：single，list和noComponent。

• 前两个选项绘制/<area name>/availableComponents节点下可用的组件（参考以下的可用组件）：
• single区域在页面上生成一个组件。编辑者可以从很多组件类型中选择，但只可以添加一个。此类型区域的例子有stage，opener和可以在两种大的要点类型中选择；后两者里只能有单个组件类型。
• list区域在页面上绘制任意数量的有序组件。编辑者可用的组件类型的选择可以从一个到多个。此类型区域的例子包括metaNavigation，content，extras1/2，base，footer这些有多个组件类型可用的，以及promos这种编辑者只可以添加一个组件类型的。
• noComponent区域不绘制<area name>/availableComponents节点下可用的组件，但可绘制配置不同的组件。noComponent区域的例子有：
• intro和sectionHeader，绘制页面页眉和章节页眉组件。
• branding，main和extras，包含子区域。
• htmlHeader，logo，search和breadcrumb，通过区域脚本绘制。

您可以在具体定义里改变区域类型（type）。参看模板定义 > 改变区域行为了解这在特性模板上是如何实现的。

区域脚本

模板原型所使用的区域脚本可在STK > 模板 /templating-kit/pages下获得。多数区域脚本只简单的分配一个DIV元素，然后调用要绘制的区域，而不定义在区域里有什么，因为那是区域定义的责任。

一个区域定义就可以绘制一个区域。如果single或list区域并没有直接引用templateScript，那么系统会采用以下默认代码：

[@cms.component content=component /]

[#list components as component]
   [@cms.component content=component /]
[/#list]

区域类

很多区域定义会定义一个特定的Java类，这个类在调用区域时可以实例化。如果您想要以任意方式在具体模板定义里修改区域定义，class属性节点应在具体区域定义里重复出现，也就是说，模板原型和具体模板定义里都应包含一个引用相同的完全相称类名的class属性。这样做的理由是，两种定义和它们的classes可以在模板合并过程中同时被实例化。如果在模板定义没能找到class，那么使用备用的class，即

比较以下模板原型里的main区域定义和stkArticle模板的配置。注意相同的class在两者里都是需要的，因为stkArticle使用了不同的templateScript。

这个规定只对以下情形适用：

• 原型区域定义里有class属性，并且
• 在具体区域定义中，区域定义某种程度上被修改。

如果该区域不使用特定的class，所有其它属性都可以通过具体定义里一个简单的修改而被修改或添加。

可用组件

/areas/<area name>/availableComponents节点使组件在区域内可用。此节点只能在list和single区域里使用，用来配置组件的一个内容映射，这些组件是通过读取使用Node2Bean机制写进Java Bean的配置来建立的。

注意以下几点：

• 组件定义通常在STK > 模板定义 /components里配置，在这里设置为对模板原型可用。
• 每个组件都是在一个子内容节点下配置的。
• 通常情况下，内容节点名对应组件定义里的内容节点名，但这并不是严格规定的。
• id属性以<module name>:<path to component definition>格式定义到组件定义的路径。这就可以实现从任何模块来添加组件，而不仅限于STK组件。
• 标准的一套组件在原型里对多数区域都可用。只要不是在具体模板定义里配置了覆写或添加，相同的组件在所有模板里都可用。样例可参考extras区域，base区域和promos区域。

• 一个值得注意的例外情况是content区域。该区域通过使这几种不同的组件类型可用来区分具体模板：内容模板里的内容组件，主页和章节模板的要点，以及特性模板里的独特组件。因此，这些组件在具体的模板定义里设置为可用，而在原型里却不可用。

  节点名	值
  prototype
  areas
  base
  availableComponents
  stkTeaserCarousel
  id	standard-templating-kit:components/teasers/stkTeaserCarousel
  catCloudWide
  id	categorization:components/catCloudWide

限制组件使用

您可以在availableComponents节点下限制单个组件对特定角色用户的可用性。用户的角色在安全应用的角色标签里设定，角色里有更多信息。下列配置样例限制了只有superuser角色的用户可以使用stkPromo组件。

• roles节点使Magnolia CMS知道可能有使用限制。

• superuser数据节点的值也设置为superuser时，就限制了只有分配了superuser角色的用户可以使用该组件。

  节点名	值
  prototype
  areas
  promos
  availableComponents
  stkPromo
  roles
  superuser	superuser
  id	standard-templating-kit:components/promos/stkPromo

这可以有效的防止没有分配此角色的用户创建组件，但他们仍可以编辑、移动和删除已有组件。这里是superuser对比样例编辑者Eric（username/password=eric）在页面编辑器里所看到的不同。

限制组件动作

 4.5.9+

您可以根据用户的角色RolesRoles定义哪些用户可以编辑、移动和删除组件。在下列例子里，有着superuser和delete-editors角色的用户可以编辑、移动和删除stkPromo组件。editors角色用户仅可以编辑和移动组件。

节点和属性：

• permissions：包含对动作的限制。
  
  • <write| move| delete>：有限制的动作。
    
    • <roleName>识别角色。该属性（attribute）名是任意的，但其值必须与已有角色相匹配。

这是被分配了superuser，delete-editors和editors三种角色的用户在页面编辑器里所看到的。只有superuser角色用户可以在此区域创建新的stkPromo组件，因为组件使用在/availableComponents/stkPromo/roles配置里被限制了。

限制组件数量

 STK 2.0.9+

您可以添加一个maxComponents属性到<area name>名字节点并设置合适的值，来限制在list区域绘制的组件数量。一旦数量达到限制，新建组件输入框就会被Maximum Components Reached通知替代，来阻止编辑者添加更多的组件。下列配置样例将base区域的组件数量限制为2。

区域继承

区域支持组件和属性继承。

组件继承

组件继承有两个好处：由于在父页面上添加组件便可在子页面上重复，可以节省精力；组件继承还可以加强一致性，只有源组件可以编辑，继承实例则不可以编辑，所以这个组件在它显示的地方始终保持一致。组件继承意味着区域的组件也会添加到子页面上。

以下两种类型的组件继承是支持的：

• 自动继承：只能在父页面上添加组件，所有子页面自动继承。metaNavigation区域为此类继承的例子。
• 选择性继承：编辑者可以决定一个特定的组件是否可以延伸到子页面上。组件对话框里有在子页面中显示复选框。只有当此复选框被选中时，组件才会被延伸使用。extras1/2和promos区域都是这类继承的样例。

组件继承在/areas/<area name>/inheritance内容节点下配置，并且只对list和single区域类型有用。

• enabled属性启用和禁用区域继承，对组件继承和属性继承两者都有效。
• components属性有三个选项：
• all配置自动继承。此区域里添加的所有组件都自动延伸到子页面。
• filtered配置选择性继承。此区域内添加的组件只有当组件对话框里的在子页面中显示框被选中时才向下延伸。inheritable属性是在组件内容节点上创建，它的值被设置为true，是选择器的触发者。只有该属性值为true的节点才被子页面继承。
• none表示没有组件被继承。该属性有效的禁用了组件继承，不需要同时禁用属性继承。参看以下的属性继承。

当components属性被设置为all时，您就可以使用editable区域属性来确保组件只在正确的页面被添加和编辑。metaNavigation区域里使用了该选项：

• 在模板原型里，属性设置为false，以使组件默认为不可编辑。
• 在stkHome模板定义里，属性设置为true，以确保组件只在主页上可编辑。

• AllComponentsAndResourcesInheritancePredicate：包含所有组件的组件继承的Predicate。
• FilteredComponentInheritancePredicate: 组件继承Predicate，该组件继承包含仅有一个inheritable属性且值为true的节点。
• InheritNothingInheritancePredicate：不含任何组件的组件继承的Predicate。
• NodeDepthComparator：对节点按深度排序的比较器。比较深层的节点被放在靠后的位置，同样级别的节点以它们作为同层出现的顺序排列。

Predicate类定义components属性在配置中可用的行为选项。您可以定义自己的Predicate类，只需添加一个predicateClass属性到inheritance配置中，并将其值设置为您的类的完全相称类名。此属性优先于components属性。

比较器（comparator）类定义了被继承的组件以何种顺序绘制。您可以定义自己的比较器类，只需添加一个nodeComparatorClass属性到inheritance配置中，并将其值设置为您的类的完全相称类名。这将会覆写缺省的排序行为。

参考可继承组件中关于配置组件继承的教程。

属性继承

属性继承的意思是区域属性会被子页面继承。演示网站没有使用该选项。属性继承通过添加properties数据节点到/areas/<area name>/inheritance内容节点来配置。可用选项有：

• all：所有区域属性都被继承。
• none：没有属性被继承。

下列配置样例显示了一个list区域，其中仅区域属性，而非组件，被子页面继承。

自动生成的组件

区域定义可以自动生成组件。自动生成的组件可以在/areas/<area name>/autoGeneration/content节点里添加。该配置选项在模板原型级别可用，但未被使用。通常它用在具体模板级别更有意义，在STK里，它被用在特性模板里和stkNewsOverview模板的extras区域。参考模板定义－自动生成的组件以获得更多信息。

浮动显示

区域定义里的/floating内容节点指定区域内的元素是否可以浮动显示（并排显示），以及如果可以浮动显示的话，它们会被安排进多少列。与autoGeneration不同，floating不可在模板原型级别里不经过定制就进行配置。它在stkHome和stkSection模板的main/content区域可用。参考启用浮动显示中更多信息。