Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

Components are the smallest block of content on a page. The STK includes components for all use cases and the available components range from simple text components to complex aggregation teasers and more. The individual components are discussed on the Components page.

Component definitions are configured in STK > Template Definitions /components. The definitions are arranged in folders and the folder names indicate the component types.

Node nameValue

 components

 

 content

 

 teasers

 

 extras

 

 promos

 

 stkPromo

 

 features

 

 links

 

 stages

 

 footer

 

 pur

 

A component definition is similar to the page definition. Both use the same template definition object. Pages and components reference their dialogs using the same path syntax. In addition, pages and components are rendered using the same renderer.

In many cases, it is not necessary to create a new component from scratch; you can copy or extend an existing one and adapt it to your needs.

Typically when creating new components, the following steps are involved:

  1. Create a dialog.
  2. Create a component definition.
  3. Create a component script.
  4. Make the component available to a component script.

Components are available to editors for content entry via the associated component dialog configured in STK > Dialog Definitions. The dialog definition is mapped to the component definition using the dialog property.

Most components are assigned to page templates within the area definitions in either the template prototype or concrete page template definition.

Component template properties

All STK component definitions have the the following properties:

  • description: Message bundle key to the component description
  • dialog: Path to the dialog definition with a <module name>:<path to definition> structure. Most STK dialogs are configured in STK > Dialog Defintions.
  • 118nBasename: The internationalization key, info.magnolia.module.templatingkit.messages, to the message bundle that contains STK translations.
  • renderType STKRenderer assigned by the value stk is a STK-specific renderer used by all STK templates (pages and components). info.magnolia.module.templatingkit.renderers.STKRenderer
  • templateScript: Path to the script that renders the component. Component scripts are accessible in STK > Templates /templating-kit/components.
  • title: The component title that renders in the component toolbar.
  • deletable determines if the component can be deleted. If set to false the Delete component action is not available in the action bar. (warning) 4.5.9+
  • moveable determines if the component can be moved. If set to false the move icon is not rendered in the component toolbar and the Move component action is not available in the action bar. (warning) 4.5.9+
  • writable determines if the component can be edited. If set to false the edit icon is not rendered in the toolbar and the Edit component action is not available in the action bar. (warning) 4.5.9+

For a full list of available component template properties and their usage see Reference > Components.

Node nameValue

 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

The use of the deletablemoveable and writable properties in the example configuration above makes the component editable while disallowing moving and deleting. Here's what the editor sees in the page editor.

You can also restrict component actions in an area definition, in either the prototype or the concrete template definition, based on the roles assigned to users.

Model class

Many components use their own model class that provides the business logic for the component, and in some instances makes custom properties available to the script. For example the stkTeaser component below uses InternalTeaserModel that allows linking to internal content in teaser components.

Node nameValue

 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

The internalPage.ftl script renders the properties of the target content that are made available by the model. Here's a snippet from the script that is accessible in 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!]

Parameters

Properties in a /<component name>/parameters node of a component definition are available to the template script without a supporting model class. This is built-in functionality. This node is also used for model class parameters.

Parameter properties are used extensively for CSS styling. For example, in the stkTeaserNewsList component definition configuration below:

  • The divClassdivIDPrefix and headingLevel properties are made available to the template for CSS styling purposes and are not reliant on the model class. For more information see Teaser IDs.
  • The searchForSubcategory property is made available to the template by the modelClassNewsListModel. This component renders a list of teasers that have target pages based on page templates of subcategory=news.
  • The teaserLinkType property is also made available by the modelClass and identifies the teaser links as internal links.
Node nameValue

 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

Here's how the newsList.ftl script renders the divClassdivIDPrefix and headingLevel properties. You can access this script in STK > Templates /templating-kit/components/teasers/newsList.ftl.

[#-------------- RENDERING PART --------------]
[#-- Rendering: Latest News --]
<div class="${divClass}" ${divID} >

    <${headingLevel}>${content.teaserTitle}</${headingLevel}>

Here's the rendered HTML of a stkNewsList component. 

Nested components

Many STK components have nested components. On the page, the main component is created first and then the editor creates the child components. The main stkPureLinkList component allows for only for a component title and the links are created using the stkInternalLinkstkExternalLink or stkDownloadLink components.

In the main component definition:

  • The child components are assigned in the /areas/<area name>/availableComponents node. The node structure here is identical to that used when making components available in an area definition.
  • Each child component is assigned in its own child content node with a name that matches its component definition.
  • The id property references the child component with the <module name>:<path to component> structure.
  • Each child component is configured separately in its own component definition. You can view these in STK > Template Definitions /components/links.
  • The main components, nested area and individual child components are all rendered by their own scripts.

Node nameValue

 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

The pureLinkList.ftl script renders the main components with the same code used to render areas on page templates. The full script is accessible in STK > Templates /templating-kit/components/teasers/pureLinkList.ftl. Here's the relevant snippet.

[#-- Rendering the teaser's linkList --]
    [@cms.area name="linkList"/]

The linkListArea.ftl script renders the nested components using the [#list] directive. The full script is accessible in STK > Templates /templating-kit/components/links/linkListArea.ftl. Here's the relevant snippet.

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

Extends property

The extends mechanism is used extensively to minimize configuration of extras components that have corresponding teaser components. The components that render in the two areas are essentially the same except for CSS styling and inheritance behavior.

Here's the stkTeaserContact component definition that is configured in full.

Node nameValue

 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

The stkExtrasContact component extends the teaser component changing only the divIDPrefix and dialog reference. The stkExtrasContact dialog is also an extension of the stkTeaserContact dialog with the addition of the Show in Subpage field that allows for cascading on child pages. You can view the referenced dialogs in STK > Dialog Definitions /components/teasers/stkTeaserContact and /extras/stkExtrasContact. For more information see Inheritable components.

Node nameValue

 components

 

 extras

 

 stkExtrasContact

 

 parameters

 

 divIDPrefix

box

 dialog

standard-templating-kit:components/extras/stkExtrasContact

 extends

/modules/standard-templating-kit/templates/components/teasers/stkTeaserContact

Autogenerated components

The autogeneration feature allows you to generate components automatically in any area of a page. This is Magnolia core functionality provided by:

  • ConfiguredAutoGeneration class (imported by  AreaElement) that provides for an autoGeneration node and properties in an area definition.
  • CopyGenerator generator class that creates nodes and properties identical to those found in a configuration linked to in the templateId property and applies only to nodes named autoGeneration.

Autogenerated components can be configured in any area definition. The example configuration below autogenerates the stkExtrasCalendar component in the nested extras1 area in the stkEvent template. See extras area for more information about the configuration options available in the extras area.

Node nameValue

 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

Nodes and properties:

  • autoGeneration/content: The naming convention and node structure identifies the configuration as autogenerated content. Parent and child node need to have these specific names.
    • calendar: Node can be named anything you like. The properties in the example are the only required properties, but additional properties can be added depending on the component referenced (see example below).

      • nodeType: mgnl:component identifies the referenced component as a component.
      • templateId: Path to the component definition in the <module name>:<path to definition> format.
    • generatorClass: CopyGenerator allows the use of any properties available to the component referenced in the templateId property.

Here's the autogenerated component on a new page based on the stkEvent template.

The example below autogenerates the stkHTML component in the main/content area on the stkArticle template. Because the other content templates extend this template the component also renders on the stkLargeArticlestkNewsstkEvent and stkGlossaryTerm templates.

Here's the html.ftl script that renders the stkHTML component. Note that a single property, editHTML, renders in the component.

[#if content.editHTML?has_content]
    ${cmsfn.decode(content).editHTML}
[/#if]

Here's the example configuration the renders this component in main/content area of the stkArticle template:

  • The base configuration is the same as the previous example.
  • The addition of the editHTML property adds the HTML code rendered by the [cmsfn.decode] method in the script.
Node nameValue

 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

Here's the autogenerated component on a new page based on the stkArticle template.

The behavior of autogenerated differs from standard components:

  • During the first generation, autogenerated components render in the order defined in the template definition.
  • You cannot permanently delete an autogenerated component. If you delete one, it is automatically regenerated, but then renders last in the area.
  • If autogenerated components exist on a page and you add an additional autogenerated component in the template definition, the new component will be generated and rendered last in the area.

You can prevent editors deleting or moving autogenerated components by restricting component actions.

Feature components

The feature templates are distinguishable mainly by the component that renders in the main/content area of the page template. The stkImagGallerystkFAQstkSiteMap etc. components render in the area on the stkImageGallerystkFAQstkSiteMap templates etc. The component is rendered automatically by the page template and the autogeneration feature is used to accomplish this.

The component definitions are configured in the same way as other components and you can view them in STK > Template Definitions /components/features.

The stkSiteMap component shown below:

  • Uses the SiteMapParagraphModel that contains the business logic and makes the maxLevelsshowSiteMapRoot and titleToUse properties available to the script.
  • Is rendered by the siteMap.ftl script accessible in STK > Templates /templating-kit/components/features/siteMap.ftl.
Node nameValue

 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

When a page based on the stkSiteMap template is created, the component is rendered using default values configured in the area definition (see below). Editors can change these default values in the stkSiteMap component dialog configured in STK > Dialog Definitions /components/features/stkSiteMap. View the demo-project/service/site-map page to see how this works.

In the stkSiteMap page template in the areas/main/areas/content node:

  • The /autoGeneration node is assigned the CopyGenerator class in the generatorClass node. This generator creates nodes and properties identical to those found in the configuration linked to in the templateId property and applies only to nodes named autoGeneration.
  • In the autoGeneration/content/singleton node:
    • Default values are assigned to the properties exposed by the component model.
    • The nodeType is set to mgnl:component.
    • The templatedId property references the stkSiteMap component definition with the <module name>:<path to component> structure.
Node nameValue

 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

Here's the stkSiteMap component and dialog on the demo-project/service/site-map page.

In the dialog above the maxLevels property is set to 4. This is because the default of 3 defined in the template definition has been overriden on the page. The new value of 4 is stored in the JCR and you can verify this in Tools > JCR /demo-project/service/site-map/content/singleton.

Node nameValue

 demo-project

 

 service

 

 site-map

 

 content

 

 singleton

 

 maxLevels

4

 showSiteMapRoot

true

 titleToUse

title

If you want to change the default settings of an autogenerated component in the template definition, you need to first delete the component node (singleton) in the JCR Browser and then refresh the page. The system will recreate the component on the page using the new template definition properties. This is a known bug and you can follow the progress in MAGNOLIA-4482.