This page contain's best practices for developing a custom Magnolia CMS project. Some of them are not specifically related to migration, but might help in improving the overall maintainability of your project and help minimize the effort needed for a successful migration process.

Create a clean structure for development

If you're working with Magnolia projects, it's a good idea to structure your projects based on Maven because then your development is much more aligned to the Magnolia way and it easier for you to include existing modules into your development project, if using Maven is not possible in your environment at least follow the standard module structure.

Make use of existing Maven features:

  • use the parent POM/inheritance mechanism in Maven
  • don't declare dependencies multiple times with version information in several project modules if not necessary

More notes about your modules:

  • clean up your module by using separate modules for different tasks - for example define modules for themes/templates/other stuff
  • put all resources, configuration, template scripts (...) in your own modules
  • make use of Magnolia module version handling

More Resources:

Development Repository

Your development repository differs from a repository used in a live/production environment in the way that you should be able to delete your development repository at any time in the development process.

Follow these rules regarding your development repository:

  • don't create a dependencies on a specific repository because of configuration stored in it, for example inline templates (templates served from the repository and not from your module)
  • put templating stuff in your own modules
  • don't directly manipulate any original STK component/element, always work with your own modules and configuration 
  • in general, modules should be self-contained

Restructure templates, paragraphs, dialogs before migration

In Magnolia 4.4, templates and other related objects are referenced from the content by an arbitrary name stored in the node's meta data. Because of this, it's actually rather easy to change this name, you can even do a simple search/replace in your bootstrap files.

As of Magnolia 4.5, these references are stored in an ID, containing the path to the referenced object. This results in a much more clear structure than before, an element stored under a .../dialogs/... path can easily be identified as dialog.

Because it's a lot more work renaming/replacing these ID references, we recommend cleaning up your template, paragraph and dialog structures before doing a migration. Use meaningful names, folders and paths for templating objects. 

Make optimal use of the extends feature

You may have heard about using the extends mechanism in Magnolia. If not, please consult some of the existing documentation:

Don't extend the default site configuration

Based on practical experience it's considered best practice to not extend the default site configuration. Remember that when adding a new website,  it is automatically linked to the available default site configuration. 

This might introduce one or more of the following disadvantages:

  • when adding something new you are always depending on your own changed default, you don't see the original state provided by the standard Magnolia templates
  • it's hard to see what the original configuration was if you're working on a modified default (added/removed attributes...)
  • it might be hard to detect and recover from mistakes you did by changing the default
  • future upgrades to the default configuration might cause problems in your specific project

Copy the default site configuration, then extend the copy

It's considered best practice to use a full copy of the default site configuration as base for your own project. Then you should make use of the "extends" mechanism but based on your copy of the default. This helps avoiding the problems pointed out in the previous paragraph.