STK具体页面模板和组件模板定义在STK > 模板定义下配置。
节点名 | 值 |
---|---|
pages | |
components |
页面定义
所有STK页面模板的具体模板定义都在STK > 模板定义 /pages
里配置。
节点名 | 值 |
---|---|
pages | |
demo-features | |
stkHome | |
stkSection | |
stkArticle |
这些模板可供编辑者在页面应用里选择使用。它们可以出现在页面应用的模板下拉菜单里,只需要:
在通用属性里,visible
属性设置为true
。- 模板在企业版的缺省网站定义或其他网站定义里设置为可用。
- 编辑者的权限已经可以获取特定的模板了。如要通过角色来限制权限,可在原型里的
/availability/<template name>/roles
节点下配置。
不同的页面级别可用的模板是不同的。例如,级别1可用stkHome
和stkRedirect
,而级别2则可用stkSection
和其他的模板。以下的类别和子类有更多关于如何实现网站层级的信息。
所有具体的页面模板都是基于模板原型的。原型包含了缺省结构和行为,具体模板则定义了对原型配置的例外、添加物和覆写。参考模板合并里的样例来了解它是如何工作的。
为了能让系统识别,模板定义里的配置结构需要与模板原型里相应的配置一样。比较模板原型(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里有一个配置样例。
模板属性
多数模板属性是在具体模板级别分配的,能够区分不同的模板。
参考资料部分的页面>属性里有一个完整的列表,包含了可用的模板属性及用法。
通用属性
模板原型里分配的唯一一个所有具体模板都可用的属性是templateScript
,用来引用管理页面脚本,即main.ftl。
除此之外,所有STK模板都使用以下通用属性:
class
节点里分配的STKPage,
定义基本模板定义。modelClass节点里分配的STKPageModel,
是基本页面模型,提供页面级功能。它扩展了STKPage
。renderType节点下
STK值为
stk时,
分配的
。所有STK模板(页面和组件)都可以使用这个绘制器。专用绘制器,
STKRendereri18nBasename
节点下分配的国际化关键字,info.magnolia.module.templatingkit.messages
。这也是STK翻译的消息包关键字。visible
属性设置为true,
使编辑者在页面应用里可以选择该模板。节点名 值 pagesstkArticle
areas
bodyIDarticle categorycontent classinfo.magnolia.module.templatingkit.templates.pages.STKPage dialogstandard-templating-kit:pages/article/stkArticleProperties i18nBasenameinfo.magnolia.module.templatingkit.messages modelClassinfo.magnolia.module.templatingkit.templates.pages.STKPageModel renderTypestk subcategoryarticle titletemplates.stkArticle.title visibletrue
有两个例外:
stkGlossary
模板使用它自己的modelClass
,即GlossaryTemplateModel
,这个模型类通过扩展STKPageModel<STKPage>
来完成按字母排序的词汇表。节点名 值 pagesstkGlossary
areas
bodyIDglossary categoryfeature classinfo.magnolia.module.templatingkit.templates.pages.STKPage dialogstandard-templating-kit:pages/glossary/stkGlossaryProperties i18nBasenameinfo.magnolia.module.templatingkit.messages modelClassinfo.magnolia.module.templatingkit.templates.GlossaryTemplateModel renderTypestk subcategoryglossary titletemplates.stkGlossary.title visibletrue
stkRedirect
模板使用它自己的:modelClass
:RedirectTemplateModel
,这个模型类扩展了STKPageModel,
并提供3个可选的重定向模式。编辑者可以通过以下方式之一设置path
值来选择模式:- 如果在对话框里输入了内部路径或外部URL,用户将会直接被重定向过去。为避免写入响应,绘制步骤会被跳过。
- 如果没有输入路径,那么页面会重定向至找到的第一个子页面。这有利于直接显示一个在重定向树的二级或三级定义的页面。
templateScript:redirectMain.ftl
,在页面上绘制合适的路径。您可以在STK > 模板/templating-kit/pages/functional/redirectMain.ftl
里查看脚本。节点名 值 pagesstkRedirect
areas
bodyIDredirect categoryfunctional classinfo.magnolia.module.templatingkit.templates.pages.STKPage dialogstandard-templating-kit:functional/stkRedirect i18nBasenameinfo.magnolia.module.templatingkit.messages modelClassinfo.magnolia.module.templatingkit.templates.RedirectTemplateModel renderTypestk subcategoryredirect templateScript/templating-kit/pages/functional/redirectMain.ftl titletemplates.stkRedirect.title visibletrue
在页面编辑器里,页面显示到内部或外部重定向的路径,但在预览里,则显示目标页面。/demo-project/service/m5-campaign
页面使用的是stkRedirect
模板。
模板特定属性
以下属性因每个模板而不同:
bodyID
:这是模板专有样式的CSS表所用的标签。参考Body类和ID以获得更多信息。bodyID
和subcategory
值常常会一致,但它们彼此之间没有依赖关系。category
和subcategory
:每个模板都会分配到一个类别里,同时大多数模板也会分配到子类。很多场合都使用了类别,参考类别和子类。dialog
:每个页面模板会连接到它自己的stk<Template name>Properties
对话框,这个对话框在STK > 对话框定义/pages
里配置。页面顶部工具栏里的属性按钮可以打开此对话框,控制浏览器标题和导航标题及行为,页面元数据(关键字和描述),变异形式排除和页面依赖性。详细信息参看属性对话框。title
:在页面应用的模板下拉菜单里显示的模板标题。节点名 值 pagesstkImageGallery
areas
bodyIDimage-gallery categoryfeature classinfo.magnolia.module.templatingkit.templates.pages.STKPage dialogstandard-templating-kit:pages/imageGallery/stkImageGalleryProperties i18nBasenameinfo.magnolia.module.templatingkit.messages modelClassinfo.magnolia.module.templatingkit.templates.pages.STKPageModel renderTypestk subcategoryimageGallery titletemplates.stkImageGallery.title visibletrue
extends属性
Magnolia CMS使用扩展机制来最小化配置。这个机制类似于单个模板定义和原型定义之间的关系,只不过它很直观。扩展配置中只配置修改、例外和添加物,其他所有配置都照搬基本配置。
内容模板,也就是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
节点下配置,其次是通过类别配置。类别的可用性逻辑以硬编码(hard-coded)方式写入TemplateCategory
里,所以必须先扩展此类才能声明。另外,TemplateCategoryUtil
为使用模板的类别添加了实用方法。子类别由于不是固定的,您可以直接在模板定义里设置。
类别的可用性逻辑是硬编码的,它的默认设置为:
只有home
和functional分
类可以被分配给网站的根页面。
home
在每个页面只可以被分配一次。您可以定义很多主页模板,如有着不同的列布局的模板,使他们都属于home分
类,但您一次只可以分配它们当中的一个。functional
可以被分配给任意页面,不管父模板的类别是什么。举个例子,也就是说,您可以在网站的任意位置有一个重定向页面。section
只可以被分配给父页面类别为home
,section
,functional
,或feature
的页面。换句话说,它可以被分配给除父页面为content
类以外的所有页面。content
和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
节点里添加组件。以下的配置在
模板的stkArticle
区域添加了promos
stkTextImage
和stkQuotedText
组件。加上原型使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
enabledfalse stkExtrasContact
idstandard-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
idstandard-templating-kit:components/content/stkTextImage extendsoverride dialogstandard-templating-kit:pages/news/stkNewsProperties extends/modules/standard-templating-kit/templates/pages/stkArticle subcategorynews titletemplates.stkNews.title
限制组件使用
您可以在模板定义里,限制对区域内任意可用组件的使用权。stkArticle
模板里有一个配置样例,限制了只有superuser
角色的用户可以使用stkHTML
组件,任何有着较少权限的用户都不可以使用该组件。这是在STK > 模板定义 /pages/stkArticle/areas/main/areas/content/availableComponents/stkHTML
里配置的:
roles
内容节点提醒Magnolia CMS可能有使用限制。superuser
属性值也设置为superuser,
限制了只有superuser
角色的用户才能使用组件。详细信息参考角色RolesRoles。节点名 值 stkArticle
areas
main
areas
content
availableComponents
stkHTML
roles
superusersuperuser idstandard-templating-kit:components/content/stkHTML stkTextImage
stkQuotedText
您可以这样来测试:以样例编辑者Eric(username/password=eric
)的身份登录,尝试在任意文章页面的content
区域添加stkHTML
组件。结果将会是,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
maxImages9 nodeTypemgnl:component templateIdstandard-templating-kit:components/features/stkImageGallery generatorClassinfo.magnolia.rendering.generator.CopyGenerator typesingle
使能区域
大多数区域在原型里是使能的,因此需要在特定的模板定义里禁用,改变默认设置。您可以将/areas/<area name>
内容节点下的enabled
属性节点值设置为false
来做到。另一方面,类似stage
或platform
的区域由于很少使用,所以在原型里是不使能的,这种情况就需要设置enabled
属性值为true
来改变。
使能或禁用区域,将会:
决定整个区域是否绘制,无论区域包含的是组件,自动生成的内容,还是脚本绘制的内容。内容会保留在内容库中,并且在一个被禁用的区域重新使能后,将会再绘制。您可以在
stkArticle
模板上禁用extras
,并在工具 > JCR里查看任意文章页来验证。模板定义
节点名 值 stkArticle
areas
extras
enabledfalse bodyIDarticle JCR浏览器(网站)
节点名 值 demo-projectaboutsubsection-articlesarticleextras
extras1
0
00
- 对扩展模板与基本模板有着同样的作用。例如,如果您在
stkArticle
上禁用extras
,所有内容模板上都会禁用该区域;要在您的扩展模板上使能该区域,需要在扩展模板上添加enabled
属性并设置为true
。 - 可能影响页面布局。以下是一些样例,样例中的结果主要是由于页面排列和内容包装的方法造成的。
- 当
extras
被禁用时,main
区域会展开占用所有的可用空间。 - 当
promos
被禁用时,原本它占用的可用空间里什么都不会绘制。 - 当
base
、stage
或是sectionHeader
被禁用时,内容会上移显示,就像被禁用的区域不曾存在一样。区域在使能但不包含任何内容时,预览模式里也会发生同样的情况。下面的截图为禁用了stage
的stkHome
模板。
- 当
- 当
main
区域里使能浮显(floating
),并且将columns
设置为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
区域脚本绘制。 在
availableComponents
节点里设置stkTeaserOpener
组件可用。节点名 值 stkSection
areas
main
floating
areas
intro
opener
availableComponents
stkTeaserOpener
idstandard-templating-kit:components/teasers/stkTeaserOpener descriptionareas.templates.main.opener.description enabledtrue optionaltrue templateScript/templating-kit/pages/section/opener.ftl titleareas.templates.main.opener.title typesingle content
classinfo.magnolia.module.templatingkit.templates.SectionMainArea templateScript/templating-kit/pages/section/mainArea.ftl
使能浮显
浮显(floating)是指该区域内的组件在指定数目的列里绘制。默认情况下,浮显在stkHome
和stkSectionFloating
模板的main
区域内是使能的。demo-project
的主页和demo-features/section-variations/floating
页面就使用了这两个模板。下图显示了demo-project
主页的main
区域。
浮显是在模板定义的<template name>/areas/main
内容节点里配置的。在STK > 模板定义 /pages/stkHome
的stkHome
模板里:
/areas/main:
- 使用
SectionMainArea
类定义浮显属性。 - 由
section/MainArea.ftl
脚本绘制,简单的绘制所有嵌套区域。 areas/main/floating
:enabled
节点设置为true
来使能浮显。您可以将此属性设置为false
来禁用。columns
设置为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
columns3 enabledtrue areas
content
availableComponents
templateScript/templating-kit/pages/section/contentArea.ftl titletemplates.stkHome.areas.main.content.title intro
classinfo.magnolia.module.templatingkit.templates.MainAreaIntro enabledfalse opener
breadcrumb
classinfo.magnolia.module.templatingkit.templates.SectionMainArea templateScript/templating-kit/pages/section/mainArea.ftl extras
inheritance
classinfo.magnolia.module.templatingkit.templates.ExtrasArea enabledfalse
默认情况下,您可以扩展stkHome
和stkSection
模板来配置一个浮显模板,这是因为它们都使用SectionMainArea
类和要点组件。其它的场景则需要定制。STK > 模板定义 /pages/demo-features/stkSectionFloating
里的stkSectionFloating
模板就是扩展stkSection
模板的一个例子,它:
- 在
stkSectionFloating/extends
节点下扩展stkSection
模板。通过扩展: - 需要的要点组件在
/areas/main/content/availableComponents
节点下可用。 SectionMainArea
类得到使用。- 在
/areas/main/floating
节点,floating
被使能且columns
设置为2
。 - 在
/areas/main/areas
节点,intro
和opener
区域被禁用。 在
/areas/extras
节点,extras
区域被禁用。节点名 值 pagesdemo-featuresstkSectionFloating
areas
main
floating
columns2 enabledtrue areas
intro
enabledfalse opener
enabledfalse extras
inheritance
classinfo.magnolia.module.templatingkit.templates.ExtrasArea enabledfalse base
extends/modules/standard-templating-kit/templates/pages/stkSection titleSection 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
。
变异形式
变异形式可以用于多种用途,例如重新排版智能手机和平板设备的内容,或已登录用户组的特定输出等。移动性里有关于演示站点里smartphone
变异形式样例的详细讨论,通道里也有此核心功能的更多信息。
变异形式通常在网站定义里配置,但也可以在模板定义里的模板级别上配置。舞台是使用该选项在智能手机上禁用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。这个功能可用于如网站的节假日活动或专有章节。
下列配置样例在stkArticle
模板里分配一个特定的CSS表和一个附加JavaScript。
节点名 | 值 |
---|---|
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 > 模板定义 /components
里配置,以文件夹的形式排列,文件夹名表示组件类型。
节点名 | 值 |
---|---|
components | |
content | |
teasers | |
extras | |
promos | |
stkPromo | |
features | |
links | |
stages | |
footer | |
pur |
组件定义与页面定义相似,使用相同的模板定义对象。页面和组件使用相同路径语法引用它们的对话框。此外,页面和组件还使用相同的绘制工具绘制。
多数情况下,您不需要从头开始创建一个新组件;您可以拷贝或扩展现有的,并按您的需要调整。
通常创建新组件包括以下几步:
- 创建一个对话框。
- 创建一个组件定义。
- 创建一个组件脚本。
- 使组件对组件脚本可用。
编辑者可以在STK > 对话框定义里配置的相关组件对话框输入内容,来使用组件。对话框定义通过dialog
属性映射到组件定义里。
大多数组件在区域定义里分配给页面模板,区域定义可以是模板原型或具体页面模板定义的。
组件模板属性
所有的STK组件定义都有以下属性:
description
:指向组件描述的消息包关键字。dialog
:到对话框定义的路径,结构为<module name>:<path to definition>
。大多数STK对话框都在STK > 对话框定义下配置。118nBasename
:国际化关键字,即info.magnolia.module.templatingkit.messages
,指向包含STK翻译的消息包。renderType
:值为stk时
分配的STKRenderer
是一个STK专用的绘制器,为所有的STK模板(页面和组件)所使用。templateScript
:指向绘制组件的脚本的路径。组件脚本在STK > 模板/templating-kit/components
下。title
:在组件工具栏里绘制的组件标题。deletable
决定组件是否能被删除。如果设置为false
,那么删除组件在动作栏里不可用。 4.5.9+moveable
决定组件是否能被移动。如果设置为false
,那么移动图标在组件工具栏里不绘制,并且移动组件动作在动作栏里不可用。 4.5.9+writable
决定组件是否能被编辑。如果设置为
,那么编辑图标在组件工具栏里不绘制,并且编辑组件动作在动作栏里不可用。 4.5.9+false
参考资料 > 组件里有可用的组件模板属性的完整列表及用法。
节点名 | 值 |
---|---|
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
属性的配置使组件可编辑,但不可移动或删除。以下为编辑者在页面编辑器里看到的。
模型类
很多组件使用它们自己的模型类(model class),提供组件的业务逻辑,并且有时使脚本可以使用定制的属性。例如,以下的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 > 模板 /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
组件定义配置里:
- 为了达到使用CSS样式的目的,模板里设置了
divClass
,divIDPrefix
和headingLevel
属性。这些属性不依赖于模型类。更多信息可参考Teaser IDs。 - 模板通过
设置了NewsListModel modelClass
searchForSubcategory
属性。这个组件会生成一个要点列表,其中要点的目标页面基于subcategory=news
的页面模板。 teaserLinkType
属性也通过modelClass
被模板所用,它标记要点链接为internal
链接。
节点名 | 值 |
---|---|
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 > 模板 /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 > 模板定义
/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 > 模板 /templating-kit/components/teasers/pureLinkList.ftl
下,这里为相关片段。
[#-- Rendering the teaser's linkList --] [@cms.area name="linkList"/]
linkListArea.ftl
脚本使用[#list]
指令来绘制嵌套组件。脚本全文在STK > 模板 /templating-kit/components/links/linkListArea.ftl
里,这里为相关片段。
… [#list components as component ] [@cms.component content=component /] [/#list] …
extends属性
扩展机制被广泛使用来最小化extras
组件的配置。extras
组件有对应的teaser
组件,这两个区域绘制的组件基本相同,只有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
对话框的一个扩展,添加了在子页面中显示字段,允许子页面继承。您可以在STK > 对话框定义 /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
生成器类(generator class),创建节点和属性,使他们与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 > 模板定义 /components/features
里查看。
下列所示的stkSiteMap
组件:
- 使用了
SiteMapParagraphModel
,这个模型类包含业务逻辑,并使maxLevels
、showSiteMapRoot
和titleToUse
属性对脚本可用。 - 由
siteMap.ftl
脚本绘制。该脚本在STK > 模板/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 > 对话框定义 /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中,您可以在工具 > 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里跟踪进展。