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. If you have discovered a great way to do something leave a comment.

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

Displaying content stored in apps

From Search

Define as a component anything that is likely to change 

Defining something as a component allows other developers quickly change the implementation. For this reason, you should define anything that is likely to be changed or customized later as a component. For example, define your apps and subapps as components. Views are also common customization points so define the views returned by subapps as components. Any components you define are available for injection. This is also true for components further up the hierarchy in parent components.

Examples:

• Defining an app or subapp as a component
• Write your own views

Development

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 option group field 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

Language

Provide a message bundle

With message bundles a translator can work with a plain text file and doesn't need to touch the code.

From Internationalization

Use UTF-8

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

From Internationalization

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 Types of translatable text

Create separate message bundles for template and UI labels

From Types of translatable text

Modules

Create your own bundle

A small purpose-built bundle is easy to understand and fast to build and deploy.

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.

From Modules

Multisite

Author domain

In a multisite setup with one Magnolia installation, you assign multiple domains to the public instance. However, it is sufficient and recommended to have only one domain pointing to your author instance. The domain of the author instance is different from the domains of the public instance.

Site definition name and handle prefix

Use different values for the site-definition-name and the name of the mapped node (handlePrefix).

Turn off domains and mappings inheritance

When extending site definitions, turn off inheritance for mapping and domains by using @extends=override.

Disable the uri-starts-with-sitename rule on the public context

Disable the uri-starts-with-sitename rule in the public context.

Add an additional voter AdminOnlyMatcher to the rule. This way you can use the same configuration on both the author and public instances.

From How to use Multisite

Resources

Use a dedicated CSS pre-processor

New Web technologies such as Syntactically Awesome Style Sheets (Sass) and Less have largely replaced the need to do FreeMarker pre-processing for CSS files. You can now accomplish the same with a dedicated CSS pre-processor. We recommend that you start using such new technologies. Magnolia provides the /resources path (without dot) as a legacy option to support older projects.

From 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

MultiExcerpt named create traits that have a clear set of allowed values was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro

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

Workflow and tasks

Don't use tasks for non-human workflows

Do not 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