Component definitions

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.

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.  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.  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.  4.5.9+

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

The use of the deletable, moveable 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.

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.

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 divClass, divIDPrefix 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 modelClass, NewsListModel. 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.

Here's how the newsList.ftl script renders the divClass, divIDPrefix 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 stkInternalLink, stkExternalLink 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.

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.

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.

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.

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 stkLargeArticle, stkNews, stkEvent 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.

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.

Feature components

The feature templates are distinguishable mainly by the component that renders in the main/content area of the page template. The stkImagGallery, stkFAQ, stkSiteMap etc. components render in the area on the stkImageGallery, stkFAQ, stkSiteMap 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 maxLevels, showSiteMapRoot and titleToUse properties available to the script.
• Is rendered by the siteMap.ftl script accessible in STK > Templates /templating-kit/components/features/siteMap.ftl.

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.

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.

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.