Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
A site definition allows you to add features such as image variations to your site. This page explains how to configure image variations in a theme, which is referenced in the site definition.
Before you proceed read How to work with images using damfn.
Why use image variations?
The image assets for Eric's cars 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. We want to render small images on the page but we want to keep the big original images in the Assets app in case we use them elsewhere.
Configuring a theme
Keep in mind that you can only have one site with Magnolia Community Edition. In this tutorial we add a new theme and reference it in the existing travel
site definition.
A theme can be configured in YAML in any module and must reside in the themes
folder of the module.
Create a themes
folder in /one-pager-module
:
one-pager-module/ ├── dialogs/ └── templates/ └── themes/ └── my-first-website.yaml └── webresources/
Defining image variations in a theme
Create my-first-website
theme definition with three image variations : large
, large-square
and xxlarge
.:
imaging: class: info.magnolia.templating.imaging.VariationAwareImagingSupport variations: large: class: info.magnolia.templating.imaging.variation.SimpleResizeVariation width: 730 large-square: class: info.magnolia.templating.imaging.variation.SimpleResizeVariation width: 730 height: 730 xxlarge: class: info.magnolia.templating.imaging.variation.SimpleResizeVariation width: 1140
Referencing a theme
Themes are referenced in the themes
node of a site definition which is configured in the Site app.
Open the Site app and change the value of the /theme/name
property to my-first-website
.
Node name | Value |
---|---|
templates | |
theme | |
name | my-first-website |
i18n |
Using image variations
Although we did not mention it, the code in the previous pages already uses imaging variations. The damfn templating functions return resized images when you pass the desired variation name as an argument:
-
damfn.getRendition(itemKey, renditionName)
returns anAssetRendition
for theitemKey
andrenditionName
(variation name). -
damfn.getAssetLink(itemKey, renditionName)
returns a link for the same.
Background image
To render the background image we pass the variation name xxlarge
:
<style> [#if content.introBgImage?has_content] [#assign assetRendition = damfn.getRendition(content.introBgImage, "xxlarge")! /] [#if assetRendition?has_content] .intro-section { background: url(${assetRendition.getLink()}) no-repeat center center; background-size: cover; } [/#if] [/#if][#-- eof: introBgImage --] </style>
Product image
To render a car image we use the large
variation:
<div class="big-box"> [#if product.image?has_content] [#assign imgRef = damfn.getAssetLink(product.image, "large")!] [#if imgRef?has_content] <img class="img-responsive img-rounded" src="${imgRef}" alt="${productTitle!}"> [/#if] [/#if] </div>
Image in the textImage component
The macro that renders Eric's profile image uses the large
and large-square
variations depending on what the user has selected in the dialog:
[#if "roundedEdges"==content.imageStyle!] <img class="img-responsive img-rounded" src="${damfn.getRendition(asset, "large").getLink()!}"/> [#elseif "circle"==content.imageStyle!] <img class="img-responsive img-circle" src="${damfn.getRendition(asset, "large-square").getLink()!}"/> [#else] <img class="img-responsive" src="${damfn.getRendition(asset, "large").getLink()!}"/> [/#if]
What happens if no variation is defined?
But what happens if the image variation is not defined? Will Magnolia throw an error? 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. So the website looks OK but serves large original images, which is slower and wastes bandwidth.
Testing image variations
How can you test that the variations are working? Does Magnolia now resize the images?
Reload the page and inspect the image in your browser.
Example: The original Fiat Cinquecento image is 1024 x 741 pixels. Magnolia resizes it to 730 pixels as defined in the large
variation. Boostrap resizes the image further to fit the parent element in a responsive way.
Congratulations!
You created a website with Magnolia. You know how to manage content in an app and how to display it on the site. You created your first light module and learned the basics of working with images.
See Tutorials for your next learning goal.