Open-sourcing a light module
When you are ready to share a light module with the greater Magnolia community, follow the instructions on this page.
Use a meaningful, findable name
The name of a shared module should be the same in magnolia, on npm and
on github (or whichever public source code repository you use), and
should work well in all of these contexts. We recommend the pattern
<what-it-is>-magnolia .
For example: language-switcher-magnolia, chartjs-magnolia,
pinterest-magnolia.
Use an appropriate location
Find an appropriate location on your hard drive for shared code.
-
If you are working with an existing light module from a project, copy or move the module out of the project to make it easier to maintain.
-
If you are creating a new module, use the Magnolia CLI
mgnl create-light-modulecommand.
Symbolic links are a convenient way to have a shared light module in one location on your hard drive, but use it in many locations.
Open a terminal in your servers light-modules location and run:
ln -s <path to light module> <name of light module dir>Example:
ln -s /Users/<jdoe>/Documents/shared-projects/chartjs-magnolia chartjs-magnoliaTest your light module
To ensure that your module works for others and contains everything it
needs, we recommend you test it in a fresh Magnolia instance. To install
a new instance, use the Magnolia CLI mgnl jumpstart command.
Choose a license
Choose a license and add a license file to your light module.
We recommend the MIT license for modules that you are sharing publicly. This gives others freedom to use your module on any project.
Write a README.md
Good README files are key to the success of the Magnolia light module ecosystem. Someone looking for a module should understand yours quickly thanks to screenshots and clear descriptions in the README file.
We recommend you use this template: https://raw.githubusercontent.com/magnolia-cms/shareable-magnolia/master/README.md
Use Git
Initialize a Git repository in your light module directory. Code can be hosted in any publicly available repository, but we recommend GitHub due to its popularity and comprehensive feature set. If you create a https://github.com account, and create a repository via the website, it provides you with instructions on how to connect it to the project on your hard drive.
|
The |
Create a package.json file
Run the npm init command in your module directory. This prepares your
module for distribution on npm by creating a package.json file. Accept
the default prompts, but change the version to 0.0.1 unless you know you
are ready for the first official release of your module.
Add npm Keywords
Once the package.json file is created, add the following keywords to the package.json to make it discoverable via search and to assist automation.
| Keyword | Description |
|---|---|
|
Required |
|
Optional Use for a single component. |
|
Optional Use for a collection of templates. |
- Example
"keywords": [
"magnolia-light-module",
"magnolia-component"
],Manage dependencies
Optionally, you can add a module.yaml file as the Magnolia module
descriptor where you can specify any hard Magnolia dependencies. Specify
this if your module uses a feature which became available in a certain
version of Magnolia, such as
decorations.
Clean up
Place all the files that you want to include in your GitHub source
control project but that are not part of the actual light module, in the
_dev directory.
.npmignore
While the source control project should include everything to help a
developer use and understand your module, the published package on npm
should be just a light-module that is ready to use in production. The
.npmignore file is used by npm to exclude files from being published
to npm. It should be configured to ignore the _dev directory.
Provide demo content
A demo page with one or more instances of the component delivered in the module can be very helpful for someone evaluating your module.
Export your demo page(s) to xml bootstrap files, and place them in
_dev/demos. Describe how to access them in the Demo section of the
readme.
|
Link to Java JARs
If your module depends on .jar files that are not in the standard
Magnolia bundles, developers will need to install these files manually.
We recommend that you include a link URL to any .jar files in the Usage
section of the REAME file and explain how to install them. If you decide
that you want to include the .jar files in your project, place them in
_dev/jars.
Tips
Handling resources and JavaScript
We recommend:
-
Component templates typically should not contain script or stylesheet link tags to bring in web resource files. Developers who use your module must have control over how they want to include the web resources: using resfn, themes, static includes, require.js, and so on.
-
Component templates can include initialization JavaScript which relies on those libraries.
-
A component can be placed multiple times on the same page. It can help to have a unique id for each instance of the component. This can be created by using the id of the component node (FreeMarker expression:
${content.@id}).
Enabling customization
We recommend you provide a way for developers to customize how your module functions in their project. For example, the languageSwitcher component can be customized to render either a selection box or an unordered list by default.
You can use:
-
Template parameters - A developer can change the template parameters directly in the template definition, but this would mean they cannot use the npm package as-is. They need to edit the template definition. A cleaner practice would be to use a decoration in their own project module to modify the template definition.
-
Site parameters - This approach has the advantage that the component can be configured to behave differently on each site in a multi-site project.
Checklist
-
Directory Name Details <what it is>-magnolia
-
magnolia-light-module Details Keywords in package.json
-
Description Details In the README and the package.json
-
README Details Features, Usage, Demo
-
README screenshots
-
Small Details Your module provides one component, or a focussed set of functionality.
-
Demo
-
License file
-
Github Details Source code is available. (Or other public source control repository)
-
module.yaml
-
.npmignore Details To exclude the
_devdirectory and other things not relevant to a production light module. -
Buildable Details Buildable with
npm run build
Publish to npm
To publish your light module as a package to npm, run npm publish.
This interactive command also helps you setup a user on npm if you don’t yet have one.
View your published package at
https://www.npmjs.com/package/<light module name>!
Your package can be found using npm search after a short time.
Let the world know
You are awesome. Thanks for contributing to the Magnolia community. Let
everyone know by posting to the
Magnolia User Mailing List.
Mention @magnolia_cms in a tweet on twitter, and we’ll spread it to our followers.
If you would like even more exposure, consider writing a personal blog post about it.
You could even contact us to discuss
hosting it on the magnolia blogs.