Magnolia 6.0 reached end of life on June 26, 2019. This branch is no longer supported, see End-of-life policy.
A theme is a collection of resource files that gives a site its visual identity through the use of colors and typography. A theme consists of Cascading Style Sheets (CSS), Javascript files and an imaging configuration which tells the Imaging module what to do with images for a particular page or component.
A theme is a module or part of a module composed of CSS, JS, and images.
The Site module provides theme functionality. You can only create a theme if you use this module and have configured a site definition.
Theme resources can be stored in light (YAML) or Maven modules. Themes can reside in a dedicated theme module or form part of another module. A special module version handler is not necessary.
All Magnolia resources, including theme resources, are loaded under the /.resources
("dot resources") path.
/src/main/resources/<moduleName>
and any subfolder./<moduleName>/webresources/
Theme resources can also be loaded from an external source by specifying the full URL. This is very useful if you use a CDN to store, cache and deliver your static resources.
See Resources and Module structure for more.
Themes offer a number of benefits:
Themes can be configured:
The configuration must reside in the themes
folder of the module in
/<module-name>/themes/<theme-name>
. This can be done in YAML or JCR.
The old and deprecated location for themes is
site/config/<theme-name>
. Themes in this location could only be configured in the JCR. Themes configured in the old location should be moved to the new location.
travel-demo-theme
in travel-demo/themes/travel-demo-theme.yaml.
cssFiles: #CSS files configuration jsFiles: #JavaScript files configuration imaging: #Imaging variations configuration
Node name |
---|
travel-demo-theme |
cssFiles |
jsFiles |
imaging |
Three configuration nodes define the individual elements of a theme:
travel-demo-theme | |
| Optional References CSS files. |
| Optional References JavaScript files. |
| Optional Defines Image variations a.k.a renditions. |
Links to CSS resources are configured in the cssFiles
node of the theme.
CSS defines the presentation semantics of an HTML document, and creates the look and feel of the site.
Example: cssFiles
configuration in travel-demo-theme
in travel-demo/themes/travel-demo-theme.yaml
.
cssFiles: bootstrap: addFingerPrint: true link: /.resources/travel-demo-theme/libs/twitterbootstrap/css/bootstrap.min.css media: all roboto-condensed: addFingerPrint: true link: https://fonts.googleapis.com/css?family=Roboto+Condensed:400,300,700 media: all slick: addFingerPrint: true link: /.resources/travel-demo-theme/libs/slick-carousel/css/slick.css media: all slick-theme: addFingerPrint: true link: /.resources/travel-demo-theme/libs/slick-carousel/css/slick-theme.css media: all travels-magnolia: addFingerPrint: true link: /.resources/travel-demo-theme/css/travels-magnolia.css media: all video: addFingerPrint: true link: /.resources/mtk/css/video.css media: all jsFiles: #JavaScript files configuration imaging: #Imaging variations configuration
Node name | Value |
---|---|
my-theme | |
cssFiles | |
bootstrap | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/libs/twitterbootstrap/css/bootstrap.min.css |
media | all |
roboto-condensed | |
addFingerPrint | true |
link | https://fonts.googleapis.com/css?family=Roboto+Condensed:400,300,700 |
media | all |
slick | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/libs/slick-carousel/css/slick.css |
media | all |
slick-theme | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/libs/slick-carousel/css/slick-theme.css |
media | all |
travels-magnolia | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/css/travels-magnolia.css |
media | all |
video | |
addFingerPrint | true |
link | /.resources/mtk/css/video.css |
media | all |
Properties:
cssFiles | optional CSS node of the theme. |
| required Arbitrary node name. Add a node for each sheet. |
| optional Embeds a file content fingerprint in the resource URL. The fingerprint consists of a timestamp in the |
| required Path to the CSS file that is added to the HTML. See Adding style to HTML for more. See also Web resources and Origins and loading order for different options for storing and loading resources. |
| optional Media associated with the linked CSS file. If you use a responsive web design framework like Bootstrap or Foundation set this property to |
| optional Defines the conditional comment attribute for the linked CSS file. Conditional comments are used to overcome the limitations of legacy browsers such as Internet Explorer 9 and earlier. For example, the conditional comment " <!--[if lte IE9]> //inclusion of the stylesheet or javascript resource <![endif]--> |
This simple theme example uses only the default Bootstrap minimized CSS with no customizations.
Links to JavaScripts are configured in the jsFiles
node of the theme.
JavaScript is responsible for client-side functionality such as carousel paging, AJAX, menu animations, trees, embedded video player, mouse wheel support, Google Analytics and much more.
Example: jsFiles
configuration in travel-demo-theme
in travel-demo/themes/travel-demo-theme.yaml
.
cssFiles: #CSS files configuration jsFiles: respimage: addFingerPrint: true link: /.resources/travel-demo-theme/libs/lazysizes/respimage.min.js lazysizes: addFingerPrint: true link: /.resources/travel-demo-theme/libs/lazysizes/lazysizes.min.js modernizr: addFingerPrint: true link: /.resources/travel-demo-theme/js/modernizr-2.6.2.min.js jquery: addFingerPrint: true link: /.resources/travel-demo-theme/js/jquery-1.10.2.min.js js.cookies: addFingerPrint: true link: /.resources/travel-demo-theme/js/js.cookies-2.1.2.js jquery.object-fit-cover-simple: addFingerPrint: true link: /.resources/travel-demo-theme/js/jquery.object-fit-cover-simple.js slick: addFingerPrint: true link: /.resources/travel-demo-theme/libs/slick-carousel/js/slick.min.js addtoany: link: https://static.addtoany.com/menu/page.js imaging: #Imaging variations configuration
Node name | Value |
---|---|
my-theme | |
jsFiles | |
respimage | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/libs/lazysizes/respimage.min.js |
lazysizes: | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/libs/lazysizes/lazysizes.min.js |
modernizr | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/js/modernizr-2.6.2.min.js |
jquery | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/js/jquery-1.10.2.min.js |
js.cookies | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/js/js.cookies-2.1.2.js |
jquery.object-fit-cover-simple | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/js/jquery.object-fit-cover-simple.js |
slick | |
addFingerPrint | true |
link | /.resources/travel-demo-theme/libs/slick-carousel/js/slick.min.js |
addtoany | |
link | https://static.addtoany.com/menu/page.js |
Properties:
jsFiles | optional JavaScript node of the theme. |
| required Arbitrary node name. Add a node for each JavaScript file. |
| optional Embeds a file content fingerprint in the resource URL. The fingerprint consists of a timestamp in the |
| required Path to the JavaScript file. See Web resources and Origins and loading order for different options for storing and loading resources. |
Here's an example JavaScript alert box using JQuery and the default Bootstrap minimized CSS.
Themes can make use of the Imaging module to preconfigure image variations. A variation is a specific configuration that defines features of a target image. Variations can range from complex operations, such as applying filters and overlays, to simple resizing of the target image.
Variations are an effective alternative to resizing images with CSS:
Variations are configured in the imaging
node of the theme.
Example: imaging
configuration in travel-demo-theme
in travel-demo/themes/travel-demo-theme.yaml
.
cssFiles: #CSS files configuration jsFiles: #JavaScript files configuration imaging: class: info.magnolia.templating.imaging.VariationAwareImagingSupport variations: "1600": class: info.magnolia.templating.imaging.variation.SimpleResizeVariation width: 1600 "1366": class: info.magnolia.templating.imaging.variation.SimpleResizeVariation width: 1366 #...... "240": class: info.magnolia.templating.imaging.variation.SimpleResizeVariation width: 240 "1600x1200": class: info.magnolia.templating.imaging.variation.SimpleResizeVariation height: 1200 width: 1600 "1366x1024": class: info.magnolia.templating.imaging.variation.SimpleResizeVariation height: 1024 width: 1366 #..... "240x180": class: info.magnolia.templating.imaging.variation.SimpleResizeVariation height: 180 width: 240
Node name | Value |
---|---|
travel-demo-theme | |
imaging | |
variations | |
1600 | |
class | info.magnolia.templating.imaging.variation.SimpleResizeVariation |
width | 1600 |
1366 | |
... | |
240 | |
1600x1200 | |
class | info.magnolia.templating.imaging.variation.SimpleResizeVariation |
height | 1200 |
width | 1600 |
1366x1024 | |
... | |
240x180 | |
class | info.magnolia.templating.imaging.VariationAwareImagingSupport |
Properties:
imaging | optional Imaging node of the theme. |
| required Image variations node. |
| required The name of the variation, a.k.a the rendition name. The name is used to call the variation in template scripts. Add one node for every variation. |
| required You can use one of the available classes or create a custom one. The available properties depend on the class used for the variation. Any custom class must implement Variation . MTE module provides SimpleResizeVariation that resizes images to a defined size in pixels (see below for available properties). |
| Add properties that are supported by the class used. |
| required VariationAwareImagingSupport provides support for variations. |
| optional Enables and disables variation support. |
The SimpleResizeVariation
class is suitable for most resize variations. It resizes the original image to a defined size in pixels.
Properties:
<variation name> | |
| required
|
| optional, default is Whether cropping is allowed. |
| optional An integer that defines the height in pixels. |
| optional An integer that defines the width in pixels. |
Behavior:
ImagingException
and the image displays in it's original uploaded size.false
, the image is resized to the specified size, and may be distorted (stretched).See damfn and How to work with images using damfn for how to use variations in your scripts.
Themes are assigned to a site in the theme
node of the site definition in the Site app.
Example: Travel Demo Site Definition (CE)
Node name | Value |
---|---|
templates | |
theme | |
name | travel-demo-theme |
i18n |
Properties:
theme | required Theme node. |
| required The value of this property must match the name of the theme configured in |
Theme resources are typically added to the <head>
element of a page template.
Retrieve the configured theme configured over the sitefn function class:
[#assign site = sitefn.site()!] [#assign theme = sitefn.theme(site)!]
Iterate over the theme configuration and include the configured resources:
[#list theme.cssFiles as cssFile] <link rel="stylesheet" href="${cssFile.link}" media="${cssFile.media}" /> [/#list] [#list theme.jsFiles as jsFile] <script src="${jsFile.link}"></script> [/#list]
Theme definitions from all sources and origins are available in the Definitions app. Select theme
in Of type to find all theme definitions. You can hotfix themes in the Resource Files app. Select the theme definition and click Show in Resources in the Definitions app to access the file.
Example: travel-demo-theme in Definitions app and Resource files app.