Theme

Goals

• Understand how resolving image variations is possible in themes
• Learn about the imgfn templating function

Theme

• A theme is a configuration set for defining CSS, JS, images variation and resizing rules
• One theme can provide one set of multiple resources and imaging rules
• By switching a theme, different resources and imaging rules can be provided instantly to a website

Theme Functionality

• All theme functionality is purely optional

• Can be used over templating functions in any template within the system

Theme functionalities:

1. Image Resizing:
   A theme provides simple rules available in all template scripts for resizing images.
                 
2. Sharing resources:
   Themes are an easy way to add, move, change or remove resources without having to modify the head section of the HTML construct.
                          
3. Switchable Resources Sets:
   Can easily set up a bunch of different themes for other (sub)sites, variations or simply different occasions, such as switching the theme for another one that is seasonal.
                               

4. Advanced Caching Functionality for Resources:
   When providing a recourse through a theme configuration, additional functionality can be plugged in as 'infinitive cache-able resources'.

Theme Configuration by YAML

• Can be configured in any light module as a top level entity themes
• Optional

Three possible configuration entities within a theme:

1. imaging - for imaging resizing rules.
2. cssFiles - for inclusion and caching behavior of CSS resources.
3. jsFiles - for inclusion and caching behavior of JS resources.

Example of theme configuration in light module:

cssFiles:
  bootstrap:
    media: screen
    addFingerPrint: true
    link: /.resources/training-templating-website/webresources/bootstrap.css

jsFiles:
  jquery.min.js:
    addFingerPrint: false
    link: /.resources/training-templating-website/webresources/jquery.min.js
  bootstrap.min.js:
    addFingerPrint: false
    link: /.resources/training-templating-website/webresources/bootstrap.min.js

imaging:
  class: info.magnolia.templating.imaging.VariationAwareImagingSupport
  variations:
    large:
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 1600
    medium:
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 800
    small:
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 300

Assigning a Theme via Site Definition

• A theme is assigned to a site via its Site Definition
  Example of a theme configuration:
  

Resizing Images with 'damfn' and 'imgfn'

• Provides useful functions for handling of image resources.
• Commonly used for resolving image variations

Example of getting a link of an image with a variation from the template definition:

<img alt="Using damfn object."src="${damfn.getAssetLink(content.linkToAsset, "small")}">
<img alt="Using imgfn object."src="${imgfn.getImageVariationLinkFromBinary(content.imageBinary, "small")}">

Example of resolving the imageLink property and getting the resized image.

[#if content.imageLink?has_content]
  [#assign assetLink = damfn.getAssetLink(content.imageLink, "large")!]
    [#if assetLink?has_content]
      <img class="img-responsive" src="${assetLink}" alt="">
    [/#if]
[/#if]

Importance of Using Image Variations

Problem/Requirements

• The image assets for the website are rather large
• The components on the page require smaller images
• Even if Bootstrap CSS resizes the images to fit the layout, the browser still loads the big images
• You want to render small images on the page
• But also want to keep the big original images in the Assets App in case they are needed elsewhere

Best practice

• If you need different sizes of the same image, DO NOT upload multiple copies (variations) of the same image to your DAM repository
• Instead, upload the image only once and define image size variations in your theme

No Variation Defined

• What happens if the image variation is not defined?
• Will Magnolia throw an error?

Answer

• No, it just logs a warning and returns the original asset

  WARN ia.templating.imaging.VariationAwareImagingSupport: Supplied variation [xxlarge] could not be found. Please update your configuration.

• If a variation cannot be found but the original asset exists, the damfn templating function returns the original asset
• As a result the website still looks OK but serves large original images, which is slower and wastes bandwidth

Dynamic Resources Includes

In Static Web 'Resources' and 'resfn' Helper, you learned how to reference web resources both in a static manner and using the resfn function:

<head>
	${resfn.css("/training-templating-foundation.*css")}
</head>

There is another way to dynamically include resources and that is through the theme in a site definition.

Benefits of having a dynamic resources includes in a site scope:

• Be able to reference all resources of the same type
• For a growing number of resource files, forgetting to reference a file will be avoided

Example of dynamic resources includes placed in the <head> tag: