Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

With the Magnolia 5.4.4 release we continue to improve Magnolia Templating Essentials (MTE). We strive to make template use easier in projects especially for front-end developers and developers new to Magnolia. We retain our primary commitment to make AdminCentral easy and comfortable for content authors.

What's new?

MTE templates move to a new module Magnolia Templating Kit (MTK)

MTE templates (scripts, definitions) move to a new module Magnolia Templating Kit (MTK). The Magnolia Templating Essentials (MTE) module stays but contains only templating function libraries and some model classes.


  • As a developer, you can decide which templates to use in your project:
    • Use MTK templates.
    • Use another library of components.
    • Create your own templating kit.
  • The goal of MTE is to be future-proof and front-end agnostic. With this change we move the front-end technology to a new module where it can evolve independently.
  • We follow and promote a pattern of a templating kit which is a collection of templates packaged together.

MTK is available as a light module

The MTK is included in the standard bundles, or you can add it to your project as usual via Maven or as a jar. However, for the convenience of front-end developers the templates are also available as a zip file which you can extract into your resources directory. This allows any developer to quickly see and understand the templates, use them as a starting point for their own custom templates, or even override the jar supplied MTK templates. If using the files in this way, consider them as your own project files - as this directory will not be managed or migrated by Magnolia. See included readme for details.


MTK templates don't use model classes anymore

While model classes can be very beneficial, sometime they are not necessary. Model classes are difficult for front-end developers to access because they are written in Java. This makes the functionality of templates hard to understand and modify.

In this release we moved simple template logic from MTK model classes into the template scripts. All developers can quickly understand how a template works because they can see the logic in the template script.

This change only impacts the MTK templates, we still recommend using model classes in your own templates as appropriate for your project or team.

Migrating from earlier versions of MTE

There are no automatic version handlers for pre-1.0 versions of MTE. Here are some tips if you would like to migrate to MTE 0.8.

  • Components have moved from the MTE module to the MTK module. All references to MTE templates must be changed to use the mtk prefix.
    Example: change 
    mte:components/html to mtk:components/html
  • Teaser components teaserteaserInternalteaserExternal and teaserDownload have merged into one component teaser. All references to teaser components must be changed to point to the new component and must include the linkType property of "page", "external" or "download".
  • Models have been removed. If you used the MTE models in your custom templates you have three options:
    • Create your own models.
    • Use templating functions instead.
    • Update your templates to behave the way the new MTK components do. They use simple FreeMarker assignments instead of models.

App for processed resources

Magnolia 5.4.4 brings back the ability to work with processed resources. The user community passionately supports Magnolia-processed resources so we keep this feature in the product.

Install the Processed Resources app to work with processed resources. The app is not installed by default. Download the module and add it to your project.

(warning) This feature is limited to resources that are in the JCR resources workspace. Resource files on the file system or classpath cannot be processed.

Duplicate resources problem resolved

Since 5.4, previously installed resources appeared twice in the new Resource Files app: once from the classpath with extension and again from the JCR with extension stripped.

  • For installing resources, we discourage stripping extensions,  InstallTextResourceTask  and InstallBinaryResourceTask  both support not stripping extensions.
  • For updating, we now provide the ResourceCleanUpTask  to help restoring extensions in resource node names. The ResourceCleanUpTask also removes empty or redundant properties.
  • We applied this to STK and theme-pop installed resources - so, no more duplicated resources for STK and theme pop. If you want to get rid of duplicated resources within your custom modules, you have to write your own version handler using ResourceCleanUpTask.
  • Additionally, mind that since 5.4, installing resources is not required anymore (with the exception of processed resources), if you serve them through the new loading cascade.
  • (warning) Users installing resource references in scriptloaders need to update the paths of those scriptloaders to include the extension for install, and set stripExtension to false on the  InstallReferenceResourceTask .

Loading of classpath resources (.yaml, .ftl) is improved

  • Template scripts (.ftl) added in the classpath are now observed and loaded.

  • You can configure the file types of resources that Magnolia should observe in the classpath and reload on-change. Configure the types with a new property in your files.

    If not configured, the classpath scanner use a default value .*\\.(ftl|yaml)$.

JCR browser allows to switch between workspaces via dropdown

Magnolia 5.4.4 introduces a new JCR app that allows you to browse all Magnolia workspaces. You can switch between workspaces in a dropdown, display system properties and see the node type of each entry. New workspaces are automatically added to the app. Read JCR Browser app documentation to learn more.

New i18n API can be used for template scripts

5.4.4 closes a gap in i18n usage in template scripts. The new i18n API now fully supports template scripts. This means, there is no more need to provide an i18nBasename in a template definition. Template labels can be handled with new i18n API and a new key generator was introduced to generate keys for page and component definitions.

However, you can still use the old API.

ConfiguredRenderableDefinition #getI18nBasename and #setI18nBasename are deprecated. 

Demo improvements

Public User Registration

The PUR feature is now demonstrated in the Travel Demo. The header now contains login and registration links. A registered user has access to a special Member Content page. Password recovery and profile updating is also included.  MGNLDEMO-104 - Getting issue details... STATUS

Multi-step Forms

Advanced form features are demonstrated including multi-step form with breadcrumbs, a conditional step, a summary, every available form field, validation and email sending. Click the Book tour button in the demo to try the advanced form yourself. MGNLDEMO-103 - Getting issue details... STATUS

Several related form bugs are also fixed.

Usability improvements

  • New feature: you may now select the JCR workspace in the "JCR app". JCR system properties can be shown as well by selecting a filter, but are hidden by default. MGNLUI-2496
  • Improved: if your license is about to expire, we send a warning message to administrators through Pulse. MGNLEE-419
  • Improved: if your license has expired, we send an error message to all users through Pulse. MGNLEE-418
  • Improved: we've improved the way multi-value fields handle required fields. MGNLUI-3313
  • Fixed: Page editor: the bars of an edited area or component now remain selected and in view after you've saved changes. PAGES-41
  • Fixed: if you duplicate an item in a list or tree, the duplicate is now added right after the item it duplicates. MGNLUI-2927, MGNLDAM-631
  • Fixed: if you maximize a text area, the button below to save your changes are now no longer hidden. MGNLUI-3604

Fixed publishing and unpublishing of segments and personas

Publishing and unpublishing of segments and personas including child nodes was failing. The fix involves changing the supertype (node type) of personas and segments from mgnl:contentNode to mgnl:content. The fix also removes any incorrectly created nodes from the mgnlVersion workspace. This will lead to a loss of versions of personas and segments.


  • API change in   PageEditorListener  and  PageEditorServerRpc . The page-editor now reports broken templates in case edit-bars cannot be injected (for instance due to missing or misplaced @cms tags). PAGES-47
  • Fixed: Invalid message patterns aren't breaking the UI anymore. MGNLUI-3701
  • Improved: MIME type for JCR export is now changed from application/octet-stream to application/xmlMAGNOLIA-6479
  • Improved: A subapp to create, edit and delete themes has been added to the Site appMGNLSITE-28
  • Improved: Link field works to choose items from any content app. See Using link fields with JCR-agnostic target appsMGNLUI-3725

An aggregated change log for 5.4.4 contains all the changes.

This release is a recommended update for all users of Magnolia 5.

Updated modules

This release includes the following new module versions:

  • Advanced Cache 1.7.2
  • Community Edition 5.4.4
  • Content Translation Support 2.1.2
  • DAM 2.1.3
  • Demo 0.9
  • Enterprise Edition 5.4.4
  • Form 2.3.3
  • Google Analytics 1.3.1
  • Groovy 2.4.2
  • Imaging 3.2.4
  • Language Bundles 1.0.3
  • Magnolia 5.4.4
  • Magnolia Templating Essentials 0.8
  • Pages app 5.4.3
  • Personalization 1.2.3
  • Processed Resources 1.0
  • Public User Registration 2.5.1
  • Resources 2.4.3
  • Site 1.0.4
  • Standard Templating Kit 2.9.3
  • UI 5.4.4

The Magnolia team would also like to thank everyone who reported issues, contributed patches, or simply commented on issues for this release. Your continued interest helps us make Magnolia better. Special thanks go to:  Sven Bach, Ronald Ten Berge, Ravish Bhagdev, Casper Biever, Rainer Blumenthal, Nils Breunese,Natascha Desmarais, Kib Erne, Joerg Von Frantzius, Florian Fuchs, Vincent Gombert, Grégory Joseph, Ed King, Christian Menzel, Ngoc Nguyenthanh, Mike Nuttall, Roland Polzer, Frank Sommer, Steve Surace, Marek Swiecznik, Richard Unger, Edgar Vonk and Tom Wespi.

How to update from earlier versions

Changes from 5.4.x file

Add the following lines:

magnolia.resources.dir = ${magnolia.home}

Important changes for Magnolia 5.2 and 5.3 users

If you had STK installed

If you continue to work with STK, use the new magnolia-enterprise-pro-stk-bundle as a basis for your project. It includes Enterprise Pro, STK and the old demo project. You get all STK functionality out of the box. Exclude the demo-project if it's in your way.

Jackrabbit configuration

In order to enable getting an HTML excerpt in a query result, you should update the configuration files of your Jackrabbit instances. Add the two <param/> directives within your <SearchIndex> block.

  <!-- more params here -->

  <!-- needed to highlight the searched term -->
  <param name="supportHighlighting" value="true"/>
  <!-- custom provider for getting an HTML excerpt in a query result with rep:excerpt() -->
  <param name="excerptProviderClass" value="info.magnolia.jackrabbit.lucene.SearchHTMLExcerpt"/>

log4j.xml addition

Add the log configuration for org.reflections

 <category name="org.apache.jackrabbit">
    <priority value="WARN" />
 <!-- Reflections library spoils logs with hundreds of harmless warnings; tries to look into native libs but none of its DefaultUrlTypes can handle them. -->
  <category name="org.reflections">
    <priority value="ERROR" />
  <category name="com">
    <priority value="WARN" />

How to update from Magnolia 5.2 and earlier

To update your project, follow the standard update procedure, then make the following changes:

  1. Update your content apps with the content app upgrade task. It automatically takes care of the following:
    • Using the content connector.

    • Updating configuration of availability rules and default rule classes

    • Updating selected action definitions with node-type based availability

  2. If you used the DAM: 
    • Replace DamManager with AssetProviderRegistry.
    • See DAM and the STK and DAM templating on how to use assets in your templates.
    • The DAM changes have no impact on the STK. There is no need to modify Freemarker scripts because the new DAM API is abstracted from STK.
  3. If you have a custom jBPM workflow:
    • In the info.magnolia.module.workflow.jbpm.JbpmWorkflowManager#completeWorkItem method, checking for present parameters is obsolete and refers to publication related workitems. The method is no longer used for completing a workitem in the new human task context. It is still valid in the context of completing service tasks, however.
    • Stop using the info.magnolia.module.workflow.jbpm.JbpmWorkflowManager#getWorkItem method. It was used to complete a work item for human tasks. Furthermore, the wrapper we initialize only holds the mgnlData map.

    • The previously hardcoded mgnlData parameter is now configurable in /modules/workflow/commands/workflow/activate/activate/parameterMapName.

  4. If you have custom widgets or Vaadin add-ons:
    • Magnolia's default widgetset was relocated to info.magnolia.widgetset.MagnoliaWidgetSet.
    • Update your webapps's file.
    • Otherwise Magnolia will automatically fall back to the new widgetset but will issue warnings during upgrade, and whenever a user logs in to Magnolia.

How to update from Magnolia 4.5 and earlier

Are you running on Magnolia 4.5 or earlier? It’s time to move to 5. Contact us for migration support and look at the migration process.

Known issues

Allocate more JVM memory

Magnolia 5.4.2 ee-bundle may require you to allocate more memory the Java Virtual Machine (JVM). If you see a java.lang.OutOfMemoryError in the startup log or the system stops responding during installation, increase the Java heap size. The default maximum heap size is 512M. Try a higher amount such as 1024M. We are working on uncovering the root cause for the increased memory need.

See: Java out of memory

Processed Resources app conflict

If you upgrade to Magnolia 5.4.4 from 5.4.2 or earlier then you will experience UUID conflict if you try to also install the new Processed Resources app during the upgrade.

java.lang.RuntimeException: Error importing config.modules.processed-resources-app.dialogs: a node with uuid a53f308a-0d6a-4bb9-a5f8-6f11ff68504d already exists!

To workaround this issue complete the upgrade before installing the Processed Resources app.