Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
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.
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
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
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.
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.
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
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
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
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
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
From Forum module
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 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
Magnolia requires everyone to use UTF-8 character encoding in .properties
files.
From Internationalization basics
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 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
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.
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
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
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
/mgnl-files/docroot
add a subfolder named after your moduleWhen 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
/mgnl-resources
add a subfolder named after your moduleWhen 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
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 actually need them. This ensures that the app launcher stays uncluttered and users find apps quickly.
From App permissions
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.
Magnolia | LDAP | ||
Roles | Groups | Groups | Users |
---|---|---|---|
|
|
|
|
|
|
|
|
From Group resolving
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 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
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
From Extending the stkArticle template
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
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
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
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 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