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

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

The STK concrete page template and component template definitions are configured in Templating Kit > Template Definitions.

Page definitions

Concrete template definitions for all STK page templates are configured in Template Definitions > /pages.

These templates are made available to editors for selection in Website. They will show up in the dropdown list provided the:

  • visible property is set to true in the template definition.
  • Template is made available in the default site definition, or any other site definition in the EE.
  • Editor's permissions are sufficient to access the particular template. role based restrictions can be imposed in the /availability/<template name>/roles node of the prototype.

The templates available at the various page levels differ. For example, stkHome and stkRedirect are available at level 1 and stkSection and others at level 2 etc. See Categories and subcategories below for more information on how the site hierarchy is achieved.

All concrete page templates are based on the template prototype. The prototype contains the default structure and behaviour and the concrete definitions define exceptions, additions and overrides of the prototype configuration. See Template merging for an example of how this works.

In order to be recognized by the system, configurations in the template definition need to be structured identically to the corresponding configuration in the template prototype. Compare the configurations of the infoBlock area in the template prototype and stkEvent template below and note that the node structure is identical.

To make a template unique, in the template definition you can:

  • Override most properties and content node configurations found in the prototype.
  • Configure additions to the prototype. Additions are new configurations not found in the prototype that add functionality, areas, components and other features.

There are no hard and fast rules. In a custom installation the configurations that should be included in the template prototype, as opposed to the concrete templates, is a practical, rather than a technical, decision.

Modifications to the prototype can be made on a:

  • Page level, for example by referencing a new templateScript. The stkRedirect template discussed below is an example of this.
  • Navigation level by changing the default navigation configuration or coding an entirely new one. This would rarely be necessary but may be appropriate on special custom templates.
  • Area level by referencing different scripts and changing area behavior. See main area for an example.
  • Variation level by disabling areas for a specific template so that the area renders for one variation but not the other. See Mobile for how this option is used for the stage area in the stkHome template.
  • JavaScript and CSS level by referencing different CSS sheets or JavaScripts. This option is rarely necessary and not used in either the prototype or concrete template definitions, but there is an example configuration in CSS and JavaScript below.

Template properties

Most template properties are assigned on a concrete template level because they distinguish the different templates.

For a full list of available template properties and their usage see Pages > Properties in our Reference section.

Common properties

The only property assigned in the template prototype and therefore available to all concrete templates is the templateScript that references the master page script, main.ftl.

With one exception, the following common properties are used by all STK templates:

  • STKPage assigned in the class node defines the base template definition.
  • STKPageModel assigned in the modelClass node is the base page model that provides page level functionality. It extends STKPage.
  • STKRenderer assigned in the renderType node by the value stk is the STK-specific renderer used by all STK templates (pages and components).
  • The internationalization key, info.magnolia.module.templatingkit.messages, assigned in the i18nBasename node. This is the key to the message bundle that contains STK translations.
  • The visible property set to true that makes the template available to editors in Website.

There are two exceptions:

  • The stkGlossary template uses its own modelClass, GlossaryTemplateModel, that extends STKPageModel<STKPage> to complete the alphabetical glossary list.

  • The stkRedirect template uses its own:
    • modelClass: RedirectTemplateModel that extends STKPageModel and provides 3 alternative redirect modes that depend on the path value provided by editors:
      • If an internal path or external URL is entered in the dialog, users are redirected directly to it and the rendering is skipped avoiding writing of the response.
      • If no path is entered the page redirects to the first child page found. This is useful to directly display a page defined in a second or third level of a redirect tree.
    • templateScript: redirectMain.ftl renders the path appropriately on the page. You can view this script in Templates > /templating-kit/pages/functional/redirectMain.ftl.

In edit mode the path to the internal or external redirect renders on the page, but in preview mode the target page renders.

Template specific properties

The following properties are specific to each template:

  • bodyID: This is the tag used by the CSS sheets for template-specific styling. See Body classes and ids for more information. The bodyID and subcategory values often correspond but have no bearing on or relationship to each other.
  • category and subcategory: Each template is assigned a category and most also a subcategory. Categories can be used in various scenarios see Categories and subcategories below.
  • dialog: Each page template links to its own stk<Template name>Properties dialog configured in Dialog Definitions > /pages. The Properties button in the top bar on each page opens this dialog, which controls the browser title and navigation title and behavior, page meta data (keywords and description), variation exclusion and page dependencies. See Properties dialogs for more information.
  • title: The template title that displays in the dropdown list in Website.

Extends property

The extends mechanism is used to minimize configuration. The mechanism is analogous to the relationship between an individual template definition and the prototype definition, but is explicit. Only changes, exceptions and additions are configured in the extended configuration, and all other configurations are taken from the base configuration.

The content templates, i.e. stkLargeArticle, stkNews, stkEvent and stkGlossaryTerm, are all extensions of the stkArticle template that forms the base configuration. You can use this mechanism to easily create custom templates that are similar to the default STK templates.

Similarly, the templates in /pages/demo-features are all extensions of the stkSection template. These templates show numerous ways that you can change the page layout by configuration. You can view them in Section Variations in the demo-features site.

The extends property can also be set to override parts of an extended configuration. See the example in Making components available below.

Template merging is an automatic process that does not rely on the extends mechanism. The extends=override property cannot be used in a template definition to modify the template prototype.

Categories and subcategories

Each STK page template belongs to a category and all templates except stkHome and stkRedirect also have a subcategory. Categories allow you to control where a template can be used on the site. If a template category is not allowed at a given place in the site structure, it will not be available to editors. The category mechanism therefore makes sure that templates are assigned in a consistent way and that your site has a controlled structure.

Categories establish an implicit template hierarchy. They define which template can be assigned to a page. For example the stkHome template belongs to category home. The home category can only be used on the root page of the site. Similarly, templates that belong to category content can only be used on a page that resides under a page whose template belongs to categories section, feature or functional.

Subcategories are used for content aggregation. For example, the system aggregates all pages in the news subcategory to generate a list of news teasers. An example is the creation of RSS feeds.

There are five template categories that correspond closely to the intended usage of the STK templates.

CategoryDescriptionTemplates in this category
homeRoot of the site.stkHome
functionalSpecial templates that perform actions rather than render content.stkRedirect
sectionSections that organize the site. The demo-project site has sections such as News and Events and Service. Yours could be Products, Services or Support.stkSection (including /demo-features variations), stkGlossaryLetter
featureSpecial templates and templates that collect or aggregate content.stkForm
stkFormStep
stkImageGallery
stkFAQ
stkPublicUserRegistration
stkSearchResult
stkSiteMap
stkGlossary
stkNewsOverview
stkEventsOverview
stkCategoryOverview
contentCore content pages.stkArticle
stkLargeArticle
stkNews
stkEvent
stkGlossaryTerm

Template availability and hierarchy are controlled by the STKTemplateAvailability class that implements TemplateAvailability wrapper class. The latter class contains the list of templates available on the site. Availability is configured first in the /template/availability node in the site definition and second through categories. The availability logic for categories is hard-coded in TemplateCategory. They cannot be arbitrarily declared without extending this class. TemplateCategoryUtil adds utility methods for using template categories. Subcategories are not fixed. You can set them arbitrarily in the template definition.

The hard-coded default availability logic for categories are:

  • home and functional are the only categories that can be assigned to the root page of the site.
  • home can be assigned only once per site. You can define many home page templates, for example with different column layouts, which all have category home. But you can assign only one of them at a time.
  • functional can be assigned to any page regardless of the category of the parent template. This means that you can for example have a redirect page anywhere on the site.
  • section can only be assigned to a page whose parent page has category home, section, functional or feature. In other words, it can be assigned to all pages except those whose parent is content.
  • content can be assigned to a page whose parent page has category section, content, functional or feature. In other words, it can be assigned under all pages except the home page.
  • feature can be assigned to a page whose parent page has category section, content, functional or feature. In other words, it can be assigned under all pages except the home page.

Area definitions

Area definitions are very powerful and you will find many of the configurations that distinguish the templates within these definitions. In this section we provide an overview of how area definitions are commonly used. To demonstrate we show a few examples of how the concrete templates differ from the template prototype to add functionality and features. For a more in-depth discussion of each area see the STK areas page. The examples show the flexibility of the system, but are not exhaustive. By combining them you can come up with many new possibilities.

Referencing dialogs

Area definitions can reference a dialog. This option is used in the main/intro area of all concrete templates (except stkHome) to reference a template-specific properties dialogs. See intro area for more information.

Making components available

The template prototype makes components available in areas where it makes sense to have a consistent set of components on all templates. The promotional areas: extras, promos and base, are examples. The main/content area is the distinguishing area and here components are made available in the concrete templates.

Components can be added to any list or single area. For more information see Area types.

You can add additional components to the /areas/<area name>/availableComponents node of any template. The configuration below adds the stkTextImage and stkQuotedText components in the promos area of the stkArticle template. The prototype makes the stkPromo component available so a total of three components become available in stkArticle.

 

Not all components render perfectly in all areas and you may need change the CSS sheet or component definition. For example in the above configuration stkQuotedText will not pick up the background font or quote.png image used by the CSS sheet in promos like it does in the main/content area.

 

If you want to reduce the number of components made available in the prototype you can use the enabled property to disable specific components. Note that the extends=override property cannot be used in this case because template merging does not rely on the extends mechanism.

The example configuration below uses the stkEventsOverview template.

  • This template is not an extension of any other template.
  • The addition of the /areas/promos/availableComponents node makes Magnolia aware that changes to the prototype are configured in the area.
  • The /availableComponents/stkPromo/enabled node disables the stkPromo component in the area.
  • The /availableComponents/stkExtrasContact node makes the stkExtrasContact component available instead of the stkPromo component.

Here's the new component on the /demo-project/news-and-events/events-overview page.

If you want to make different components available in a template that extends another template you can use the extends=override property.

The example configuration below uses the stkNews template:

  • This template is an extension of the stkArticle template. This is configured in the /stkNews/extends node.
  • The addition of the /areas/content/extends property set to override tells Magnolia to ignore (override) the /areas/content configuration in the stkArticle template. This configuration makes 8 content components available.
  • The addition of the /areas/content/availableComponents node makes only the stkTextImage component available for use in the stkNews template.

Restricting component access

You can restrict access to any component made available in an area in the template definition. There is an example configuration in the stkArticle template that restricts access to the stkHTML component to users assigned the superuser role. Any user with lesser permissions cannot access the component. The configuration is in Template Definitions > /pages/stkArticle/areas/main/areas/content/availableComponents/stkHTML:

  • The roles content node alerts Magnolia to a possible access restriction.
  • The superuser data node with value also set to superuser restricts access to the component to users assigned the superuser role. See Roles for more information.

You can test this by logging in as the Example Editor Eric (username/password=eric) and attempting to add the stkHTML component to the content area of any article page. The stkHTML component is not available in the selector dialog.

Magnolia 4.5.9 introduced two new features that relate to component availability. These are configured in the same way on a template level as in the prototype template. You can now also:

Changing area behavior

The main/content area is the major distinguishing factor between the templates. In the template prototype the area is defined as type=list allowing an unlimited number of sequential components to be added by default.

  • The stkHome, stkSection and content templates retain the default type. In the /areas/main/areas/content/availableComponents node, teaser are made available in the first and second templates and content components in the third.

  • The feature templates override the default type, changing it to single. The feature component is added in the /areas/main/areas/content/autoGeneration/content/singleton node. See Feature components and Autogenerated components below for more information.

Enabling areas

Most areas are enabled in the prototype and therefore need to be disabled in a specific template definition to change the default setting. This is done by adding an enabled data node under the /areas/<area name> content node and setting the value to false. Areas like stage and platform that are rarely used are disabled in the prototype. In these cases set the enabled property to true to change the default behavior.

Enabling or disabling an area:

  • Causes the entire area to either render or not render. This will happen regardless of whether the area contains content such as components, auto-generated content or content rendered by a script. The content remains in the repository and will render again when a previously disabled area is re-enabled. You can verify this by disabling extras on the stkArticle template and viewing any article page in Tools > JCR Browser (Website).

  • Will have the same effect on template extensions as it does on the base template. For example, if you disable extras on stkArticle it will also be disabled on all content templates. You can reverse this by adding the enabled property and setting it to true on the template extensions on which you would like to include the area.
  • May affect the page layout. The results you see below are mainly due to the way pages are structured and the content wrapped. Here are a few examples:
    • When extras is disabled, main area expands to use the available space.

    • When promos is disabled nothing renders in the available space.

    • When base, stage or sectionHeader are disabled the content moves up and renders as if the disabled area did not exist. This is also the behavior in preview mode when an area is enabled but contains no content. For the screenshot below we disabled the stage on stkHome template.


      When floating is enabled in main and columns set to 2, the second column in main will only render if extras is disabled. The screenshot below shows the demo-features/section-variations/floating page based on the /demo-features/stkSectionFloating template.

Adding areas

In the template definition you can add areas that are not defined in the template prototype. The main area of the stkSection template creates a new nested area, opener area.

The following changes to the prototype configuration relate to the new opener area:

  • /areas/main node:
    • Uses its own class, SectionMainArea, that defines the opener area properties.
    • Is rendered by the /section/mainArea.ftl script that is identical to the default script, /global/mainArea.ftl, except that it adds the opener area using the [@cms.area name="opener"/] tag.
  • /areas/main/areas/opener node
    • Configures the new opener area.
    • Is a single area meaning that only one component can render.
    • Is enabled and optional meaning that it is available but editors may choose to delete it.
    • Is rendered by the /section/opener.ftl script that is a standard single area script.
    • Makes the stkTeaserOpener component available in the availableComponents node.

Enabling floating

Floating means that components in the area render in a specified number of columns. By default, floating is enabled in main area in the stkHome and stkSectionFloating templates. The demo-project home page and the demo-features/section-variations/floating pages are based on these templates. Here's main area of demo-project home page.

Floating is configured in the <template name>/areas/main content node of the template definition. In the stkHome template in Template Definitions > /pages/stkHome:

  • /areas/main:
    • Uses the SectionMainArea class that defines the floating properties.
    • Is rendered by the section/MainArea.ftl script that simply renders all nested areas.
  • In areas/main/floating:
    • The enabled node is set true enabling floating. You can disable it by setting this property to false.
    • columns is set to 3 which tells Magnolia to render the components in three columns. Available options are 1, 2 and 3. Because the other nested areas are disabled, only components made available in the /areas/main/areas/content/availableComponents node render in the main area.
  • areas/main/areas/content:
    • Makes a number of teaser components available in the /availableComponents node. These components are configured to work within a floating area (see below).
    • Is rendered by the section/contentArea.ftl script. This script contains code that renders a teaserCount (see below).
  • /areas/main/areas/intro, /opener and /breadcrumb are disabled, meaning that on this template floating only happens in /areas/main/areas/content. It is not strictly necessary to disable the other nested areas.
  • /areas/extras is disabled ensuring that the page resolves to an allowedBodyClass (see below).

By default, you can configure a floating template by extending the stkHome and stkSection templates because they use the SectionMainArea class and teaser components. All other scenarios require customization. The stkSectionFloating template available in Template Definitions > /pages/demo-features/stkSectionFloating is an example of extending the stkSection template:

  • The template extends the stkSection template in the stkSectionFloating/extends node. By extension:
    • Suitable teaser components are made available in the /areas/main/content/availableComponents node.
    • The SectionMainArea class is used.
  • In the /areas/main/floating node floating is enabled with columns set to 2.
  • In the /areas/main/areas node the intro and opener areas are disabled.
  • In the /areas/extras node the extras area is disabled.

Here's the demo-features/section-variables/floating page that is based on the stkSectionFloating template. The page resolves to an allowedBodyClass=nav-col-float2 that is included as an attribute of the <body id> element. Each teaser in main area has an appended teaser id in the <div class> element.

Here are the elements that need to be considered to ensure that the components render correctly when floating is enabled:

  • The BodyClassResolver Java class resolves the page bodyClass automatically. Areas should be enabled and disabled as necessary to ensure that the page resolves to an allowedBodyClass. See Body classes for more information.
  • CSS sheets reference the bodyClass to ensure the correct styling.
  • While the number of floating columns are configured, it is the teaserCount that tells Magnolia where to render each teaser. See Teaser ids for more information.
    • The configuration of each teaser definition has has a divId and divIdPrefix property that facilitates the teaserCount.
    • The FreeMarker code in the individual components scripts assigns a teaser id and the section/contentArea.ftl script renders the teaserCount in the area.

Variations

Variations can be used in a number of ways, for example to reformat content for devices like smartphones and tablets, or specific output for groups of logged in users. See Mobile for a full discussion of the example smartphone variation used in the demo sites and Channels for more information about this core functionality.

Variations are typically configured in the site definition, but can also be configured on a template level in the template definition. See Stage for an example of how this option is used to disable the stage area for smartphones.

(warning) 4.5.3 +

On a page template level you can configure a variation that is triggered by the page URL extension. Note that this type of variation cannot be configured in the site definition.

In the example configuration below the newsletter variation disables the sectionHeader, extras, promos and base areas leaving only the main content. This variation may be suitable for example for an online version of a newsletter or a printable version of a page.

If you request content on any page based on the stkSection template and change the extension from .html to .newletter the variation content is served.

You can combine this with the smartphone variation configured in the site definition by adding the ?mgnlChannel=smartphone parameter to serve the newsletter variation in a format suitable for smartphones.

Variations are resolved by DefaultRenderableVariationResolver that combines ChannelVariationResolver and ExtensionVariationResolver.

 

This functionality should be used with caution because it allows users access to content by changing the URL extension. If used for sensitive content consider extending DefaultRenderableVariationResolver to provide additional security measures.

 

CSS and JavaScript

You can also reference template-specific CSS sheets and JavaScripts for individual templates in the template definition. This option could be useful for example for holiday campaigns or dedicated sections of a site.

The example configuration below assigns a specific CSS sheet and an additional JavaScript to the stkArticle template.

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 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 Dialog Definitions. The dialog definition is mapped to the component definition using the dialogproperty.

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 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).
  • templateScript: Path to the script that renders the component. Component scripts are accessible in 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 icon is rendered in the toolbar. (warning) 4.5.9+
  • moveable determines if the component can be moved. If set to false the move icon is not rendered in the toolbar. (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. (warning) 4.5.9+

For a full list of available component template properties and their usage see Properties.

Here is an example of making a 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.

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 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 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 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 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 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 at 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 the:

  • AreaElement class that provides for an autoGeneration node 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 extrasarea.

  • The /areas/<area name>/autoGeneration parent node and /content child node need to have these specific names. The naming convention and node structure identifies the configuration as autogenerated content.
  • The /autoGeneration/generatorClass node assigns the CopyGenerator class that allows the use of any properties available to the component referenced in the templateId property.
  • The /autoGeneration/content/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 is set to mgnl:component identifying the referenced component as a component.
    • templateId defines the path to the component definition in the <module name>:<path to definition> format.

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 that is rendered by the [cmsfn.decode] method.

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 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 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 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 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 Browser (Website) > /demo-project/service/site-map/content/singleton.

If you to change the default settings of an autogenerated component in the template definition, you need to first delete the component (singleton node) 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.

 

  • No labels