Magnolia Marketplace - Development guidelines

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:

  <dependencyManagement>

 <dependencies>

   <!--Dependency management section from external libs-->

   <dependency>

     <groupId>info.magnolia.boms</groupId>

     <artifactId>magnolia-external-dependencies</artifactId>

     <version>6.2</version>

     <type>pom</type>

     <scope>import</scope>

   </dependency>

 </dependencies>

</dependencyManagement>

And then for your external dependencies, you don’t need to specify a version as such:

  <dependency>

 <groupId>org.projectlombok</groupId>

 <artifactId>lombok</artifactId>

</dependency>

<dependency>

 <groupId>com.github.ben-manes.caffeine</groupId>

 <artifactId>caffeine</artifactId>

</dependency>

https://docs.magnolia-cms.com/product-docs/6.2/Developing/BOM-for-third-party-libraries.html

Module descriptors

https://documentation.magnolia-cms.com/display/DOCS62/Module+descriptor

Archetype generator

https://documentation.magnolia-cms.com/display/DOCS62/How+to+use+Magnolia+Maven+archetypes

Dependency injection

https://documentation.magnolia-cms.com/display/DOCS62/Dependency+injection+and+inversion+of+control

I18n

https://documentation.magnolia-cms.com/display/DOCS62/i18n+API

Recommend Password Manager module over YAML file for sensitive data

https://documentation.magnolia-cms.com/display/DOCS62/Password+Manager+module

Roles and ACL (Access Control Lists)

https://documentation.magnolia-cms.com/display/DOCS62/Roles+and+access+control+lists

Long-running actions/tasks

https://documentation.magnolia-cms.com/display/DOCS62/Action+definition#Actiondefinition-Asynchronousactions

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.