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. 

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.

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?

The following tasks are currently possible in light development:

• Modules: Create a module on the file system. See Creating a light module. 
• Template definitions: Write page, area and components definitions in YAML. See Template definition.
• Site template prototype definitions: Write template prototype definitions in YAML. See Template prototype.
• Template scripts: Write template scripts in FreeMarker and store them on the file system. See Template scripts. 
• Dialog definitions: Write dialog definitions (templates and apps) in YAML and store them on the file system. See Dialog definition.
• Resource files: Store resource files on the file system. See resource origins and loading order.
• App definitions: Define content apps in YAML and store them on the file system. See Creating a custom content app.
• Include YAML files: Reuse a YAML definition in another definition using the include mechanism. 
• Templating functions: Use templating functions instead of template models to define business logic in your scripts. See Templating functions.
• i18n: Store i18n properties files on the file system.
• Module dependencies: Manage module dependencies in a YAML-based module descriptor.
• Decorations: Reuse and modify existing configuration through decoration. 
• Bootstrapping: Bootstrap content into the JCR using the Content Importer module.
• Theme: Configure a theme on the file system in YAML.
• Templating functions: Use templating functions in your scripts. See Templating functions.
• Use JavaScript Models. See JavaScript Models module, How to work with JavaScript models.
• Virtual URI mappings: Create short, convenient URLs that do not match the site hierarchy exactly. See Virtual URI mappings.
• REST endpoint definitions: Configure multiple endpoints for the Delivery endpoint or your custom REST endpoint.

What is next for light development?

We are working on expanding light development functionality. 

See light development items on the Magnoila Roadmap.

What is not supported in light modules?

• Site definition
• Module descriptor
  • Register workspace
  • Register nodetype
  • Module class
  • Module version handler
• Module configuration that resides under the config folder in JCR.
• Workflows

Resource storage and loading in light development

Resources include static resources (CSS, JavaScript), definition files for apps , dialogs and templates  (YAML), and  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. 

Example: Light module structure.

<module-name>
├── apps
├── dialogs
│   └── myDialog.yaml
├── webresources
└── templates
    ├── components
    └── pages
        └── my-template
            ├── myTemplate.yaml
            └── myTemplate.ftl

Definitions in light development

Definitions in light development are coded via text files in YAML format. You can configure templates , dialogs , apps  and themes in YAML. 

Example: Simple page template definition.

renderType: freemarker
templateScript: /my-module/templates/pages/home.ftl
dialog: my-module:pages/homePageProperties

Configuration of system parameters for light development

Set these properties in your magnolia.properties file when developing light modules:

• magnolia.develop is a configuration property that can be set to true in the magnolia.properties file for development purposes, specifically to:

  • Enable ClasspathScanner, when developing via IDE and changing / deploying edited classpath based resources.
  • Disable the cache for resources.
• 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 has the default value $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 (a.k.a symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.
• 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.
• magnolia.resources.watcher.sensitivity is a property that defines the sensitivity (speed) with which the changes of the resources in the magnolia.resources.dir are observed by the 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.