Release notes for Magnolia 4.0.1

What has changed since Magnolia 3.6

This is the first official and complete release in the 4.0 line. This is a major release, bringing a whole lot of changes. The main improvements include, but are not limited to, templating and cleaning up Magnolia's API.

  • Improved templating: we improved Magnolia's templating by providing template definition and model objects; other useful objects are also now available in the templates, reducing the need for scriplets. This gives the developer more power and flexibility, while the template code becomes more readable. See What's new in templating with Magnolia 4.0 for more details.
  • FreeMarker support: we added full support for FreeMarker templates for both page and paragraph templates. Both FreeMarker and JSP templates can be used in combination. But in addition to the JSP templates the FreeMarker templates can be loaded from the classpath, repository or file system. See our Magnolia FreeMarker integration page for more details.
  • Standard Templating Kit (STK): Magnolia now provides a full set of useful templates and paragraphs; use-case-driven templates, flexibility and extensibility are key points of the STK. Standards compliance and accessibility, too! The STK will be part of the Magnolia Enterprise Edition, but also available as a separate Badgeware download. See the Standard Templating Kit documentation for more details. Note that this first release of the STK lacks translations. Feel free to jump in and contribute!
  • Extended Templating Kit (ETK): while the STK is freely available, the ETK is only available with the Enterprise Edition. It adds advanced features like multiple site configurations.
  • New developer samples: we replaced the previous Samples module with new developer-oriented examples featuring the latest developments within Magnolia. The new developer samples show a range of functionality from basic things like templating to more advanced topics like adding custom filters or using module configuration beans. This is done with minimal code to keep the examples as simple as possible. The examples contain both FreeMarker and JSP templates.
  • In-place templating: the FreeMarker templates can be stored in the repository (which allows, amongst others, activation and quick prototyping). We plan to add WebDAV support in 4.1, so that a template workspace can be mapped to a network drive. This would allow developers to edit templates directly in their favored editor as a quick way to learn more about Magnolia or do smaller projects that do not demand the rigourous release-cycle of enterprise deployments.
  • Resource module: similar to the templates, it is useful to have the CSS files stored in the repository (and thus, under access and version control). Similar to the In-place Templating Module we will add support for WebDAV in 4.1.
  • Link API: the link API as been moved from info.magnolia.cms.link have moved to info.magnolia.link. LinkResolverImpl, LinkHelper and LinkUtil have been replaced by the single LinkUtil class. (MAGNOLIA-2542)
  • API cleanup: we cleaned up the Magnolia API by finally removing of a lot of deprecated code. Check the complete list of removed methods and classes, along with explanations of what happened to them.
  • Breaking API changes: a couple of API changes were introduced, and you might want to read about them.
  • Modules: (!) modules that were written for Magnolia 3.0 are not supported anymore, and will have to be updated.
  • Jackrabbit 1.5: Magnolia now ships with Jackrabbit 1.5, which provides performance and reliability improvement over the previous version.
  • Dependencies and 3rd party libraries: we've updated a lot of the 3rd party library we use. See MAGNOLIA-2532, MAGNOLIA-2536, MAGNOLIA-2537.
  • Multi-value support: we've introduced multi-value support in dialogs with the DialogMultiSelect / MultiValueSaveHandler combination. (MAGNOLIA-2363)
  • Logging configuration: the default logging configuration has been revised and now provides a clearer layout.
  • Java 5: Magnolia 4.0 still works with Java 1.4. However, we're moving forward, and the next releases will require Java 5.
As usual, the complete list of changes can be found on our Jira.

The Magnolia team would also like to thank everyone who reported issues or contributed patches to this release. Your continuous interest helps us make Magnolia better.

How to update from Magnolia 3.6.3

Simply follow the general update procedure, with the following additional steps:

Node Types

Update the nodetypes definitions: execute the updatenodetypes or updatenodetypes.bat script from the add-ons/magnolia-tools/bin folder of Magnolia Enterprise Edition Tomcat bundle. On a typical setup, you'll only need to pass it the -webapp argument, like for example: 
./updatenodetypes -webapp /Applications/Magnolia/apache-tomcat-5.5.25/webapps/magnoliaAuthor/

Do this for all your instances.

Templates

There is a known issue related to the update of templates, for which you will need to manually fix the templatePath property. After an update from Magnolia 3.6.x, these are incorrectly moved under a parameters subnode. Please see MAGNOLIA-2809 for details.

Modules

If you still have modules that were written for Magnolia 3.0, they will need to be adapted. The "old style" of modules is not supported anymore.

Properties

A new property was added (magnolia.logs.dir), and we generalized the usage of the magnolia.app.rootdir property. While none of this is mandatory, we recommend you update your magnolia.properties file to ensure compatibility with future releases. These are the new default values for updated properties:
magnolia.cache.startdir=${magnolia.app.rootdir}/cache
magnolia.upload.tmpdir=${magnolia.app.rootdir}/tmp
magnolia.exchange.history=${magnolia.app.rootdir}/history
magnolia.repositories.home=${magnolia.app.rootdir}/repositories
magnolia.logs.dir=${magnolia.app.rootdir}/logs
Other properties are left unchanged.

Log configuration

The logging configuration has been updated to provide better readability. If you're updating an existing instance and want to benefit from this, you will have to copy the default log4j.xml file from WEB-INF/config/default/ to your instance.

Samples

The samples have been modified. The whole configuration (templates, paragraphs, ...) and content (pages) will be backed up under /server/install/backup when you update. If you were using original or customized elements from the previous samples, we recommend you move them to a custom module.

Web.xml

To resolve some encoding issues, you will have to add the following snippet to your web.xml file. If you haven't customized yours, you can simply copy the one provided.

  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <page-encoding>UTF-8</page-encoding>
    </jsp-property-group>
  </jsp-config>

How to update from an earlier version of Magnolia

(!) Please read all release notes concerning the versions you're skipping, and follow the above procedure, along with any additional step mentioned in the release notes of the versions you're skipping.

Known issues

Templates

When updating from a Magnolia version older than 4.0, there is a known issue related to the update of templates, for which you will need to manually fix the templatePath property. After an update from Magnolia 3.6.x, these are incorrectly moved under a parameters subnode. Please see MAGNOLIA-2809 for details.

JBoss 5

There is an unfortunate issue, specifically when deploying under JBoss 5: you will need to remove the Xerces jar from the Magnolia webapps: if deploying using war files, you can remove it from the archive, or with the following Unix command zip -d path-to-magnolia.war WEB-INF/lib/xercesImpl-2.8.1.jar. If deploying using an exploded directory, simply remove the WEB-INF/lib/xercesImpl-2.8.1.jar file. See MAGNOLIA-2577 for technical details. If you get exception messages such as org.jboss.xb.binding.JBossXBException: Failed to create a new SAX parser and/or java.lang.ClassCastException: org.apache.xerces.parsers.XIncludeAwareParserConfiguration, this is the issue you're hitting.

WebSphere

When installing on WebSphere, the Derby database is no longer supported due to an issue between Derby and JackRabbit on WebSphere. Please make sure to update the default configuration to use another PersistenceManager than the Derby one. There is also an issue with Lucene 2.3.0 with WebSphere 6. For this reason it is necessary to replace WEB-INF/lib/lucene-2.3.0.jar, which is distributed with JackRabbit by default, with WEB-INF/lib/lucene-2.2.0.jar which works fine.

Weblogic 10

When deploying on Weblogic 10, there is a version conflict while using commons-lang. While Weblogic-10 is distributed with commons-lang-2.3.jar, JackRabbit and Magnolia need at least commons-lang-2.4.jar. To resolve this issue, modify setDomainEnv.sh of Weblogic and add commons-lang-2.4.jar to the PRE_CLASSPATH. Since version 2.4 of commons-lang doesn't remove any methods, but only adds new API and fixes known bugs, there is no adverse effect from this change to the Weblogic installation.

Please see the list of known issues in the administration section for more details.