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
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.
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:
Fields
Use delegating field transformers
The delegating transformer 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
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
Example: Message files in the Travel Demo
module-travel-demo-backend_en.properties
(user interface labels)module-travel-demo-frontend_en.properties
(template labels)
From Types of translatable text
Modules
Create your own webapp
To create a custom Magnolia webapp, always start with a preconfigured Magnolia webapp.
Use the properties
section to define versions. The section may the serve as a central part for organizing all versions required by your project.
From Creating a custom webapp with Maven
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 Add an additional voter AdminOnlyMatcher to the rule. This way you can use the same configuration on both the author and public instances.uri-starts-with-sitename
rule in the public context.
From How to use Multisite
Resources
Use a dedicated CSS pre-processor
MultiExcerpt named Use a dedicated CSS pre-processor was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
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.
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. Roles Groups Groups UsersMagnolia LDAP editor
workflow-base
editors
editors
jsmith
eallen
cappleton
publisher
workflow-base
publishers
publishers
bleroy
dmillet
vrobbins
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. They 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