Developer guidance for how to build an external module
Light Dev integrations
-
Module structure
-
Dependencies and versioning
Java module integrations
-
Module structure
-
Dependencies and versioning
-
Configuration management (YAML vs JCR)
-
Logging
-
Security rights and roles
Module structure
Set correct BOM version
Magnolia offers so-called BOM project for each Magnolia version so that external dependencies can rely on the same versions within various modules. Inherit the BOM version for your project which you target Magnolia version and use external dependencies as much as possible from that BOM project.
For instance, an example configuration is:
1<dependencyManagement>
2
3 <dependencies>
4
5 <!--Dependency management section from external libs-->
6
7 <dependency>
8
9 <groupId>info.magnolia.boms</groupId>
10
11 <artifactId>magnolia-external-dependencies</artifactId>
12
13 <version>6.2</version>
14
15 <type>pom</type>
16
17 <scope>import</scope>
18
19 </dependency>
20
21 </dependencies>
22
23</dependencyManagement> And then for your external dependencies, you don’t need to specify a version as such:
1<dependency>
2
3 <groupId>org.projectlombok</groupId>
4
5 <artifactId>lombok</artifactId>
6
7</dependency>
8
9<dependency>
10
11 <groupId>com.github.ben-manes.caffeine</groupId>
12
13 <artifactId>caffeine</artifactId>
14
15</dependency>
BOM for third-party libraries
https://docs.magnolia-cms.com/product-docs/developing/bom-for-third-party-libraries/
Module descriptors
https://docs.magnolia-cms.com/product-docs/modules/module-descriptor/
Archetype generator
Dependency injection
https://docs.magnolia-cms.com/product-docs/modules/dependency-injection-and-inversion-of-control/
I18n
https://docs.magnolia-cms.com/product-docs/administration/language/i18n-api/
Recommend Password Manager module over YAML file for sensitive data
https://docs.magnolia-cms.com/product-docs/modules/list-of-modules/password-manager-module/
Roles and ACL (Access Control Lists)
Long-running actions/tasks
Checklist
-
CVE scan beforehand
-
Documentation
-
Definition app without any errors reported
Dependencies and versioning
Your module should support new installations as well as upgrades from previous versions of the module.
If your module depends on other Magnolia modules, you should define corresponding dependencies in the module definition.
Clean dependency management is key for stable deployment. If your module relies on Magnolia modules then use the versions specified in the Magnolia bundle for your module dependencies.
Configuration management
Use YAML configurations wherever possible as it makes migrations and module deployment more efficient and manageable as version handlers are not required.
Only use Yaml configurations for settings that are project-specific like endpoint URLs.
Logging
Logging is an important part for stable operations, good logging practices will help system administrators, support providers and developers alike.
Your log messages should appropriate log levels to provide information to system administrators, support providers and developers:
-
Administrators -- providing detailed information lets them know if their Magnolia servers are running in perfect condition and alert them if there are problems, messages should use ERROR, FATAL and WARNING log levels
-
Support providers -- provide details and evidence to help resolve customer issues, usually WARNING and INFO log levels
-
Developers -- tracing code execution without attaching a debugger to shorten error troubleshooting, usually at DEBUG or TRACE log levels
Make sure that exceptions are logged in a self explanatory way.
Security rights and roles
Security is absolutely essential for every project. If your project requires custom roles then please ship them with your module and make sure that they are just granting access for the functionality needed for your app to function properly.
Don’t apply added roles automatically to non-administrator groups.
Document your roles clearly so the admin can decide which of your app roles are applied to user groups.
Become a Magnolia partner
