STK具体页面模板和组件模板定义在STK > Template Definitions下配置。
节点名 | 值 |
---|---|
pages | |
components |
页面定义
所有STK页面模板的具体模板定义都在STK > Template Definitions /pages
里配置。
节点名 | 值 |
---|---|
pages | |
demo-features | |
stkHome | |
stkSection | |
stkArticle |
这些模板可供编辑者在Pages应用里选择使用。它们可以出现在Pages应用的Template域里,只需要:
在通用属性里,visible
属性设置为true
。- 模板在缺省网站定义或企业版里任意其他网站定义里可用。
- 编辑者的权限已经足够获取特定的模板了。基于
role
的限制可利用原型里的/availability/<template name>/roles
节点来添加。
可用的模板在不同的页面级别是不同的。例如,stkHome
和stkRedirect在级别1可用
,而stkSection
和其他的则在级别2可用等。以下的类别和子类有关于如何实现网站层级的更多信息。
所有具体的页面模板都是基于模板原型的。原型包含了缺省结构和行为,以及具体的对原型配置的例外,添加物,以及覆写的定义。参考模板合并里的样例以了解它是如何工作的。
为了能使系统识别,模板定义里的配置结构需要与模板原型里相应的配置一样。比较模板prototype和下面的
stkEvent
模板里关于infoBlock
区域的配置,注意两者的节点结构是相同的。
模板原型
节点名 | 值 |
---|---|
default | |
templates | |
prototype | |
areas | |
main | |
areas | |
intro | |
areas | |
infoBlock |
模板定义
节点名 | 值 |
---|---|
pages | |
stkEvent | |
areas | |
main | |
areas | |
intro | |
areas | |
infoBlock |
为使模板独一无二,您可以在模板定义里:
- 覆写原型里的大多数属性和内容节点配置。
- 为原型配置添加物。添加物为原型里所没有的新配置,能够添加功能,区域,组件,以及其他特性。
没有硬性的快速规则。在典型安装里,模板原型里应包含的配置,与具体模板相比,是一个较为实用而非技术化的选择。
对原型的修改可以在以下级别进行:
- 页面级,如引用一个新的
templateScript
。以下讨论的stkRedirect
模板就是这样的一个例子。 - 导航级,通过修改缺省导航配置或编写一个全新的。这通常不是必须的,但适用于特殊定制的模板。
- 区域级,通过引用不同的脚本并改变区域行为。参考main区域样例。
- 变异形式级,通过为特定模板禁止区域,好让区域为特定变异形式绘制。参考移动性以了解这个选项是如何用在
stkHome
模板的stage
区域里的。 - JavaScript和CSS级,通过引用不同的CSS表或JavaScript。此选项通常不是必须的,无论在原型还是具体模板定义里都不会使用,不过以下的CSS和JavaScript是一个配置样例。
模板属性
多数模板属性是在具体模板级别分配的,它们能够区分不同的模板。
Reference部分的页面>属性里有可用的模板属性的完整列表及其用法。
通用属性
模板原型里分配的唯一一个对所有具体模板都可用的属性是templateScript
,它引用管理页面脚本,main.ftl。
除了这一个例外,以下通用属性为所有STK模板所用:
class
节点里分配的STKPage
定义基本模板定义。modelClass节点里分配的STKPageModel
为基本页面模型,提供页面级功能。它扩展STKPage
。
为STK专用绘制器,被所有STK模板(页面和组件)使用。值为
stk的
renderType节点分配的
STKRenderer- 国际化关键字,
info.magnolia.module.templatingkit.messages
,在i18nBasename
节点下分配。这也是指向包含STK翻译的消息包的关键字。 设置为
true
的visible
属性使模板在Pages应用里对编辑者可用。节点名 值 pages
stkArticle
areas
bodyID article category content class info.magnolia.module.templatingkit.templates.pages.STKPage dialog standard-templating-kit:pages/article/stkArticleProperties i18nBasename info.magnolia.module.templatingkit.messages modelClass info.magnolia.module.templatingkit.templates.pages.STKPageModel renderType stk subcategory article title templates.stkArticle.title visible true
有两个例外:
stkGlossary
模板使用它自己的modelClass
,GlossaryTemplateModel
,来扩展STKPageModel<STKPage>,完成字母序排列的术语表
。节点名 值 pages
stkGlossary
areas
bodyID
glossary category
feature class
info.magnolia.module.templatingkit.templates.pages.STKPage dialog
standard-templating-kit:pages/glossary/stkGlossaryProperties i18nBasename
info.magnolia.module.templatingkit.messages modelClass
info.magnolia.module.templatingkit.templates.GlossaryTemplateModel renderType
stk subcategory
glossary title
templates.stkGlossary.title visible
true
stkRedirect
模板使用它自己的:modelClass
:RedirectTemplateModel
用于扩展STKPageModel
并提供3个交替的重定向模式,这三个模式取决于编辑者设置的path
值:- 如果在对话里输入了内部路径或外部URL,用户将会直接被重定向过去,绘制被跳过,以避免写入响应。
- 如果没有输入路径,那么页面重定向至找到的第一个子页面。这对于直接显示一个在重定向树的二级或三级定义的页面是很有用的。
templateScript
:redirectMain.ftl
在页面上正确地绘制路径。您可以在STK > Templates/templating-kit/pages/functional/redirectMain.ftl
里查看脚本。节点名 值 pages
stkRedirect
areas
bodyID
redirect category
functional class
info.magnolia.module.templatingkit.templates.pages.STKPage dialog
standard-templating-kit:functional/stkRedirect i18nBasename
info.magnolia.module.templatingkit.messages modelClass
info.magnolia.module.templatingkit.templates.RedirectTemplateModel renderType
stk subcategory
redirect templateScript
/templating-kit/pages/functional/redirectMain.ftl title
templates.stkRedirect.title visible
true
在页面编辑器里,页面上绘制到内部或外部重定向的路径,但在预览里,则由目标页面绘制。/demo-project/service/m5-campaign
页面基于stkRedirect
模板。
模板特定属性
以下属性因每个模板而不同:
bodyID
:这是专为模板的样式准备的CSS表所用的标签。参考Body类和ID以获得更多信息。bodyID
和subcategory值常常会一致,但它们彼此之间没有相通的关系。
category
和subcategory
:每个模板都会被分配一个类别,大多数也会被分配一个子类。类别被用在很多场合,参考下面的类别和子类。dialog
:每个页面模板会连接到它自己的stk<Template name>Properties
对话,这个对话在STK > Dialog Definitions/pages
里配置。每个页面顶部工具栏里的Properties按钮可以打开此对话,用来控制浏览器标题和导航标题及行为,页面管理数据(关键字和描述),变异排除和页面依赖性。详细信息参看属性对话。title
:在Pages应用的Template域里显示的模板标题。节点名 值 pages
stkImageGallery
areas
bodyID
image-gallery category
feature class
info.magnolia.module.templatingkit.templates.pages.STKPage dialog
standard-templating-kit:pages/imageGallery/stkImageGalleryProperties i18nBasename
info.magnolia.module.templatingkit.messages modelClass
info.magnolia.module.templatingkit.templates.pages.STKPageModel renderType
stk subcategory
imageGallery title
templates.stkImageGallery.title visible
true
extends
属性
扩展机制被用来最小化配置。该机制类似单个模板定义和原型定义之间的关系,只不过它很直观。只有修改,例外,和添加物才在扩展配置中配置,其他所有配置都照搬基本配置。
内容模板,也就是stkLargeArticle
,stkNews
,stkEvent和
stkGlossaryTerm
,都是组成基本配置的stkArticle
模板的扩展。您可以使用此机制轻松创建与缺省的STK模板类似的定制模板。
节点名 | 值 |
---|---|
pages | |
stkArticle | |
stkLargeArticle | |
stkNews | |
areas | |
dialog | standard-templating-kit:pages/news/stkNewsProperties |
extends | /modules/standard-templating-kit/templates/pages/stkArticle |
subcategory | news |
title | templates.stkNews.title |
相似地,/pages/demo-features
里的模板都是stkSection
模板的扩展。这些模板展示了您可以通过配置来改变页面布局的多种途径。您可以在demo-features站点的Section Variations里看到。
节点名 | 值 |
---|---|
pages | |
demo-features | |
stkSectionNoExtras | |
areas | |
extends | /modules/standard-templating-kit/templates/pages/stkSection |
title | Section no Extras |
stkSectionNoHeader | |
stkSectionFloating |
extends属性也可被设置为
override
来覆写部分扩展配置。参考以下的使组件可用中的样例。
类别和子类
每个STK页面模板都属于一个类别,除stkHome
和stkRedirect
以外的所有模板都有一个子类(subcategory
)。类别使您能够控制模板可被用在网站上的什么位置。如果一个模板类别不被允许在网站结构的指定位置出现,它将不会对编辑者可用。分类机制因此确保了模板分配的一致性,并使您的网站有一个可控的结构。
类别建立了一个隐含的模板层次结构,它们定义哪个模板可被分配到一个页面。例如,stkHome
模板属于home
分类。home
分类只能被用于网站的根页面。同样地,content
分类的模板只能被用在位于使用section
,feature
,或functional
类模板页面下的页。
子类别用于内容聚合。例如,系统在news子类别里聚合了所有页面,以生成一个新闻要点的列表。
RSS种子的生成就是一个例子。
以下五个模板类别非常符合STK模板的计划用途。
类别 | 描述 | 类别里的模板 |
---|---|---|
home | 网站的根页面。 | stkHome |
functional | 执行操作而非生成内容的特定模板。 | stkRedirect |
section | 组成网站的章节。demo-project站点有诸如新闻( News),事件(Events),和服务(Service)的章节。您的也可以是产品(Products),服务(Services),以及支持(Support)。 | stkSection (包括/demo-features 里的变异形式 ), stkGlossaryLetter |
feature | 特定模板和收集或聚合内容的模板。 | stkForm stkFormStep stkImageGallery stkFAQ stkPublicUserRegistration stkSearchResult stkSiteMap stkGlossary stkNewsOverview stkEventsOverview stkCategoryOverview |
content | 核心内容页面。 | stkArticle stkLargeArticle stkNews stkEvent stkGlossaryTerm |
模板的可用性和层次结构都由STKTemplateAvailability
类来控制,这个类同时也实现TemplateAvailability
包装类。后者包含网站上可用的模板列表。可用性首先在网站定义的/template/availability
节点下配置,其次是通过类别配置。类别的可用性逻辑被硬编码方式写入TemplateCategory
里,它们不可以不通过扩展此类就直接声明。TemplateCategoryUtil
为使用模板的类别添加实用方法。子类别不是固定的,您可以在模板定义里直接设置它们。
硬编码的缺省类别可用性逻辑为:
只有home
和functional分
类可以被分配给网站的根页面。
home
在每个页面只可以被分配一次。您可以定义很多主页模板,如有着不同的列布局的模板,都属于home分
类,但您一次只可以分配它们当中的一个。functional
可以被分配给任意页面,无论父模板的类别如何。这就意味着,比如,您可以在网站的任意位置有一个重定向页面等。section
只可以被分配给父页面类别为home
,section
,functional
,或feature
的页面。换句话说,它可以被分配给除父页面为content
页以外的所有页面。content
可以被分配给父页面类别为
,section
,content
,或functional
的页面。换句话说,它可以被分配到除主页外的所有页面下。feature
feature可以被分配给父页面类别为
,section
,content
,或functional
的页面。换句话说,它可以被分配到除主页外的所有页面下。feature
区域定义
区域定义很强大,您在定义里可以找到很多模板独特的配置。本小节概述了区域定义通常是如何使用的。为了演示方便,我们提供一些添加功能和特性的样例,来演示具体模板与模板原型的不同。STK区域里有对每个区域更深层的讨论。这些样例展示了系统的灵活性,但并不详尽。您可以把它们综合起来创造出更多的可能。
引用对话
区域定义可以引用对话。该选项用在所有具体模板(除了stkHome
)的main/intro
区域,来引用模板专用的属性对话。参考intro区域以获得更多信息。
节点名 | 值 |
---|---|
stkSection | |
areas | |
main | |
areas | |
intro | |
class | info.magnolia.module.templatingkit.templates.MainAreaIntro |
dialog | standard-templating-kit:pages/section/stkSectionIntro |
divID | page-intro |
showAuthorDate | false |
showTextFeatures | false |
使组件可用
模板原型使组件在区域内可用,区域里的所有模板有同样的一套组件是合理的。促销区域(extras
,promos
,和base
)便是这样的例子。main/content
区域比较特别,在这里组件对具体模板可用。
组件可被添加到任何list
或single
区域。详细信息可参考区域类型。
您可以添加组件到任意模板的/areas/<area name>/availableComponents
节点。以下的配置添加了stkTextImage
和stkQuotedText
组件到
模板的stkArticle
区域。加上原型使promos
stkPromo
组件可用,这样就共有三个组件在stkArticle
里可用了。
节点名 | 值 |
---|---|
stkArticle | |
areas | |
promos | |
availableComponents | |
stkTextImage | |
id | standard-templating-kit:components/content/stkTextImage |
stkQuotedText | |
id | standard-templating-kit:components/content/stkQoutedText |
不是所有组件在所有区域里都能很好的绘制,您可能需要修改CSS表或组件定义。例如,在以上配置中,stkQuotedText
将不会获得CSS表在promos
里使用的背景字体或quote.png
图片,正如它在main/content
区域里一样。
如果您想要减少原型里可用的组件数量,您可以使用enabled
属性来禁用特定组件。注意extends=override
属性不能用于这种情况,因为模板合并不依赖于扩展机制。
以下的配置样例使用了stkEventsOverview
模板。
- 该模板不是任何其他模板的扩展。
/areas/promos/availableComponents
节点的添加使Magnolia CMS了解对原型的修改是在此区域配置的。/availableComponents/stkPromo/enabled
节点禁用此区域的stkPromo
组件。/availableComponents/stkExtrasContact节点使
stkExtrasContact组件取代
stkPromo组件
可用。
节点名 值 stkEventsOverview
areas
promos
availableComponents
stkPromo
enabled false stkExtrasContact
id standard-templating-kit:components/extras/stkExtrasContact
这里是/demo-project/news-and-events/events-overview
页面上的新组件。
如果您想要使不同的组件在扩展了另一模板的模板里可用,您可以使用extends=override
属性。
下列配置样例使用了stkNews
模板:
- 该模板是
stkArticle
模板的一个扩展。这是在/stkNews/extends
节点下配置的。 - 添加
/areas/content/extends
属性并设置为override
,就会告诉Magnolia CMS忽略(覆写)stkArticle
模板里的/areas/content
配置。这个配置使得8种内容组件可用。 添加
/areas/content/availableComponents
节点使得stkNews
模板里只有stkTextImage
组件可用。节点名 值 stkNews
areas
main
areas
content
availableComponents
stkTextImage
id standard-templating-kit:components/content/stkTextImage extends override dialog standard-templating-kit:pages/news/stkNewsProperties extends /modules/standard-templating-kit/templates/pages/stkArticle subcategory news title templates.stkNews.title
限制组件使用
您可以在模板定义里限制任意区域内可用组件的使用权。stkArticle
模板里有一个配置样例,限制了只有被分配了superuser
角色的用户可以使用stkHTML
组件。任何有着较少权限的用户都不可以使用该组件。此项配置在STK > Template Definitions /pages/stkArticle/areas/main/areas/content/availableComponents/stkHTML
里:
roles
内容节点警告Magnolia CMS可能的使用限制。值也为
superuser
的superuser
数据节点限制了只有被分配了superuser
角色的用户才能使用组件。参考角色里的详细信息。节点名 值 stkArticle
areas
main
areas
content
availableComponents
stkHTML
roles
superuser superuser id standard-templating-kit:components/content/stkHTML stkTextImage
stkQuotedText
您可以这样来测试,以样例编辑者Eric(username/password=eric
)的身份登录,并尝试添加stkHTML
组件到任何文章页面的content
区域。stkHTML
组件在选择器对话里不可用。
4.5.9 + 引入了两个有关组件可用性的新特性。它们以与原型模板里相同的方式在模板级别上配置。您也可以:
- 用
maxComponents
属性限制编辑者能够添加到区域里的组件数量。 - 基于分配给用户的角色,定义细粒度的行为限制。参考限制组件动作以获得更多信息。
修改区域行为
main/content区域是把模板区别开的主要因素。在模板原型里,该区域被定义为type=list
,缺省情况下允许无数量限制的添加有序组件。
stkHome
,stkSection
和内容模板保持缺省类型。在/areas/main/areas/content/availableComponents
节点里,要点在stkHome
和stkSection
模板里可用,内容组件在内容模板(stkArticle
)里可用。节点名 stkHome
areas
main
areas
content
availableComponents
stkTeaser
stkTeaserNewsList
stkTeaserEventsList
stkTeaserGroup
stkTeaserHorizontalTabbed
stkTeaserPureLinkList
节点名 stkArticle
areas
main
areas
content
availableComponents
stkTextImage
stkQuotedText
stkLinkList
stkFlash
stkVideo
stkTeaserHorizontalTabbed
stkDownloadList
stkContact
特性模板覆写了缺省类型,将其改为
single
。该特性组件在/areas/main/areas/content/autoGeneration/content/singleton
节点里添加。参考以下的特色组件和自动生成的组件以获得更多信息。节点名 值 stkImageGallery
areas
main
areas
content
autoGeneration
content
singleton
maxImages 9 nodeType mgnl:component templateId standard-templating-kit:components/features/stkImageGallery generatorClass info.magnolia.rendering.generator.CopyGenerator type single
使能区域
大多数区域在原型里是使能的,因此需要在特定的模板定义里禁用,以改变缺省设置。这是通过将/areas/<area name>
内容节点下的enabled
属性节点值设置为false
实现的。类似stage
或platform
这样很少使用到的区域在原型里是不使能的。这种情况可以设置enabled
属性值为true
来改变缺省行为。
使能或禁用区域:
决定整个区域绘制或不绘制,无论区域包含诸如组件的内容,自动生成的内容,还是脚本绘制的内容。内容会保留在内容库中,并且当一个之前被禁用的区域被重新使能后,将会再次绘制。您可以通过在
stkArticle
模板上禁用extras
,并在Tools > JCR里查看任何文章页来验证。模板定义
节点名 值 stkArticle
areas
extras
enabled false bodyID article JCR浏览器(网站)
节点名 值 demo-project
about
subsection-articles
article
extras
extras1
0
00
- 将会对模板扩展与对基本模板有同样的效果。例如,如果您在
stkArticle
上禁用extras
,这样将会在所有内容模板上都禁用该区域。添加enabled
属性并在您想要包含该区域的模板扩展上将其设置为true
,就可以修改了。 - 可能会影响页面布局。以下的结果主要是由于页面排列和内容包装的方法造成的。这里是一些样例:
- 当
extras
被禁用时,main
区域会展开,以使用可用空间。 - 当
promos
被禁用时,可用空间里什么都不会绘制。 - 当
base
,stage
,或是sectionHeader
被禁用时,内容会上移绘制,就像被禁用的区域不存在一样。同样的行为也发生在区域被使能但不包含任何内容的预览模式里。下面的截图为禁用了stage
的stkHome
模板。
- 当
- 当浮显(
floating
)在main
区域里被使能,并列数设置为2
时,main
区域里的第二列只会在extras
被禁用时绘制。下面的截图展示了基于/demo-features/stkSectionFloating
模板的demo-features/section-variations/floating
页面。
- 当浮显(
添加区域
在模板定义里,您可以添加模板原型里没定义的区域。stkSection
模板的main区域会创建一个新的嵌套区域,opener
区域。
以下对原型配置的修改与新的opene
r区域有关:
/areas/main
节点:- 使用它自己的类,
SectionMainArea
,用来定义opener
区域属性。 - 由
/section/mainArea.ftl
脚本绘制,该脚本与缺省的/global/mainArea.ftl
脚本除了使用[@cms.area name="opener"/]
标签添加了opener
区域外完全相同。 /areas/main/areas/opener
节点:- 配置新
opener
区域。 - 是一个只能绘制一个组件的
single
区域。 - 是
enabled
和optional
的,意味着它虽然可用,但编辑者可能会选择删除它。 - 由
/section/opener.ftl
这个标准的single
区域脚本绘制。 使
stkTeaserOpener
组件在availableComponents
节点里可用。节点名 值 stkSection
areas
main
floating
areas
intro
opener
availableComponents
stkTeaserOpener
id standard-templating-kit:components/teasers/stkTeaserOpener description areas.templates.main.opener.description enabled true optional true templateScript /templating-kit/pages/section/opener.ftl title areas.templates.main.opener.title type single content
class info.magnolia.module.templatingkit.templates.SectionMainArea templateScript /templating-kit/pages/section/mainArea.ftl
使能浮显
浮显就意味着该区域内的组件在指定数目的列里绘制。缺省情况下,浮显在stkHome
和stkSectionFloating
模板的main
区域内是使能的。demo-project
主页和demo-features/section-variations/floating
页面就是建立在这些模板之上的。这里就是demo-project
主页的main
区域。
浮显是在模板定义的<template name>/areas/main
内容节点里配置的。在STK > Template Definitions /pages/stkHome
的stkHome
模板下:
/areas/main:
- 使用
SectionMainArea
类定义浮显属性。 - 由
section/MainArea.ftl
脚本绘制,简单的绘制所有嵌套区域。 areas/main/floating
里:enabled
节点被设置为true
来使能浮显。您可以将此属性设置为false
来禁用。- 列数设置为
3
,告诉Magnolia CMS在三列中绘制组件。可用的选项有1
,2
,和3
。由于其他嵌套区域都被禁用,只有在/areas/main/areas/content/availableComponents
节点下可用的组件会在main
区域里绘制。 areas/main/areas/content
:- 使一些要点组件在
/availableComponents
节点里可用。这些组件被配置在一个浮显区域内工作(参看下表)。 - 由
section/contentArea.ftl
脚本绘制。该脚本包含绘制teaserCount
的代码(参看下表)。 /areas/main/areas/intro
,/opener
和/breadcrumb
被禁用了,意味着在此模板上,浮显只出现在/areas/main/areas/content
里。禁用其他嵌套区域不是严格必须的。/areas/extras被禁用,以确保此页解析到一个allowedBodyClass
里(参看下表)。节点名 值 stkHome
areas
main
floating
columns 3 enabled true areas
content
availableComponents
templateScript /templating-kit/pages/section/contentArea.ftl title templates.stkHome.areas.main.content.title intro
class info.magnolia.module.templatingkit.templates.MainAreaIntro enabled false opener
breadcrumb
class info.magnolia.module.templatingkit.templates.SectionMainArea templateScript /templating-kit/pages/section/mainArea.ftl extras
inheritance
class info.magnolia.module.templatingkit.templates.ExtrasArea enabled false
缺省情况下,您可以扩展stkHome
和stkSection
模板来配置一个浮显模板,因为它们都使用SectionMainArea
类和要点组件。其它的场景需要定制。STK > Template Definitions /pages/demo-features/stkSectionFloating
里的stkSectionFloating
模板就是扩展stkSection
模板的一个例子:
- 此模板在
stkSectionFloating/extends
节点下扩展stkSection
模板。通过扩展: - 合适的要点组件在
/areas/main/content/availableComponents
节点下可用。 - 使用
SectionMainArea
类。 - 在
/areas/main/floating
节点,floating
被使能且列数设置为2
。 - 在
/areas/main/areas
节点,intro
和opener
区域被禁用。 在
/areas/extras
节点,extras
区域被禁用。节点名 值 pages demo-features
stkSectionFloating
areas
main
floating
columns 2 enabled true areas
intro
enabled false opener
enabled false extras
inheritance
class info.magnolia.module.templatingkit.templates.ExtrasArea enabled false base
extends /modules/standard-templating-kit/templates/pages/stkSection title Section Floating
这就是基于stkSectionFloating
模板的公共实例上的demo-features/section-variables/floating
页。该页解析到body
元素里包含的一个属性(attribute)allowedBodyClass=nav-col-float2
里。main
区域的每个要点都被包在一个DIV元素内。
为确保浮显被使能后组件能够正确绘制,需要考虑以下几点因素:
BodyClassResolver
Java类自动解析此页的bodyClass
。区域应在需要时被使能或禁用,以确保页面解析到一个allowedBodyClass
。参看body类以获得更多信息。- CSS表格引用此
bodyClass
以保证正确的样式。 - 当浮显列数被配置后,
teaserCount
会告诉Magnolia CMS哪里可以绘制每个要点。参看Teaser IDs以获得更多信息。 - 每个要点定义的配置都有一个
divId
和一个divIdPrefix
属性来辅助teaserCount
。 - 单个组件脚本里的FreeMarker代码分配一个要点ID和
section/contentArea.ftl
脚本来在此区域里绘制teaserCount
。
变异形式
变异形式用于某些特定用途,例如重新设计智能手机和平板这样的设备的内容格式,或已登录用户组的特定输出等。参看移动里关于演示站点里用到的智能手机变异形式样例的详细讨论,以及通知里关于此核心功能的更多信息。
变异形式通常在变异形式里配置,但只可以在模板定义里模板级别上配置。参看舞台里关于该选项是如何在智能手机上禁用stage
区域的例子。
4.5.3 +
在页面模板级别,您可以配置一个由页面URL扩展触发的变异形式。注意这种变异形式不可在网站定义里配置。
在以下的配置样例中,newsletter
变异形式禁用了sectionHeader
,extras
,promos
,和base
区域,只剩主要内容。这个变异形式可能适用于如新闻简报的在线版或页面的打印版。
节点名 | 值 |
---|---|
pages | |
stkSection | |
areas | |
variations | |
newsletter | |
areas | |
sectionHeader | |
enabled | false |
extras | |
enabled | false |
promos | |
enabled | false |
base | |
enabled | false |
如果您在基于stkSection
模板的任何页面上请求内容,将扩展名从.html
改为.newsletter
,变异内容就出现了。
您可以将这个与网站定义里配置的smartphone
变异结合起来,只需要添加?mgnlChannel=smartphone
参数来使newsletter
变异形式为适合智能手机的格式。
变异形式通过DefaultRenderableVariationResolver
解析,这个解析器是ChannelVariationResolver
和ExtensionVariationResolver
的结合。
此功能需小心使用,因为它允许用户通过改变URL扩展名来获取内容。如果要用于敏感内容,那么可以考虑通过扩展DefaultRenderableVariationResolver
来提供额外的安全措施。
CSS和JavaScript
您也可以为单个模板在模板定义里引用模板专用的CSS表格和JavaScripts。此选项对如网站的节假日活动或专用章节可能会有用。
下列配置样例分配一个专有CSS表格和一个附加JavaScript到stkArticle
模板。
节点名 | 值 |
---|---|
pages | |
stkArticle | |
cssFiles | |
articleStyles | |
farFutureCaching | true |
link | /resources/templating-kit/css/articleStyles.css |
media | screen |
jsFiles | |
fireworks | |
farFutureCaching | true |
link | /resources/templating-kit/js/fireworks.js |
组件定义
组件是页面上最小的内容块。STK包括用于所有使用案例的组件,和从简单的文本组件到复杂的聚合要点等可用组件。单个组件在组件页上讨论。
组件定义在STK > Template Definitions /components
里配置。定义以文件夹的形式排列,文件夹名表示组件类型。
节点名 | 值 |
---|---|
components | |
content | |
teasers | |
extras | |
promos | |
stkPromo | |
features | |
links | |
stages | |
footer | |
pur |
组件定义与页面定义相似,都使用同样的模板定义对象。页面和组件使用相同路径语法引用它们的对话。此外,页面和组件使用相同的绘制工具绘制。
在很多时候,都不需要从头开始创建一个新组件,您可以拷贝或扩展现有的,并按您的需要调整。
通常创建新组件包括以下几步:
- 创建一个对话。
- 创建一个组件定义。
- 创建一个组件脚本。
- 使组件对组件脚本可用。
组件可用于编辑者通过STK > Dialog Definitions里配置的相关组件对话输入内容。对话定义通过对话属性映射到组件定义里。
大多数组件在模板原型或具体页面模板定义的区域定义里被分配给页面模板。
组件模板属性
所有的STK组件定义都有以下属性:
description
:指向组件描述的消息包关键字。dialog
:到对话定义的路径,有着<module name>:<path to definition>
结构。大多数STK对话都在STK > Dialog Defintions下配置。118nBasename
:国际化关键字,info.magnolia.module.templatingkit.messages
,指向包含STK翻译的消息包。renderType
:值为stk时
分配的STKRenderer
是一个STK专用的绘制器,为所有的STK模板(页面和组件)所使用。templateScript
:指向绘制组件的脚本的路径。组件脚本在STK > Templates/templating-kit/components
下。title
:在组件工具栏里绘制的组件标题。deletable
决定组件是否能被删除。如果设置为false
,那么Delete component动作在动作栏里不可用。 4.5.9+moveable
决定组件是否能被移动。如果设置为false
,那么移动图标在组件工具栏里不绘制,并且Move component动作在动作栏里不可用。 4.5.9+writable
决定组件是否能被编辑。如果设置为
,那么编辑图标在组件工具栏里不绘制,并且Edit component动作在动作栏里不可用。 4.5.9+false
Reference > Components里有可用的组件模板属性以及它们的用法的完整列表。
节点名 | 值 |
---|---|
components | |
content | |
stkQuotedText | |
deletable | false |
description | paragraphs.content.stkQuotedText.description |
dialog | standard-templating-kit:components/content/stkQuotedText |
i18nBasename | info.magnolia.module.templatingkit.messages |
moveable | false |
renderType | stk |
templateScript | /templating-kit/components/content/quotedText.ftl |
title | paragraphs.content.stkQuotedText.title |
writable | true |
以上的配置样例中,deletable
,moveable
和writable
属性的使用使得组件可编辑,同时禁止移动和删除。以下为编辑者在页面编辑器里看到的。
模型类
很多组件使用它们自己的模型类,为组件提供业务逻辑,并且在一些实例中使定制属性对脚本可用。例如,以下的stkTeaser
组件使用了InternalTeaserModel
,允许链接到要点组件的内部内容。
节点名 | 值 |
---|---|
components | |
teasers | |
stkTeaser | |
parameters | |
areas | |
description | paragraphs.teasers.stkTeaser.description |
dialog | standard-templating-kit:components/teasers/stkTeaser |
i18nBasename | info.magnolia.module.templatingkit.messages |
modelClass | info.magnolia.module.templatingkit.templates.components.InternalTeaserModel |
renderType | stk |
templateScript | /templating-kit/components/teasers/internalPage.ftl |
title | paragraphs.teasers.stkTeaser.title |
internalPage.ftl
脚本绘制模型使能的目标内容的属性。以下为这个脚本的片段,该脚本在STK > Templates /templating-kit/components/teasers/interalPage.ftl
。
[#-- Assigns: Get and check Teaser Target --] [#assign target = model.target!] [#assign hasTarget = target?has_content] [#-- Assigns: Macro assigning Values --] [#macro assignValues] [#-- Assigns: Get Content --] [#assign title = content.teaserTitle!target.title!target.@name] [#assign kicker = target.kicker!] [#assign text = content.teaserAbstract!target.abstract!] [#assign teaserLink = model.teaserLink!]
参数
组件定义的/<component name>/parameters
节点里的属性对模板脚本可用,无需支持的模型类。这是一个嵌入功能。此节点也同样被模板类参数使用。
参数属性被大量用于CSS样式。例如,在下面的stkTeaserNewsList
组件定义配置里:
divClass
,divIDPrefix
和headingLevel
属性可用于模板CSS样式目的,并且不依赖于模型类。更多信息可参考Teaser IDs。searchForSubcategory
属性由NewsListModel
模型类定义对模板可用。组件生成要点列表,要点为基于subcategory=news
页面模板的目标页面。teaserLinkType
属性也由modelClass
使能,并且将要点链接识别为内部链接。
节点名 | 值 |
---|---|
components | |
teasers | |
stkTeaserNewsList | |
parameters | |
divClass | teaser latest |
divIDPrefix | teaser |
headingLevel | h2 |
searchForSubcategory | news |
teaserLinkType | internal |
description | paragraphs.teasers.stkTeaserNewsList.description |
dialog | standard-templating-kit:components/teasers/stkTeaserNewsList |
i18nBasename | info.magnolia.module.templatingkit.messages |
modelClass | info.magnolia.module.templatingkit.templates.components.NewsListModel |
renderType | stk |
templateScript | /templating-kit/components/teasers/newsList.ftl |
title | paragraphs.teasers.stkTeaserNewsList.title |
以下为newsList.ftl
脚本如何绘制divClass
,divIDPrefix
和headingLevel
属性的。您可以在STK > Templates /templating-kit/components/teasers/newsList.ftl
获得此脚本。
[#-------------- RENDERING PART --------------] [#-- Rendering: Latest News --] <div class="${divClass}" ${divID} > <${headingLevel}>${content.teaserTitle}</${headingLevel}>
以下为由stkNewsList
组件绘制而成的HTML。
嵌套组件
很多STK组件都有嵌套组件。在页面上,主组件被首先创建,然后编辑者会创建子组件。stkPureLinkList
主组件只允许一个组件标题,链接是由stkInternalLink
,stkExternalLink
或stkDownloadLink
组件创建的。
在主组件定义中:
- 子组件被分配到
/areas/<area name>/availableComponents
节点下。这里的节点结构与区域定义里使组件可用时使用的结构完全一致。 - 每个子组件都被分配到它自身的子内容节点下,使用与它的组件定义匹配的名字。
id
属性引用子组件,使用<module name>:<path to component>
结构。- 每个子组件都是在它自己的组件定义中分别配置。您可以在STK > Template Definitions
/components/links
里查看这些。 主组件,嵌套区域和单个子组件都由它们自己的脚本绘制。
节点名 | 值 |
---|---|
components | |
teasers | |
stkPureLinkList | |
parameters | |
areas | |
linkList | |
availableComponents | |
stkInternalLink | |
id | standard-templating-kit:components/links/stkInternalLink |
stkExternalLink | |
stkDownloadLink | |
description | areas.components.linkList.description |
enabled | true |
templateScript | /templating-kit/components/links/linkListArea.ftl |
title | areas.components.linkList.title |
type | list |
description | paragraphs.teasers.stkTeaserPureLinkList.description |
dialog | standard-templating-kit:components/teasers/stkTeaserPureLinkList |
i18nBasename | info.magnolia.module.templatingkit.messages |
renderType | stk |
templateScript | /templating-kit/components/teasers/pureLinkList.ftl |
title | paragraphs.teasers.stkTeaserPureLinkList.title |
pureLinkList.ftl
脚本使用页面模板里绘制区域的相同代码来绘制主组件。脚本全文在STK > Templates /templating-kit/components/teasers/pureLinkList.ftl
下。这里为相关片段。
[#-- Rendering the teaser's linkList --] [@cms.area name="linkList"/]
linkListArea.ftl
脚本使用[#list]
指令来绘制嵌套组件。脚本全文在STK > Templates /templating-kit/components/links/linkListArea.ftl
里。这里为相关片段。
… [#list components as component ] [@cms.component content=component /] [/#list] …
extends
属性
扩展机制被广泛使用,以最小化有着相应teaser
组件的extras
组件的配置。在这两个区域绘制的组件基本相同,只有CSS样式和继承行为不一样。
这里是stkTeaserContact
组件定义的完全配置。
节点名 | 值 |
---|---|
components | |
teasers | |
stkTeaserContact | |
parameters | |
divClass | box vcard |
divIDPrefix | teaser |
headingLevel | h2 |
teaserLinkType | internal |
description | paragraphs.teasers.stkTeaserContact.description |
dialog | standard-templating-kit:components/teasers/stkTeaserContact |
i18nBasename | info.magnolia.module.templatingkit.messages |
modelClass | info.magnolia.module.templatingkit.templates.components.ContactModel |
renderType | stk |
templateScript | /templating-kit/components/teasers/contact.ftl |
title | paragraphs.teasers.stkTeaserContact.title |
stkExtrasContact
组件扩展要点组件,只修改divIDPrefix
和dialog
引用部分。stkExtrasContact
对话也是stkTeaserContact
对话的一个扩展,添加了Show in Subpage域,允许子页面继承。您可以在STK > Dialog Definitions /components/teasers/stkTeaserContact
和/extras/stkExtrasContact
里查看引用的对话。更多信息可参考可继承组件。
节点名 | 值 |
---|---|
components | |
extras | |
stkExtrasContact | |
parameters | |
divIDPrefix | box |
dialog | standard-templating-kit:components/extras/stkExtrasContact |
extends | /modules/standard-templating-kit/templates/components/teasers/stkTeaserContact |
自动生成的组件
自动生成特性允许您在页面的任何区域内自动生成组件。这是Magnolia CMS核心功能,由以下类提供:
ConfiguredAutoGeneration
类(由AreaElement
引入),提供在区域定义中的autoGeneration
节点和属性。CopyGenerator
生成器类,创建节点和属性,这些属性与链接到templateId
属性并且只适用于autoGeneration
节点的配置一致。
自动生成的组件可在任何区域定义里配置。以下配置样例在stkEvent
模板的嵌套extras1
区域自动生成stkExtrasCalendar
组件。参考extras区域获得关于extras
区域里可用配置选项的更多信息。
/areas/<area name>/autoGeneration
父节点和/content
子节点需要有这些特定的名字。这种命名规则和节点结构将配置识别为自动生成内容。/autoGeneration/generatorClass
节点分配CopyGenerator
类,允许任何该组件可用的属性使用被templateId
属性引用。/autoGeneration/content/calendar
节点可以被任意命名。这个例子中的属性只是必需的属性,但可以依据引用的组件(参考以下样例)添加额外的属性。nodeType
被设置为mgnl:component
,以将引用的组件识别为一个组件。
templateId
定义到组件定义的路径,使用<module name>:<path to definition>
格式。
节点名 | 值 |
---|---|
pages | |
stkEvent | |
areas | |
extras | |
areas | |
extras1 | |
autoGeneration | |
content | |
calendar | |
nodeType | mgnl:component |
templateId | standard-templating-kit:components/extras/stkExtrasCalendar |
generatorClass | info.magnolia.rendering.generator.CopyGenerator |
这里是基于stkEvent
模板的新页面上自动生成的组件。
下面的例子在stkArticle
模板的main/content
区域自动生成stkHTML
组件。因为其他内容模板扩展该模板,该组件也在stkLargeArticle
,stkNews
,stkEvent
和stkGlossaryTerm
模板上绘制。
这是绘制stkHTML
组件的html.ftl
脚本。注意一个单属性,editHTML
,在此组件中绘制。
[#if content.editHTML?has_content] ${cmsfn.decode(content).editHTML} [/#if]
这是样例的配置,用来在stkArticle
模板的main/content
区域绘制此组件:
- 基本配置与上一个例子一样。
editHTML
属性的添加会在脚本里添加由[cmsfn.decode]
方法绘制的HTML代码。
节点名 | 值 |
---|---|
pages | |
stkArticle | |
areas | |
main | |
areas | |
content | |
availableComponents | |
autoGeneration | |
content | |
conference | |
editHTML | <p><font color="#669900" size="+1">Sign up for the</font><font size="+1">....../strong></a>.</font> </p> |
nodeType | mgnl:component |
templateId | standard-templating-kit:components/content/stkHTML |
generatorClass | info.magnolia.rendering.generator.CopyGenerator |
这里是基于stkArticle
模板的新页面上的自动生成组件。
特色组件
特色模板主要由在页面模板的main/content
区域绘制的组件区分开。stkImagGallery
,stkFAQ
,stkSiteMap
等组件在stkImageGallery
, stkFAQ
, stkSiteMap
等模板的该区域绘制。组件由页面模板自动绘制,由自动生成特性完成。
组件定义与其他组件使用的配置方法,您可以在STK > Template Definitions /components/features
里查看。
下列所示的stkSiteMap
组件:
- 使用
SiteMapParagraphModel
,包含了业务逻辑,并使maxLevels
,showSiteMapRoot
,titleToUse
属性对脚本可用。 - 由
siteMap.ftl
脚本绘制,该脚本可在STK > Templates/templating-kit/components/features/siteMap.ftl
找到。
节点名 | 值 |
---|---|
components | |
features | |
stkSiteMap | |
description | paragraphs.features.stkSiteMap.description |
dialog | standard-templating-kit:components/features/stkSiteMap |
i18nBasename | info.magnolia.module.templatingkit.messages |
modelClass | info.magnolia.module.templatingkit.templates.components.SiteMapParagraphModel |
renderType | stk |
templateScript | /templating-kit/components/features/siteMap.ftl |
title | paragraphs.features.stkSiteMap.title |
当一个基于stkSiteMap
模板的页面被创建时,组件被使用区域定义(见下表)中配置的缺省值绘制。编辑者可以在STK > Dialog Definitions /components/features/stkSiteMap
下配置的stkSiteMap
组件对话里修改这些缺省值。查看demo-project/service/site-map
页了解它是如何工作的。
stkSiteMap
页面模板的areas/main/areas/content
节点下:
/autoGeneration
节点在generatorClass
节点的CopyGenerator
类里分配。该生成器创建节点和属性,其中属性和链接到templateId
属性并且只适用于autoGeneration
节点的配置一致。- 在
autoGeneration/content/singleton
节点里: - 缺省值被分配给显示给组件模型的属性。
nodeType
被设置为mgnl:component
。templatedId
属性引用stkSiteMap
组件定义,使用<module name>:<path to component>
结构。
节点名 | 值 |
---|---|
pages | |
stkSiteMap | |
areas | |
main | |
areas | |
intro | |
content | |
autoGeneration | |
content | |
singleton | |
maxLevels | 3 |
nodeType | mgnl:component |
showSiteMapRoot | true |
templateId | standard-templating-kit:components/features/stkSiteMap |
titleToUse | title |
generatorClass | info.magnolia.rendering.generator.CopyGenerator |
type | single |
class | info.magnolia.module.templatingkit.templates.MainArea |
这里是stkSiteMap
组件和demo-project/service/site-map
页面上的对话。
在上面的对话里,maxLevels
属性被设置为4
。这是因为模板定义里的缺省值3
在此页上已经被覆写了。新值4
被存在JCR中,您可以在Tools > JCR /demo-project/service/site-map/content/singleton
中验证。
节点名 | 值 |
---|---|
demo-project | |
service | |
site-map | |
content | |
singleton | |
maxLevels | 4 |
showSiteMapRoot | true |
titleToUse | title |
如果您想要在模板定义中修改一个自动生成的组件的缺省设置,您需要首先在JCR浏览器中删除这个内容节点(singleton
)并刷新该页。系统会使用新的模板定义属性在页面上重新创建该组件。这是一个已知问题,您可以在MAGNOLIA-4482里跟踪进展。