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

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 STK areas. 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 dialog. See intro area for more information.

Node nameValue

 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

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: extraspromos 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.

Node nameValue

 stkArticle

 

 areas

 

 promos

 

 availableComponents

 

 stkTextImage

 

 id

standard-templating-kit:components/content/stkTextImage

 stkQuotedText

 

 id

standard-templating-kit:components/content/stkQoutedText

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.

    Node nameValue

     stkEventsOverview

     

     areas

     

     promos

     

     availableComponents

     

     stkPromo

     

     enabled

    false

     stkExtrasContact

     

     id

    standard-templating-kit:components/extras/stkExtrasContact

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.

    Node nameValue

     stkNews

     

     areas

     

     main

     

     areas

     

     content

     

     availableComponents

     

     stkTextImage

     

     id

    standard-templating-kit:components/content/stkTextImage

     extends

    override

     dialog

    standard-templating-kit:pages/news/stkNewsProperties

     extends

    /modules/standard-templating-kit/templates/pages/stkArticle

     subcategory

    news

     title

    templates.stkNews.title

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 STK > Template Definitions /pages/stkArticle/areas/main/areas/content/availableComponents/stkHTML:

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

    Node nameValue

     stkArticle

     

     areas

     

     main

     

     areas

     

     content

     

     availableComponents

     

     stkHTML

     

     roles

     

     superuser

    superuser

     id

    standard-templating-kit:components/content/stkHTML

     stkTextImage

     

     stkQuotedText

     

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.

(warning) 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

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 stkHomestkSection and content templates retain the default type. In the /areas/main/areas/content/availableComponents node, teasers are made available in the first and second templates and content components in the third.

    Node name

     stkHome

     areas

     main

     areas

     content

     availableComponents

     stkTeaser

     stkTeaserNewsList

     stkTeaserEventsList

     stkTeaserGroup

     stkTeaserHorizontalTabbed

     stkTeaserPureLinkList

    Node name

     stkArticle

     areas

     main

     areas

     content

     availableComponents

     stkTextImage

     stkQuotedText

     stkLinkList

     stkFlash

     stkVideo

     stkTeaserHorizontalTabbed

     stkDownloadList

     stkContact

     

  • 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 for more information.

    Node nameValue

     stkImageGallery

     

     areas

     

     main

     

     areas

     

     content

     

     autoGeneration

     

     content

     

     singleton

     

     maxImages

    9

     nodeType 

     mgnl:component

     templateId

     standard-templating-kit:components/features/stkImageGallery

     generatorClass

     info.magnolia.rendering.generator.CopyGenerator

     type

    single

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 property node under the /areas/<area name> 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.

    Template definition

    Node nameValue

     stkArticle

     

     areas

     

     extras

     

     enabled

    false

     bodyID

    article

    JCR Browser (Website)

    Node nameValue

     demo-project

     

     about

     

     subsection-articles

     

     article

     

     extras

     

     extras1

     

     0

     

     00

     

     

  • 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 basestage 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 classSectionMainArea, 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.

      Node nameValue

       stkSection

       

       areas

       

       main

       

       floating

       

       areas

       

       intro

       

       opener

       

       availableComponents

       

       stkTeaserOpener

       

       id

      standard-templating-kit:components/teasers/stkTeaserOpener

       description

      areas.templates.main.opener.description

       enabled

       true

       optional

      true

       templateScript 

       /templating-kit/pages/section/opener.ftl

       title

      areas.templates.main.opener.title

       type

      single

       content

       

       class

      info.magnolia.module.templatingkit.templates.SectionMainArea

       templateScript

      /templating-kit/pages/section/mainArea.ftl

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 node of the template definition. In the stkHome template in STK > 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 12 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).

    Node nameValue

     stkHome

     

     areas

     

     main

     

     floating

     

     columns

    3

     enabled

    true

     areas

     

     content

     

     availableComponents

     

     templateScript

    /templating-kit/pages/section/contentArea.ftl

      title

    templates.stkHome.areas.main.content.title

     intro

     

     class

    info.magnolia.module.templatingkit.templates.MainAreaIntro

     enabled

    false

     opener

     

     breadcrumb

     

     class

     info.magnolia.module.templatingkit.templates.SectionMainArea

     templateScript

    /templating-kit/pages/section/mainArea.ftl

     extras

     

     inheritance

     

     class 

    info.magnolia.module.templatingkit.templates.ExtrasArea

     enabled

    false

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 STK > 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.

    Node nameValue
     pages 

     demo-features

     

     stkSectionFloating

     

     areas

     

     main

     

     floating

     

     columns

    2

     enabled

    true

     areas

     

     intro

     

     enabled

    false

     opener

     

     enabled

    false

     extras

     

     inheritance

     

     class

    info.magnolia.module.templatingkit.templates.ExtrasArea

     enabled

    false

     base

     

     extends

    /modules/standard-templating-kit/templates/pages/stkSection

     title

    Section Floating

Here's the demo-features/section-variables/floating page that is based on the stkSectionFloating template on the public instance. The page resolves to an allowedBodyClass=nav-col-float2 that is included as an attribute of the body element. Each teaser in main area is wrapped in a DIV 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.