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

This section explains how CSS is used in the STK.

HTML5 and CSS3 compliance

The STK complies with HTML5 and CSS3. JavaScripts are kept up to date and comply with accessibility standards.

Here are a few examples of recent additions that you will find in the HTML code. You can find them by checking the page source of the demo-project pages:

  • HTML5:
    • DOCTYPE declaration – <!DOCTYPE html>.
    • video tag including support for multiple source formats, controls and preload.
    • form tag including <type> attributes for input fields
      • type="url" for website
      • type="email" for email
      • type="date" for events
      • type=""datetime-local" for event day + time
      • type="number" min="18" max="99" for example for shopping carts or age
      • type="range" for sliders including value ranges
    • role attribute adding semantics for accessibility purposes, for example role="navigation".
  • CSS3:
    • border-radius property, including vendor prefixes, used by teaser switchers and tab boxes.
    • linear-gradient element, including vendor prefixes, used by teaser switchers and tab boxes.
    • media queries for flexible grid, images and many other elements.

When is CSS applied

CSS links are added to the page HTML at the end of the rendering process.

When a page is requested:

  1. The server generates clean HTML that does not contain JavaScript or <object> tags.
  2. In the browser the init-behaviour.js script registers the code to be executed on the DomReady event. This is done using the jQuery JavaScript library.
  3. Once the DomReady event is fired, the initialization code is executed. It enhances the HTML by plugging in behavior such as tabbed teaser animations.
    CSS styling is applied.

Theme

CSS style sheets are assigned to a theme in Themes > /<theme name>/cssFiles. See Themes for more information. The main style sheet, styles.css, is accessible in Resources > /templating-kit/themes/pop/css.

Java classes

The following Java classes are relevant to CSS styling.

ClassDescription
CssSelectorBuilder Defines the CSS properties to use, including the divClass, divID and bodyClass properties.
CssFile Bean that defines the CSS sheets that contain the presentation rules. Also makes the media attribute available and extends the Resource class.
CssSelectorSupportRenderingModel Model that allows for the definition and use of the class attribute in template scripts.

Body classes and ids

The bodyID represents the page type and the bodyClass controls the columns that render on the page. These properties are not interdependent or interrelated in any way, but in combination allow you to style pages differently while still using a single CSS file.

The main.ftl page script assigns and renders the bodyClass and bodyID properties as the first HTML element in the <body> tag of the page. Here's the relevant snippet:

…
[#if model.bodyClass?has_content]
    [#assign bodyClass = 'class="${model.bodyClass}"']
[#else]
    [#assign bodyClass = '']
[/#if]
[#if def.bodyID?has_content]
    [#assign bodyID = 'id="${def.bodyID}"']
[#else]
    [#assign bodyID = '']
[/#if]
<body ${bodyID} ${bodyClass}>
...
Here's the <body id> tag with the class attribute in the rendered HTML for the demo-features/section-variations/floatingpage.

Body ids

With the exception of form templates, each concrete template is assigned a bodyID in the template definition in Template Definitions > /pages/<template name>/bodyID. This is an arbitrary property and you can name it anything you like provided that you use the same name in the CSS.

bodyIDs used in the STK are: home, section, article, image-gallery, search-results, sitemap, faq, glossary, event and events-overview. The bodyID values correspond with the template names, for example the stkArticle template is assigned the article id, but there are a few exceptions:

  • stkNews template is assigned the article id.
  • stkNewsOverview and stkCategoryOverview templates are assigned the section id.
  • stkGlossaryLetter template is assigned the glossary id.
Here are a few rules in styles.css that show how the bodyIDis referenced in the CSS.
#home #wrapper-2 #wrapper-3 div.tw-switcher {
  margin: 0 0 20px 0;
}
…
#sitemap .links {
  border-top: 4px solid #b3b3b3;
  margin: 30px 0 30px 0;
}
…
#search-results #main h1 {
  padding-top: 10px;
}

Body classes

The number of columns on the page and the column width is controlled by the bodyClass without changing the templates. If floating is enabled in main area in the stkSection and stkHome templates, this fact is also taken into account. For more information see Main area and Enabling floating.

The bodyClass is resolved automatically by the BodyClassResolver Java class. This class is assigned to a theme in Themes > /<theme-name>/bodyClassResolver/class node.

BodyClassResolver takes into account the vertical navigation (nav), main area (col) and extras area (subcol). The resolved bodyClass depends on the final template configuration merged from the prototype and concrete temmplate definitions. For example if vertical navigation is enabled the bodyClass will contain the nav attribute.

The following are the only allowedBodyClasses:

BodyClassColumns
none (default = nav-col-subcol)3 columns: nav - main - sidebar
col1 column: main
nav-col2 columns: nav - main
col-subcol2 columns: main - sidebar
col-subcol-equal2 equal columns: main - sidebar
col-float31 large column with 3 floating teasers
col-float21 large column with 2 floating teasers
nav-col-float21 large column with 2 floating teasers and navigation on the left: nav - main
col-float2-subcol1 large column with 2 floating teasers and a right sidebar: main - sidebar
col-subcol-subcol3 columns: main - sidebar - sidebar

Where there is a configuration conflict, the page will render but the bodyClass will not be resolved or rendered in the HTML, i.e. the class attribute will be absent in the body id tag. For example, if you enable extras on the demo-features/stkSectionFloating template, this will override floating in main area causing the components to render sequentially instead of side by side. You will also find an error similar to ERROR info.magnolia.module.templatingkit.style.BodyClassResolver in your logs.

 

The promos area is independent of the resolver and not taken into account in the table above. Whether or not this area renders depends solely on the setting of the enabled property in the prototype or concrete template definition.

 

If necessary, you can override the autogenerated bodyClass property in the template definition by adding a bodyClass property and setting the value to one of the allowedBodyClasses. See Extras area > Configuration options for an example of how to do this.

Here are a few rules in styles.css that show how the bodyClass is referenced in the CSS.

/* Different images for .nav-col */
.nav-col #main .text-box-tabs {
  background: none #f2f2f2;
  width: 700px;
}
…
.col-float3 #wrapper-3,
.col-float3 #main {
  width: 100%;
...

Div ids

Most page areas are assigned a <div id> element, and in some cases also a nested <div id> element, in the area script. Where appropriate for accessibility purposes, the HTML5 role attribute is added. See Areas more about the individual areas. Here's the rendered div ids for the main, extras, promos and footer areas on a section page.

Div classes

The <div class> element is used for both page areas and components. The advantage of using a div class, as opposed to a div id, is twofold: div ids can be used only once on a page, and the same div class can be used to style multiple elements.

Many components assign the divClass property in the /parameters node of the component definition. The stkFAQ component below is one of many examples that you will find in Template Definition > /components.

Here's a sample rule in styles.css showing how the divClass is referenced in the CSS.

#main .super-list div div {
  background: #f7f8d9;
  background: url(../img/bgs/dotted-line.png) 0 0 repeat-x;
  padding: 10px 10px 10px 25px;
}
Here's the rendered HTML of the stkFAQ component that shows the use of the <div class>element.

Teaser ids

Most teaser components are assigned a divclass and divIDPrefix in the template definition in Template Definitions > <component name>/parameters. These nodes relate to CSS styling and the teaser components fall into two categories.

Standard teasers

In this context the term "standard teaser" refers to the components listed in the table below. The group includes internal, external, download, news lists and latest events teasers, but excludes the more complex aggregation teasers.

Most standard teaser components are assigned one or more of the following properties in the /parameters node:

  • divClass: Standard teasers belong to one of three families (classes) identified by the first word of the divClass property. These are:class="teaser" (main area), class="box" (extras area) and class="promo" (promos area). The second word of the divClass property, if any, adds a more specific identifier. For example standard internal teasers are marked divClass="teaser" whereas the stkNewsList teaser is marked divClass="teaser latest".
  • divIDPrefix: Three prefixes are used: teaser (main area), box (extras area) and promos (promos area).
  • headingLevel: The heading level exposed to the script, for example h2, h3.
       

In combination these properties:

  • Allow for specific styling of teasers in different areas and component variations.
  • Control the positioning of components within the defined number of columns when floating is enabled in main area of the stkSection and stkHome templates.
The init.inc.ftl script accessible at Templates > /components/teasers:
  • Renders each component in a <divId>. Where teasers are highlighted or the image hidden, the script adds a the divClass identifier.
  • Assigns and renders a teaserCount by appending sequential numbers to the divIDPrefix.
  • Assigns the headingLevel property.
This script is included by most component scripts using the [#include] directive. Where it is not included, you will find similar code in the relevant component script itself. This is also true for nested component scripts.

Here's the init.inc.ftl script.

[#assign headingLevel = def.parameters.headingLevel!]
[#assign hideTeaserImage = content.hideTeaserImage!false]
[#assign isHighlighted = content.highlighted!false]
[#assign divClass = def.parameters.divClass!]
[#assign divIDPrefix = def.parameters.divIDPrefix!]
[#-- Adding a prefix passed from the parent teaser-group --]
[#if ctx.divIdPrefix?? &amp;&amp; divIDPrefix??]
    [#assign divIDPrefix = "${ctx.divIdPrefix}-${divIDPrefix}"]
[/#if]
[#-- Setting variable teaserCount for usage in the teaser-template --]
[#assign teaserCount = ctx.index!stkfn.count(divIDPrefix)]
[#if divIDPrefix?has_content]
    [#assign divID = 'id="${divIDPrefix}-${teaserCount}"']
[#elseif def.divID?has_content]
    [#assign divID = 'id="${def.parameters.divID}"']
[#else]
    [#assign divID = ""]
[/#if]
[#if hideTeaserImage]
    [#assign divClass = "${divClass} no-img"]
[/#if]
[#if isHighlighted]
    [#assign divClass = "${divClass} highlight"]
[/#if]
In the stkSection and stkHome templates where floating is available, the main/content area is rendered by the /section/contentArea.ftl script accessible in Templates > /templating-kit/pages/section. This script includes the following code:

 

[#if cmsfn.editMode]
    <div class="teaser" id="teaser-${stkfn.count('teaser')}" cms:add="box"></div>
[/#if]
The following divClasses are used by standard teasers:
divClassDescriptionComponents
teaserTeaser in main area with an image.stkTeaser
boxTeaser in extras area with an image.stkExtrasDownloadFile
stkExtrasExternalPage
stkExtrasInternalPage
stkExtrasContentTypeRSSFeed
promosPromo teaser with an image.stkPromo
openerOpener teaser.stkTeaserOpener
teaser teaserlistLink list teaser in main area.stkTeaserPureLinkList
box linksLink list teaser in extras area.stkExtrasPureLinkList
stkExtrasDownloadList
teaser latestTeaser in main area rendering a list of latest pages.stkTeaserNewsList
stkSingleFeed
stkCombinedFeed
box latestTeaser in extras area rendering a list of latest pages.stkExtrasNewsList
teaser event-listTeaser in main area rendering of list of latest events.stkTeaserEventsList
box event-listTeaser in extras area rendering of list of latest events.stkExtrasEventsList
<divClass> no-imgVarious teasers without an image.Rendered by init.inc script.
<divClass> highlightVarious highlighted teasers.Rendered by init.inc script.

Here are a few rules in styles.css that show how the divClass and divIDPrefix is referenced in the CSS.

/* teaser with just a link list */
#main .teaserlist li {
  font-weight: bold;
}
…
/* events */
#extras .event-list {
  overflow: hidden;
  margin: 0 0 20px 0;
}
…
#main .no-img .links { /* teaser with link list */
  margin-top: 10px;
}
…
#main .teaser.highlight h2 {
  width: 290px;
}
Here's the rendered HTML for the demo-project home page. Note the teaserCount in main and promosareas.

On the stkSection template, the stkTeaserOpener component is automatically assigned <div id="teaser-1">. It is always the first component and there is only one per page. The diagram below shows the positioning of the numbered components with floating enabled and columns set to 2.

All standard teasers can include a kicker which is sourced from on the target page Page Header component. The kicker is part of the headline and is clickable. Here's a snippet from the internalPage.ftl script that renders internal teasers. This script is accessible at Templates > /templating-kit/components/teasers. The script #includes the init.inc.ftl script that assigns the headingLevel property included in the component definition.

<${headingLevel}>
     <a href="${teaserLink}">
         [#if hasKicker]<em>${kicker}</em>[/#if]
         ${title}
     </a>
 </${headingLevel}>

Other teasers

The teasers in this group are listed in the table below. It includes the more complex aggregation teasers and special teasers such as the calendar and contact teasers.

As is the case with standard teasers, these components are also assigned a divClass and divIDPrefix, but there are a few exceptions. They are distinguishable from the standard teasers because they break the teaserCount and are not designed for floating. Here's the rendered HTML for main area of the demo-project/about page that contains three components: stkOpener, stkTeaserGroup and stkTeaser. The stkTeaserGroup component is assigned <div id="teaser-group> and breaks the teaserCount.

With one exception, the divIDPrefixes of these components follow the standard pattern, i.e. teaser, box and promo. The horizontal tabbed teasers and their nested item components are assigned divIDPrefix=tab for components in both main and extras areas.

The following divClasses are used by these teasers:

divClassDescriptionComponents
teaserTeaser in stage area with an image.stkStageXL (divIDPrefix set to false).
teaser-group Grouped teaser in main area.stkTeaserGroup
box-groupGrouped teaser in extras area.stkExtrasBoxGroup
teaser wrapperCarousel teaser.stkTeaserCarousel
rack-teaserNested carousel item components.stkTeaserCarouselItem
text-box-tabsHorizontal tabbed teaser in main area.stkTeaserHorizontalTabbed
box toc-boxHorizontal tabbed teaser in extras area.stkExtrasHorizontalTabbed
toc-box-sectionHorizontal tabbed teaser item in extras area.stkExtrasHorizontalTabitemExternalPage
stkExtrasHorizontalTabitemInternalPage
stkExtrasHorizontalTabitemDownloadFile
superpromosFinger tabbed teaser.stkTeaserFingerTabbed
superpromo-sectionNested finger tabbed item components.stkTeaserFingerTabbedItem
box vcardContact teaser.stkTeaserContact
stkExtrasContact
box calendarCalendar component.stkExtrasCalendar

Components that contain nested item components use the init.inc script or similar code to render a teaser count for the nested components. Here's the rendered HTML for the demo-features/aggregation-components/grouped-teasers page. Note the absence of a teaserCount for the main components and the use of a teaserCount for the nested stkTeaserFingerTabbedItem components.

Flexible grid

The STK demo sites have use a flexible grid that adapts seamlessly to the user’s viewport. The dynamic template layouts change on-the-fly. For mobile sites, in addition to adapting to device size and proportion, unsuitable content is omitted or adapted to provide an optimal experience.

In brief, the flexible grid is achieved by the:

Here’s the demo-project home page for desktop with a screen width of 1600, 1200 and 850 pixels, and for the smartphonevariation.

Static HTML prototype

The STK bundle ships with a static HTML prototype. You can find it in the prototype folder inside the STK bundle ZIP file or download it from our Nexus repository. The prototype is a collection of STK page templates delivered as stand-alone HTML files. Referenced CSS and images are also included. The static prototype is aimed at creative teams who don't know how Magnolia works or have no particular desire to learn it. It allows designers to work on positioning, typography and color outside of Magnolia, using their own tools, in their own environment.

The prototype contains an index.html page, which serves as the starting point for all the component and page templates that are provided with the STK.

Whenever we enhance the STK, we add new HTML to the static prototype first. The static HTML is then tested on all supported browsers. Once the HTML has been perfected, templates are created.

  • No labels