扩展stkArticle模板

本教程向您展示了如何通过扩展现有的STK模板来创建一个定制模板。教程扩展了stkArticle模板，您也可以根据需求扩展任何STK模板，只需要调整教程中的步骤即可。教程着重于模板合并过程以及扩展机制的应用，解释了两者的区别。您可以在本页底部下载配置文件。

stkArticle模板特点

stkArticle模板是源模板，所以最好搞清楚它包含的内容，以及它与原型模板的不同。以下是合并配置的一个简要的小结。我们将会修改其中很多内容，所以您可以将它作为一个检查列表。

stkArticle配置来自于两个源模板：

1. 模板原型，为所有的具体模板定义备选配置。stkArticle使用了以下原型配置：
   
   • 未修改部分：
     
     • 页面属性：templateScript=/templating-kit/pages/main.ftl. 
     • 区域：htmlHeader，branding，footer，sectionHeader，extras，promos，base，main/breadbcrumb，以及main/comments。这些区域默认为使能的。
     • 导航：horizontal和vertical。两种导航默认都是使能的。
   • 修改部分：
     
     • 区域：main/intro，/content，和/contentNavigation（见下文）。
       
       
2. 模板定义，定义对原型模板的修改。stkArticle添加、修改了以下原型配置：
   
   • 模板属性：
     

     • bodyID=article.

     • category=content.

     • class=STKPage.

     • dialog=standard-templating-kit:pages/article/stkArticleProperties.

     • modelClass=STKPageModel.

     • renderType=stk.

     • subcategory=article.

     • title=templates.stkArticle.title（到“文章”这个词的关键字）。

     • visible=true.

• • 区域：
    

    • main/intro: dialog=standard-templating-kit:pages/article/stkArticleIntro. 


    • main/content: 6个内容组件和2个要点组件在/availableComponents节点里可用。


    • main/contentNavigation为使能（原型里是禁用的）。

STK文档：

• 模板原型
• 模板定义

创建模板

第一步就是在STK > 模板定义里创建新模板。

1. 在/pages文件夹内创建一个新的内容节点。这是STK里页面模板定义存放的地方。
2. 添加以下两个属性：
   
   1. extends: 将值设置为/modules/standard-templating-kit/templates/pages/stkArticle。这用来告诉Magnolia CMS在新模板里使用stkArtcle模板定义。


   2. title: 输入标题，用在页面应用的模板下拉菜单里，让您在创建测试页时可以找到模板。

在此阶段，我们的模板除了title属性外，是stkArticle模板的完全拷贝副本。

STK文档：

• 页面定义 > extends属性
• 页面属性 > 模板特定属性

使模板可用

第二步就是使模板对系统可用，好让我们使用时能看见它。

模板是在网站定义的templates/availability/templates节点里分配给站点。此节点位于企业版的STK > 网站定义 /default/templates/availability/templates和社区版的/templates/availability/templates里。在此节点里做以下操作：

1. 拷贝stkArticle内容节点，并重命名该节点来匹配新的模板定义。

2. 修改id属性值，使它指向新的模板定义。注意使用<module name>:<path to definition>格式。

   节点名	值
   default
   templates
   prototype
   availability
   templates
   stkArticle
   stkArticleExtension
   id	standard-templating-kit:pages/stkArticleExtension
   stkHome

STK文档：

• 网站定义 > 模板

创建测试页

一旦新模板可用，它就会在页面应用的模板下拉菜单里显示，只需要将visible模板属性设置为true就可以了。stkArticle模板已经这样设置了，所以它的扩展模板也如此。category属性决定模板可以在模板层级中分配到什么位置。新模板从stkArticle处继承了这个属性，属于content分类。这实际上意味着，它可以分配给除了主页外的所有页面，并且不能分配到根页面或2级页面。

在页面应用里创建一个新的测试页，并将新模板分配给它。您也可以视情况在此阶段创建一个子页面结构，用来后续测试依赖页面和组件的行为。

STK文档：

• 模板定义 > 类别和子类

使能platform区域

我们要做的第一个改动就是使能platform区域，并在此区域使能继承（inheritance）。platform区域在原型模板里是完整配置但禁用的，也没有被stkArticle所使用。原型定义区域为list区域，并使stkTeaserPaging组件可用。

要使能platform区域：

1. 在STK > 模板定义，新的/<template name>节点下，创建一个新的内容节点结构/areas/platform。
2. 添加一个enabled属性，值设置为true。
3. 在/areas/platform下创建一个子内容节点/inheritance。
4. 添加两个属性：
   
   1. enabled，值设置为true。
   2. components，值设置为all。这会使可用的组件自动继承到子页面上。你也可以设置为filtered，并在组件对话框中添加一般的inheritable域，允许编辑者选择该组件是否应被继承。

新模板现在包括了platform区域，在breadcrumb后绘制，并跨越main和extras区域。在预览模式里可以看到，breadcrumb得到了很好的绘制。

STK文档：

• 模板定义 > 使能区域
• 区域 > platform区域
• 模板原型 > 组件继承
• 组件 > 要点 > 页面要点
• 可继承组件

修改页面页眉组件

我们的新模板计划用于新闻页面（与标准文章相反），所以我们在/main/intro区域修改页面页眉组件来禁用分类，同时也做了一些其他修改。

要修改页面页眉组件：

1. 在/areas节点下，创建一个新的节点结构/main/areas/intro。
2. 添加以下属性：
   
   1. dialog，将值设置为standard-templating-kit:pages/<template folder>/<intro dialog name>（后续将会创建）。
   2. 为每个您要修改的show属性创建一个节点。这些属性除了showTOC外，在原型里都值都被设置为true。我们的模板里会添加：
      
      1. showCategories，设置为false，禁用分类。
      2. showTOC，设置为true，添加一个目录。
      3. showImage，设置为false，防止组件里绘制图片。

接下来我们会创建一个新对话框来配合intro区域的设置。

要创建一个新对话框：

1. 在STK > 对话框定义 /pages里为模板创建一个新文件夹。
2. 拷贝一个最接近新对话框的现有对话框，并做必要的添加和删除。我们拷贝了stkNewsIntro对话框，重命名为stkArticleExtensionIntro，并删除了image和imageLocation域。
3. 修改对话框定义的label属性和tabMain作为新对话框。这些属性分别绘制为标签卡和对话框标题。

您可以根据喜好添加属性对话框。在这里，我们的模板指向的stkArticleProperties对话框已经可以达到目的了。

这就是新的页面页眉组件和相关的对话框：

• 将会生成一个目录，由content区域里的每个组件标题组成。
• stkArticle模板里可用的tabCategorization在这里不可用。
• Print和Bookmark特性被保留。
• 编辑者可以添加非图片的所有正常内容。我们的对话框包含了stkArticle模板里不可用的location域。

STK文档：

• 区域 > Intro区域
• 对话框定义 > 简介对话框
• 对话框定义 > 属性对话框

改变模板子类 

我们的模板是为新闻页面准备的，所以我们希望使用它的页面包含在绘制news模板子类结果的聚合组件中，这样的STK组件有很多，如stkTeaserNewsList，stkExtrasNewsList，和stkExtrasContentTypeRSSFeed。

要改变模板的subcategory，需要在/<template name>节点添加一个subcategory属性，并将值设为一个新的子类，如本例中的news。

我们将稍后在测试本模板部分演示该属性的使用。

STK文档：

• 模板定义 > 类别和子类

添加一个新区域

下一步，添加一个新区域到main区域里。这个新区域将会包含一个stkTeaserNewsList组件。在新模板里，我们想要此组件在页面的特定位置绘制（content区域下方）。

要创建新区域：

1. 拷贝一个现有区域配置。我们拷贝了stkSection/areas/main/areas/opener配置。
2. 将拷贝的配置放在/areas/main/areas节点下作为子节点，并做必要的修改。
3. 我们的模板里把新区域命名为teaser，这个区域：
   
   1. 是一个single 区域，只能绘制一个组件。
   2. 是可选的（optional），编辑者可以删除它。
   3. 不直接引用一个区域脚本，所以用默认的标准代码绘制它。
   4. 设置title属性值为Teaser，在工具栏里绘制。
   5. 使stkTeaserNewsList组件在/availableComponents节点下可用。
4. 添加一个新templateScript属性到areas/main节点，值设置为一个有效路径。我们接下来将会创建这个脚本，并存放在/templating-kit/pages/custom/mainArea.ftl。

由于/content/mainArea.ftl脚本不包括这个新区域，新模板不能与stkArticle使用相同脚本来绘制main区域。您可以在templates工作区里创建一个新脚本：

1. 在STK > 模板的/templating-kit/pages下创建一个新的子文件夹。我们的文件夹名叫/custom。
2. 拷贝/content/mainArea.ftl脚本并添加到新文件夹。
3. 打开脚本编辑，添加[@cms.area name="teaser"/]到content区域标签符之后。
4. 选中使能模板域以确保脚本是从内容库中获得。

刷新测试页。teaser区域现在在content区域之后绘制，并且stkTeaserNewsList组件是可用的。

STK文档：

• 模板原型 > 区域定义
• 模板原型 > 区域类型
• 模板原型 > 区域脚本
• 模板原型 > 可用组件
• 模板脚本 > 下载脚本
• 模板脚本 > 编辑脚本
• 模板脚本 > cms:area

覆写可用组件

在stkArticle模板里，main/content区域里对编辑者可用的组件包含两个要点：stkTeaserHorizontalTabbed和stkDownloadList。我们想要去除要点，只允许内容组件在区域内。

要去除组件：

1. 在/areas/main/areas节点创建一个新内容节点/content。
2. 添加一个extends属性到新的/content节点并将值设置为override。这会告诉Magnolia CMS忽略stkArticle模板里相应的定义。
3. 拷贝stkArticle/areas/main/areas/content/availableComponents节点，并将其放在新的/content节点下作为子节点。
4. 删除您不想使用的组件。我们删除了stkTeaserHorizontalTabbed、stkDownloadList和STKContact组件。

刷新测试页，并点击main/content区域里的新建内容组件。只有在新模板定义中定义为可用的组件才在选择器对话框中显示给编辑者。

STK文档：

• 模板定义 > 使组件可用

禁用可用组件

stkArticle模板并未修改base区域。此区域内可用的组件是在原型模板里配置的，是模板合并的结果，而不是扩展机制形成的。因此，单个组件可以使用enabled属性删除，extends=override属性则不适用。原型模板使得两个组件可用：stkTeaserCarousel和catCloudWide，在我们的模板里，我们限制这个为单个组件。我们也修改了区域类型（type）以防止编辑者添加超过一个组件。

1. 要在base区域里禁用组件：
   
   1. 在/areas节点，添加一个新内容节点结构/base/availableComponents。
   2. 添加一个子内容节点，将其命名为与原型定义中匹配的名字，在本例中为stkTeaserCarousel。
   3. 添加enabled属性，将值设为false。
2. 为改变区域行为，可以添加两个属性到/base节点：
   
   1. type，其值设为single。在原型里这是一个list区域。
   2. templateScript，其值设为一个有效路径。我们可以在下一步创建此脚本，并将它存放在/templating-kit/pages/custom/baseArea.ftl里。

由于/global/baseArea.ftl是一个标准的list区域脚本，新模板不能使用原型里绘制base区域的脚本。

以与上面的添加一个新区域里同样的方式创建新脚本，使用一下标准single区域代码：

[#if component??]
     [@cms.component content=component /]
[/#if]

刷新测试页，添加一个组件到base区域。只有catCloudWide组件可用。

STK文档：

• 模板定义 > 使组件可用
• 模板脚本 > cms:component
• 区域 > base区域

更改extras区域布局

接下来，我们会更改extras区域的布局，演示一个可用配置选项以及body类和ID的用法。新模板将会使用extras/module区域，这个区域横跨两列，下方有两个extras列。使能module区域会改变页面布局，因此也会改变自动解析的bodyClass。BodyClassResolver Java类会将垂直导航、main和extras算在内，而且必须解析到一个allowedBodyClass。在这个新模板里，我们想要保留垂直导航，在main区域里绘制一个单列，两个extras列。这会自动解析到nav-col-subcol-subcol——不是一个被允许的bodyClass。因此我们在模板里直接定义一个allowedBodyClass，来覆写这个bodyClass。同时也需要禁用promos区域来保证内容适合页面大小。

stkArticle模板不会修改extras区域原型配置。在原型中：

• module区域默认禁用。它是一个single区域，stkExtrasHorizotalTabbed组件是可用的。
• extras1和extras2区域是完全一样的，默认使能，为list区域，区域内有很多可用组件。它们由extrasArea.ftl脚本绘制，columns属性被设置为2时，该脚本仅绘制extras2区域。

更改原型配置：

1. 要改变页面的body类，可以在/<template name>节点里添加一个bodyClass属性，将值设为col-subcol-subcol。这是一个allowedBodyClass。
2. 要使用所有可用的extras子类，在/areas节点下：
   
   1. 添加一个新的子内容节点/extras。
   2. 添加三个属性：
      
      1. class，将其值设置为info.magnolia.module.templatingkit.templates.ExtrasArea。添加该属性是必要的，因为原型定义了一个与默认类不同的类。
      2. columns，将值设置为2。这更改了原型中配置的1。
      3. small，将值设置为false。这更改了原型中配置的true。
3. 要使能module区域：
   
   1. 在/areas/extras节点下，添加一个新的内容节点结构/areas/module。
   2. 添加enabled属性，将值设为true。
4. 要禁用promos区域：
   
   1. 在/areas节点添加一个新的子内容节点/promos。
   2. 添加enabled属性，将值设为false。

刷新页面。extras区域使用了所有可用的子区域。

激活后，在HTML的body元素里，body id="article" class="col-subcol-subcol"。body ID元素包含了article属性（attribute），并使用stkArticle模板里分配的bodyID属性（property）。所有的内容模板都使用这个ID。class属性（attribute）包含新模板定义的bodyClass属性（property），您可以将它与基于stkArticle模板的页面上的这个元素进行比较。由于页面解析到nav-col-subcol的缺省bodyClass，class属性（attribute）没有添加。以下截图就是公共实例上看到的激活后的测试页面。

STK文档：

• CSS概念 > Body类和ID
• 模板原型 > 区域类
• 区域 > extras区域

添加一个自动生成的组件

接下来我们要添加一个自动生成的stkHTML组件，在extras/module区域绘制一个嵌入视频。这个视频将会在每个使用此新模板的页面上的该区域绘制。为防编辑者删除或改变这个自动生成的组件，我们也要禁用原型里可用的stkExtrasHorizotalTabbed组件，并使此区域不可编辑。

1. 要在module区域里添加一个自动生成的组件：
   
   1. 在/areas/extras/areas/module节点里，添加一个新内容节点结构/autoGeneration/content/<name>。您可以随意命名此组件（例如本例中用了magnolia5）。
   2. 添加一个generatorClass属性到/content节点，值设置为info.magnolia.rendering.generator.CopyGenerator。
   3. 添加三个属性到/<name>节点：
      
      1. editHTML，在值列里插入HTML代码。
      2. nodeType，将值设为mgnl:component。
      3. templateId，将值设为standard-templating-kit:components/content/stkHTML。
2. 要禁用原型组件：
   

   1. 在/areas/extras/areas/module节点里，添加一个新内容节点结构/availableComponents/stkExtrasHorizontalTabbed。

   2. 添加enabled属性，将值设置为false。

3. 为使该区域不可编辑，添加一个editable属性到/areas/module节点，并将值设置为false。

刷新测试页。自动生成的组件在module区域里绘制，并且区域工具栏不再出现。

STK文档：

• 模板定义 > 自动生成的组件
• 模板定义 > 特色组件

其他模板属性

stkArticle模板有其他的页面属性，我们在新模板里没有使用。新模板继承了这些属性，我们选择不去改变它们。这里是对每个属性的简短讨论：

• class：所有的STK模板使用STKPage类（class），定义基本模板定义。
• modelClass：大部分STK模板使用扩展STKPage的STKPageModel模型类（modelClass）。您可以扩展这个类，以提供定制的业务逻辑。关于如何达到这个目的的例子可参考stkRedirect和stkGlossary模板，这两个模板使用扩展了STKPageModel的modelClasses。
• category：该属性决定模板会被分配到页面层级的什么位置。可选的有：home，functional，section，feature，content。我们保留content是因为它适用于模板，您也可以修改此属性来试验一下。
• dialog：每个模板引用在STK > 对话框定义里配置的它自己的stk<template name>Properties对话框。除了stkHomeProperties外，这些对话框在两个版本是一样的，都扩展了/generic/master文件夹的basePageProperties配置。tabDependencies是一个企业版特性，htmlHeader.ftl脚本绘制编辑者在tabMetaData输入的管理信息（keywords和description）。例如，您可以扩展该对话框和脚本来包含robots标签符。
• renderType：值为stk时分配的STKRenderer为STK特定绘制符，为所有STK模板所使用（页面和组件）。

STK文档：

• 模板定义 > 模板属性

添加CSS

您可以在模板级添加模板特定的样式。为方便演示，我们添加一些样式规则到页面页眉组件里绘制的新目录。您很少需要这样做，更好的做法是在STK > 资源 /templating-kit/themes/pop/css里修改主CSS文件styles.css。

添加模板特定CSS：

1. 在/<template name>节点添加一个新内容节点结构/cssFiles/<name>。在我们的例子里，name=extensionStyles，您可以根据自己的喜好命名此节点。
2. 添加三个属性：
   
   1. farFutureCaching，将值设为true。
   2. link，将值设为到新样式表（将要创建）的路径（path）。您可以指向任何有效的内部或外部URL。
   3. media，将值设为一个有效的媒体类型。

您可以在resources工作区里创建新的CSS表格：

1. 在STK > 资源里，创建一个新的Processed CSS类型的项并取名。我们的样式表叫做articleExtensionStyles.css。
2. 编辑此新项并在对话框中插入样式规则。
3. 保存。

新样式表将会自动从内容库中下载。在编辑对话框的高级标签里有一些其他选择，您可以自由发掘。

这是激活到公共实例上的测试页。您可以看到，htmlHeader.ftl脚本添加了新样式表到HTML的head元素中去，所以新的样式将会在页面上绘制。

STK文档：

• 区域 > htmlHeader区域 > CSS和JavaScript
• 主题
• 资源

添加JavaScript

您也可以在模板级添加模板特定的JavaScript，与添加样式方法一样。您也很少需要这样做，因为pop主题包括了所有您最有可能需要的。为方便演示，我们添加了一个脚本，使能一个无限循环里的定时事件。您可以在w3schools.com上找到代码（Javascript和HTML的）。

为添加模板特定的JavaScript：

1. 在/<template name>节点添加一个新内容节点结构/jsFiles/<name>。在本例中，name=timer，您也可以根据喜好命名此节点。
2. 添加两个属性：
   
   1. farFutureCaching，值设置为true。
   2. link，值设置为到新脚本（将要创建）的路径（path）。您可以指向任何有效的内部或外部URL。

您可以在resources工作区里创建新的JavaScript：

1. 在STK > 资源里，创建一个新的Processed Javascript类型的项并取名。我们的样式表叫做timer.js。
2. 编辑此新项并粘贴脚本到对话框中。
3. 保存。

htmlHeader.ftl脚本添加新脚本到HTML的head元素。我们会在测试本模板 > JavaScript中演示这个JavaScript的使用。

STK文档：

• 区域 > htmlHeader区域 > CSS和JavaScript
• 主题
• 资源

测试本模板

这是源stkArticle模板的主体部分与新的stkArticleExtension模板的对比。

下一步我们将会添加测试内容到测试页和子页，确保所有的区域和组件都如期望的一样表现、绘制。

platform区域

stkTeaserPaging组件不能填满整个platform区域，因此需要很小的CSS调整。简便起见，我们可以在添加CSS步骤里添加的样式表里，添加修改的样式规则。理想情况下，您需要修改STK > 资源 /templating-kit/themes/pop/css下的主样式表styles.css。您可以在/* ### TW-PAGING ### */..../* Inside #wrapper-2 -> Platform Area */段找到相关的规则。我们使用了子测试页来做内部要点项，并且确认了该组件被所有子页面继承。这就是修改的组件。

intro区域

这是页面页眉组件，其中修改了样式和文字和图片内容组件。

main里的teaser区域

新的main/teaser区域绘制了stkTeaserNewsList组件。这个组件同时也含有基于新模板子类（subcategory）的子页面。

contentNavigation区域

contentNavigation区域在stkArticle模板里是使能的，因此在新模板中也使能。该区域在页面页眉组件上方绘制，允许用户导航至页面层级很深的页面。

STK文档：

• 区域 > contentNavigation区域

extras区域

我们的模板有两个extras列，都比默认的单列窄。我们只收到stkExtrasCalendar组件的一个样式错误，所以我们返回到新模板的extras2区域里禁用了它。

JavaScript

为测试我们的JavaScript，我们使用以下代码，在main/content区域添加了一个stkHTML组件：

<form>
<input type="button" value="Start count!" onclick="doTimer()" />
<input type="text" id="txt" />
<input type="button" value="Stop count!" onclick="stopCount()" />
</form>
<p>
Click on the "Start count!" button above to start the timer. The input field will count forever, starting at 0. Click on the "Stop count!" button to stop the counting. Click on the "Start count!" button to start the timer again.
</p>

这是我们的测试组件。如果没有添加timer.js脚本，计时器不会工作。

下载模板

下载stkArticleExtension模板.zip，并导入XML到demo-project网站和配置。