Light development in Magnolia
Light development is a modern front-end development approach that simplifies and speeds up development in Magnolia. A key feature is that configuration of common definitions, like dialogs and templates, moves out of JCR and onto the file system as YAML text files. As a developer you have all your code and configuration in the same place in files. This makes templates easier to understand, share, merge and manage in source control. Template scripts and configuration now live side-by-side in the same place.
Thanks to the resource loading mechanism, Magnolia picks up any changes to the files right away without a restart, whether they reside on the Java classpath or file system. These simplifications accelerate project development in both Java Maven modules and the light modules.
An additional benefit of the file system approach is that project teams or third party developers can easily create tools to generate Magnolia configuration.
Light modules
Magnolia introduced light modules as part of the light development approach.
The Magnolia CLI speeds up creating and developing light modules. The tool includes commands to install and start Magnolia, and to create modules, pages and components.
Develop Magnolia projects without Java skills
Now front-end developers can create Magnolia projects with light modules without the need for Java development skills, or even an SDK or Java IDE.
A light module is simply a directory on the file system that contains YAML definition files, FreeMarker template scripts, and other resource files of any type. The file system approach is more familiar to most front-end developers, and this allows them to get up to speed fast in Magnolia. They can use all of their familiar tools, text editors, IDEs and build processes.
While light modules open Magnolia to front-end developers, Java is still the key to the deep integration and customization capabilities of Magnolia.
Light modules and Maven modules
The light module approach aligns with traditional Java development: A project can be built with both Maven and light modules. Additionally, because the structure of light modules dovetails perfectly with Maven modules, a light module can easily be transformed into a Maven module by copying its contents into the Maven module. As a project architect, now you have the flexibility to build your project with the technologies that make the most sense for your project and team.
Light development capabilities
What can you do with light development now?
All of the following light development features are available in both Maven modules and light modules.
The following tasks are currently possible in light development:
-
App definitions: Define content apps in YAML and store them on the file system. See My first content app.
-
Bootstrapping: Bootstrap content into the JCR using the Content Importer module.
-
Configuration: Modify the module
config
nodes. In this way you can, for example, supply and modify site definitions. -
Content Type definitions: Define content types (data source and model) to quickly create apps.
-
Declarative REST: Declare REST clients.
-
Decorations: Reuse and modify existing configuration through decoration.
-
Dialog definitions: Write dialog definitions (templates and apps) in YAML and store them on the file system. See Dialog definition.
-
Include YAML files: Reuse a YAML definition in another definition using the include mechanism.
-
Internationalization (i18n): Store i18n properties files on the file system.
-
JavaScript Model definitions: See How to work with JavaScript models for more details.
-
Module dependencies: Manage module dependencies in a YAML-based module descriptor.
-
Modules: Create a module on the file system.
-
Resource files: Store resource files on the file system. See resource origins and loading order.
-
REST endpoint definitions: Configure multiple endpoints for the Delivery endpoint or your custom REST endpoint.
-
Site template prototype definitions: Write template prototype definitions in YAML. See Template prototype.
-
Template definitions: Write page, area and components definitions in YAML. See Template definition.
-
Template scripts: Write template scripts in FreeMarker and store them on the file system. See Template scripts.
-
Templating functions: Use templating functions in your scripts. See Templating functions.
-
Theme: Configure a theme on the file system in YAML.
-
Virtual URI mappings: Create short, convenient URLs that do not match the site hierarchy exactly. See Virtual URI mappings.
-
Webhooks: Declare webhooks. See How to create a webhook.
What is next for light development?
We are working on expanding light development functionality.
See light development items on the Magnolia Roadmap. |
Resource storage and loading in light development
Resources include:
-
static resources (CSS, JavaScript)
-
YAML definition files for
-
template scripts (FreeMarker).
Magnolia’s resource loading cascade includes hot-reload from the file system. See Light modules and Resources for more.
The following example works equally well as a light module, or in the src/main/resources
directory of a Maven module.
<module-name>
├── apps
├── dialogs
│ └── myDialog.yaml
├── webresources
└── templates
├── components
└── pages
└── my-template
├── myTemplate.yaml
└── myTemplate.ftl
Configuration of system parameters for light development
You can set the following properties in your magnolia.properties
file when developing light modules.
What is magnolia.develop
magnolia.develop
is a configuration property that can be set to true
in the
magnolia.properties
file for development purposes, specifically to:
-
Enable info.magnolia.classpathwatch.ClasspathScanner, when developing via IDE and changing/deploying edited classpath-based resources.
-
Disable the cache for resources.
What is magnolia.resources.dir
?
magnolia.resources.dir
is a property defining the directory from which
resources are loaded in a Magnolia instance.
This directory is used for file-based resources such as light modules
and for overriding classpath resources. The property is configured in
WEB-INF/config/default/magnolia.properties
and its default value is
$magnolia.home/modules
. To see the current value of the property, go
to the Config Info tab in the
About Magnolia app.
You can use symbolic links (symlinks or soft links) in the resources directory to include light modules located elsewhere on your system. |
Set the magnolia.resources.filesystem.observation.excludedDirectories
property to exclude directories from being observed for changes. (See the table in the Configuration management: Defining properties section.)
What is magnolia.content.bootstrap.dir
magnolia.content.bootstrap.dir
is a property defining the directory
from which
bootstrap XML
files are loaded in a Magnolia instance. This directory is only used for
file-based bootstrap. The directory can reside anywhere on the file
system. The property is configured in
WEB-INF/config/default/magnolia.properties
.To see the current value of
the property, see the list of properties in the About Magnolia app
Config Info tab.
What is magnolia.resources.watcher.sensitivity
magnolia.resources.watcher.sensitivity
is a property that defines the
sensitivity (speed) with which the changes of the
resources in magnolia.resources.dir
are
observed by info.magnolia.dirwatch.DirectoryWatcherService. The
property can be set in the
magnolia.properties
configuration file to one of the following values: low
, medium
,
high
. If not set explicitly in the configuration file, the
DirectoryWatcherService works by default under the high
value. This is
ideal for development purposes on OSX. It is recommended that you leave
the property set to high
.
What is magnolia.yaml.maxAliasesForCollections
Since version 1.26
of the SnakeYAML processor for JVM, there is a maximum of 50 aliases for getMaxAliasesForCollections
to prevent a Billion Laughs Attack.
The magnolia.yaml.maxAliasesForCollections
property, introduced with Magnolia 6.2.17, allows you to adjust the limit if the default value is too low and breaks parsing of aliases in YAML files.
The property is configured in
WEB-INF/config/default/magnolia.properties
. To see the current value of
the property, see the list of properties in the About Magnolia app
Config Info tab.
Check out our partner’s Magnolia YAML assistant IntelliJ plugin to increase your efficiency in Magnolia light development.
— Ray Sono AG
|