Best practices

A best practice is a way of working that consistently yields better results. Best practices save time and effort and result in more maintainable projects. Here are best practices collected from Magnolia documentation. If you have discovered a better way to do something, leave a comment below.

Administration

Disk space

We recommend that you allocate at least 50 GB of disk space for an author instance and 25 GB for a public instance.

From Disk space

Apps

Changing the location in the app UI

When you initiate changes in the user interface, you should always do it via a location change. If you don’t do so, the bookmark the user creates will not be accurate and the user will not be able to get back to where they were. You should consider locations early in your app design.

From Location, location, location

Add a Container instance in your ContentConnector

Make the Container instance available in your ContentConnector. This makes it easier to implement item and itemId related methods. This works only if you have only one Container per subapp. If you need more Containers you must decouple the Container and the ContentConnector.

From Content app framework

Configuration

Create a specific site definition

Always create a specific site definition and map it to your website. Don't rely on the default site definition alone. The default is a fallback site definition. It is not mapped to any particular site in the website workspace and it does not have a domain. You should at least specify URI-to-repository mappings and domain names in your specific site definition. However, you can extend the default to save effort.

Give site definition, domain node and root page the same name

To avoid request matching conflicts give the site definition node, /domains/<node> node and the root page the same name. For example, name all three nodes companyA.

From Multisite

Development

Use a webapp in a bundle

Each Magnolia webapp belongs to a bundle. You should always use a webapp within a bundle to ensure that Maven dependencies work. Use one of Magnolia's bundles or create your own. CE bundles are free while EE bundles require a license.

From Webapp

Check data before updating it

A good-citizen task should be safe and reliable. Think what the expected state of the system should be. Check existing data before updating it. Use CheckAndModifyPropertyValueTask ,   CheckAndModifyPartOfPropertyValueTask  or similar tasks or wrap your tasks into a  ConditionalDelegateTask .

A good-citizen task names and describes itself properly so users know what is going to happen in the installation process. When all tasks follow this convention they appear uniform when displayed to the user. When instantiating a Task, use a constructor which allows to provide name and description.

Name of the task should be a simple sentence providing some context such as "Set new rootFolder property."  

Description should be a complete and meaningful sentence in third person, ending in a period, such as "Set a new rootFolder property."

From Configuring a custom bundle

Fields

Use delegating field transformers

The delegating transformers classes should be your first choice since they are the most versatile. If you can, use DelegatingCompositeFieldTransformer or DelegatingMultiValueFieldTransformer rather than the other available classes.

From Transforming field values

Forms

Checking for null values

Define default values for fields or check for null values. This ensures that you can submit the form. For example, if you define an optional radio button field and don't provide a default value, an error occurs when a user submits the form by mail. The email processor does not check for null value in the template. It is good practice to check for null values of any variables you call.

You can check for null values and provide a default value in a Freemarker script like this:

field: ${field!"value not provided"}

From Field validators

Forums

Creating forums and forum pages

1. Author instance:
   
   1. Set up simple dummy forums on the author instance to test your pages and components.
   2. Make any desired changes to templates, themes etc.
   3. Create your pages and add forum components.
   4. Test your pages.
   5. Publish pages and templating changes to public instance.
2. Public instance:
   1. Set up your forums and initial threads and messages in the Forum app. Forum-specific roles will be created automatically in the Security app.
   2. Set anonymous, moderation and administration permissions. You can use the default roles and/or automatically created user roles.
   3. Exclude the forum pages from caching while you test your permissions. You can also flush the cache in the Cache tools app.
   4. Test your pages.

From Forum module

Language

Provide a message bundle

Provide a message bundle in your module. It makes translation easier. A translator can work with a plain text file and doesn't need to touch code.

From Internationalization basics

Inject SimpleTranslator in the constructor to access resources bundles

Inject  SimpleTranslator with IoC in the constructor of your Java class and use it to get access to resource bundles.

From Examples of new and old i18n API usage

Use UTF-8

Magnolia requires everyone to use UTF-8 character encoding in .properties files.

From Internationalization basics

Avoid hard-coded strings

Avoid hard-coded strings exposed to visitors, editors or administrators. Always allow localization of texts displayed on the website and in Magnolia Shell.

From Translatable text

Create separate message bundles for template and UI labels

Create separate message bundles for user interface labels and template labels. Don't store these two groups of text in the same properties files or message bundles. They are aimed at different audiences and have different localization requirements.

From Translatable text

Modules

Create your own bundle

The CE and EE bundles are not the best basis for your own bundle. Many developers start a Magnolia project using the CE bundle as a basis but often it contains more modules than you actually need. A small, targeted bundle makes building and deploying faster. When you don't need a module, leave it out. Streamline your Magnolia project to meet the specific demands of the project. You should build your own bundle based on magnolia-empty-webapp which brings the Magnolia webapp and some basic modules.

From Creating a custom bundle

Create separate modules for templates, content and resources

When you are creating a website project, you should have one module for templates, another module for content, a third for a theme and so on. While the project handles dependency management for all modules defined in the project, each module contains the files and logic for the functionality of that specific module.

From Modules

Resources

Keep resources in your project module

The best practice is to load resources by the standard Magnolia mechanism which loads from the file system or classpath resources. This way you can store the resources in a version control system and they become part of a controlled software development lifecycle automatically. You can edit them in an IDE or your favorite editor.

From Loading and editing template scripts

Install resources with an install task

A reliable deployable module should install its resources to the resources workspace using an installation task. Execute resource installation tasks during installation as well as during update in the ModuleVersionHandler of your module.

From Accessing resources

When using /mgnl-files/docroot add a subfolder named after your module

When you use the /mgnl-resources folder, create a subfolder and name it after your module. This makes it clear which module a resource is served from. It ensures that you don't override files in the docroot folders of other modules.

From Accessing resources

When using /mgnl-resources add a subfolder named after your module

When you use the /mgnl-resources folder, create a subfolder and name it after your module. This makes it clear which module a resource is served from. It ensures that you don't override files in the docroot folders of other modules.

From Accessing resources

Security

Create an app group for your own apps

Create a new app group for your own apps, especially if you have multiple apps. This approach is better than placing your apps in the native Magnolia groups. A dedicated group gives your organization's apps an identity and makes them instantly recognizable. Remember to choose a safe app group color.

From App permissions

Provision apps only to users who need them

Provision apps only to users who actually need them. This ensures that the app launcher stays uncluttered and users find apps quickly.

From App permissions

LDAP groups

When you store groups in LDAP, create one matching group per role in Magnolia. Assign roles to the group in Magnolia in order to grant users the permissions they need. This minimizes the number of groups you need to create in Magnolia.

From Group resolving

Personalization

Create traits that have a clear set of allowed values

Every trait has inherent allowed values. For example, locations are countries, ages are numbers, and genders are either male or female. Create traits that have a clear set of allowed values. Traits that have vague values are difficult to detect and assign. Also, make sure the trait applies to the majority of your audience. "New vs. returning visitor" is a good trait because the values are easy to detect and it applies to every visitor.

From  Personalization  

Create a segment only when you know your audience well

Create a segment only when you know your audience well and have targeted at least one successful campaign to them using local rules. Visitors who share a combination of traits are good candidates for segmentation if they respond well to personalization. For example, add visitors who previously bought a product to a "Previous buyers" segment and offer them a discount as a reward for return business. Segmentation helps you repeat successful personalization experiments. Start with local rules, move to segmentation later.

From  Personalization

Templating

Keep template scripts in your project module

Keep template scripts in your project module. This way you can store the scripts in a version control system and they become part of a controlled software development lifecycle automatically. You can edit them in an IDE or your favorite editor.

From Loading and editing template scripts

Extending a template

• Create custom templates in your own module. This keeps the STK clean and ensures that your customizations are not lost when the STK is updated.
• Use STK templates as a starting point. The templates have been extensively tested on all browsers, operating systems and devices.
• Extend, don't copy. This saves effort and makes updates easier.

From Extending the stkArticle template

Put common things in the template prototype

Put commonly used things in the template prototype. For example, if most pages on your site have the same areas then define those areas in the prototype. Similarly, if most pages have the same navigation menu then define the menu in the prototype. This makes configuration efficient. You only need to define exceptions to the rule in concrete template definitions. Exceptions make page templates unique for particular purposes.

From Template prototype

Put template logic into a model class

Instead of writing complex Freemarker and JSP scripts, put the logic of a template into a Java model class. Java gives you more programmatic power and the code is easier to debug and refactor.

From Reusing area content

Define CSS and JavaScript in a theme

Configure CSS and JavaScript in the template prototype only if you need them on every page and don't plan to change them often. This is rare. Most JavaScript frameworks and function scripts are better placed in your theme. It makes switching themes easier.

For example, you probably don't want to reference a tracking cookie script in the prototype. Magnolia would serve the same tracking ID for all sites, whereas typically want to track each site separately. (Magnolia's Google Analytics module plugs itself into the theme aggregator scripts rather than the prototype, so you don't need to worry about GA.)

From CSS and JavaScript in template prototype

Workflow and tasks

Don't use tasks for non-human workflows

Don't use tasks if you don't have any human activity in your workflow. Tasks and Pulse notifications are great for humans but unnecessary for operations that only involve the system itself.

From Tasks

Configure your content staging instance as a public instance

Configure your content staging instance as a public instance so that users cannot edit pages on it. The Pages app does not display the green edit bars on public instances. You typically don't want reviewers to change content on the staging instance. While reviewers may need permission to log into the AdminCentral to review functionality such as new apps, they should not edit pages. The staging instance is intended for testing and approving only. If something is not correct, fix it on the author instance and publish again to staging for another test.

From Content staging