模板原型

页面配置

缺省的模型原型结构和行为在STK > Site Definitions /default/templates/prototype里配置。

• templateScript属性引用主页面模板脚本，main.ftl。这使脚本对所有在STK > Template Definitions /pages里定义的具体模板定义都可用。
• navigation节点包含缺省的导航配置。
• areas节点包含区域配置。

• jsFiles和cssFiles节点可以用来提供额外JavaScript功能和CSS样式。由于缺省主题包含所有必要的内容，这些节点没有在演示网站里应用，但如果需要的话也是可用的。

  节点名	值
  default
  templates
  prototype
  navigation
  areas
  jsFiles
  cssFiles
  templateScript	/templating-kit/pages/main.ftl
  availability

导航配置

缺省情况下，STK支持2个级别的水平导航和3个级别的垂直导航，但这是可以配置的。一级水平导航包含主页和章节页，也就是网站层级里的级别1和2。在那之后级别遵循网站层级。例如，当您设置水平导航显示两个级别，层级1（主页），2（章节），和3被水平显示。层级4，5，6则被垂直显示。

属性：

• allOpen：当被设置为true时，所有可用的导航级别都被展开。当设置为false时，新的级别会随着用户点击导航链接而被展开。
• enabled：启用和禁用导航菜单。
• level：设置导航的深度。可用的选项为水平方向1和2， 垂直方向3。
• startLevel：开启导航时的级别起点。通常垂直遵循水平，没有级别重叠。例如，该属性可以让您在两种导航中显示级别。 

• template：到模板脚本的路径。vertical和horizontal节点引用它们自己的脚本。

  节点名	值
  default
  templates
  prototype
  navigation
  horizontal
  allOpen	false
  enabled	true
  level	1
  template	/templating-kit/pages/global/horizontalNavigation.ftl
  vertical
  allOpen	false
  enabled	true
  level	2
  startLevel	2
  template	/templating-kit/pages/global/verticalNavigation.ftl

网站导航模型将配置属性显示给绘制垂直和水平导航的脚本。脚本在STK > Templates /templating-kit/pages/global/horizontalNavigation.ftl和/verticalNavigation.ftl里。以下为水平脚本的片段。

[#if model.navigation.showHorizontalNavigation]
    [#assign navigation = model.navigation.horizontalNavigation/]
    [#if (model.navigation.horizontalLevel >1 && navigation.selectedItem??) && (navigation.selectedItem.level>1 || !navigation.selectedItem.leaf)]
        [#assign cssClass = "class=\"plus-navsub\""]
    [/#if]
    <div id="nav-global" ${cssClass!} role="navigation">
        <div id="nav-global-box">
            <h6>${i18n['structural.navigation']}</h6>
            [@renderNavigation navigation=navigation/]
        </div><!-- end nav-global-box -->
    </div><!-- end nav-global -->
[/#if]

以下为不同设置的demo-project导航菜单：

• 缺省设置
  

  

• horizontal/level属性设置为2 
  

  

区域配置

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

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

可用区域

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

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

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

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

• htmlHeader在HTML的head元件里插入管理元件以表示关键词、描述等，创建标题元件，以及到样式表和JavaScript的链接。
• branding包含标志，品牌口号，搜索框，以及内部登录链接。
• 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设置到绘制区域的脚本的路径。专用脚本仅在做简单绘制区域以外的事时才需要。所有的具体模板使用原型里定义的脚本，除非模板定义里引用了另一个脚本。例如，main区域通过STK > Templates /templating-kit/pages/global/mainArea.ftl为所有具体模板绘制，除了stkSection和stkHome使用/templating-kit/pages/section/mainArea.ftl。
• 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和comments这样只有一个组件类型可用的。
• list区域在页面上绘制任意数量的有序组件。编辑者可用的组件类型的选择可以从一个到多个。列表区域的例子有metaNavigation，content，extras1/2，base，footer这些有多个组件类型可用的，以及promos这种编辑者只可以添加一个组件类型的。
• noComponent区域不绘制在<area name>/availableComponents节点下可用的组件，但可绘制配置不同的组件。noComponent区域的例子有：
• intro和sectionHeader，绘制Page Header和Section Header组件。
• branding，main和extras，包含子区域。
• htmlHeader，logo，search和breadcrumb，通过区域脚本绘制。

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

区域脚本

模板原型所使用的区域脚本在STK > Templates /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 > Template Definitions /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节点下限制单个组件对特定角色用户的可用性，用户的角色在Security应用的Roles标签里设定。角色里有更多信息。下列配置样例限制了stkPromo组件仅对superuser角色可用。

• 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+

您可以根据用户的角色定义哪些用户可以编辑，移动，和删除组件。在下列例子里，有着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区域绘制的组件数量。一旦数量达到限制，New Component输入框就会被Maximum Components Reached通知替代，来阻止编辑者添加更多的组件。下列配置样例将base区域的组件数量限制为2。

区域继承

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

组件继承

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

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

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

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

• enabled属性启用和禁用区域继承，对组件继承和属性继承两者皆然。
• components属性有三个选项：
• all配置自动继承。此区域里添加的所有组件都自动延伸到子页面。
• filtered配置选择性继承。此区域内添加的组件只有当组件对话里的Show in subpage框被勾选时才向下延伸。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属性。

比较器类定义了被继承的组件以何种顺序绘制。您可以定义自己的比较器类，只需添加一个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区域可用。参考启用浮动显示中更多信息。

CSS和JavaScript

CSS和JavaScript可在必要时被添加到模板原型中。这个选项在/default/template/prototype配置中并未使用，因为所有必要的样式表和JavaScripts都被包含在缺省的pop主题里了，pop主题在网站定义/theme节点里提到。参考主题和HTML头部区域以获得更多关于标准配置的信息。

以下配置样例在模板原型级别STK > Site Definitions /default/templates/prototype/cssFiles和/jsFiles里添加了一个额外的Javascript和CSS文件。

这个Javascript为页面添加了烟花效果，CSS表改变了头部背景色。注意HTML头部脚本是如何添加额外的JavaScript到head元件的。