Magnolia basics for front-end developers
This page provides a high level overview of the key concepts you need to understand when creating file-based light modules and working with templates and resources in Magnolia.
Understanding modules in Magnolia
Magnolia has a modular architecture in which modules act as containers for your templates and resource files.
Light modules
Magnolia introduced the concept of light modules as part of the light development approach to enable front-end developers to create Magnolia projects.
A light module is a directory on the file system that contains YAML definition files, optional FreeMarker template scripts, and other resource files of any type. The file system approach allows you to start quickly with Magnolia using familiar tools, text authors, IDEs, and build processes.
| In headless projects, you typically don’t need template scripts, as rendering is handled by your front end framework like React, Angular, or Vue. |
Magnolia picks up any changes to the files right away without a restart.
What about Java?
You don’t need Java development skills, an SDK or Java IDE to create a functioning Magnolia light module. The light module approach complements traditional Java development: a project can be built with Maven modules, light modules or both. Additionally, because the structure of light modules aligns seamlessly with Maven modules, a light module can be transformed into a Maven module by copying its contents into the Maven module.
Module structure
What makes a Magnolia module are files specific to Magnolia in a particular folder structure as shown here:
<module-name>
├── apps/
├── dialogs/
│ └── myDialog.yaml
├── i18n/
├── resources/
└── templates/
├── components/
└── pages/
└── my-template/
├── myTemplate.yaml
└── myTemplate.ftl (used in FreeMarker projects)
├── themes/You can use Magnolia CLI to create all the folders and files in the right location.
Advanced topics:
Templating in Magnolia
Templates are blueprints for creating pages, areas and components. For example, when you create a page in the Pages app, you must select a template for the page to be based on. The content that authors provide using dialogs is merged into the template.
A template consists of:
-
A template definition - to give the template a name and make it available to the system.
In FreeMarker-based projects, the template definition specifies at least a script and a renderer. Magnolia includes a FreeMarker renderer that is used by default if no other is specified.
-
A template script - required in FreeMarker, to define the output, typically HTML.
-
Optionally, a dialog definition - to define a dialog for content entry.
-
Optionally, a model - the model can be a JavaBean implementing complex logic or a JavaScript model.
In Magnolia light development, you configure definitions in YAML files and scripts in a templating language such as FreeMarker.
Templating structure
Templating is organized with pages, areas, and components.
A page template outputs an entire web page. A page template typically includes some markup for the header and footer and contains one or more areas. An area is a region of a template where authors can add components. A component can provide any type of content, and is the smallest unit that authors can manage.
As a developer, you provide the page and component templates, and specify which components are available in which areas.
Templating definitions
Magnolia uses different types of template definitions to control how content is structured, displayed, and edited on a page.
Page templates
A page template definition describes the appearance of an entire page. When an author creates a page in Magnolia, they select one of the page templates you have defined.
The page template definition contains an areas section which lists the areas on the page. An area in Magnolia is a defined section of a page where authors can add and arrange components.
For each area, you specify the components that will be available in a simple list.
More information:
Component templates
A component is the smallest block of content that authors can edit, delete, copy, and move as a single unit on the page. At its simplest, a component may just be text. However, a component can contain anything: a related image, a teaser to another page, or a social media feed from a third party web service.
A component can also specify areas - enabling an author to add a component within a component.
Components render content entered by authors in dialogs.
More information: Component definitions
Template scripts (used in FreeMarker projects)
A template script defines the output (typically HTML) and is interpreted by info.magnolia.rendering.renderer.Renderer. The script is written in a templating language such as FreeMarker.
A template script is a mixture of:
-
Static markup (HTML).
-
Dynamically assigned values provided by Templating functions and other convenience helpers.
-
Content references.
More information: Template scripts
Dialogs
Dialogs enable authors to enter content. Authors type content into fields and the dialog saves the content entered in the repository.
The functionality of each input field in a dialog is provided by a field definition class that allows the author to perform a task such as enter text, upload an image, select a date, and so on. Template definitions reference dialog definitions - this is how Magnolia knows which dialog to associate with the template.
Pages, areas, and component templates can all use dialogs. All the dialogs used in Magnolia are configured in the same way. For example, the configuration of dialogs used in apps and components is the same.
More information: Dialog definitions
Resources
In Magnolia, the term resource is used for all the files in a light module, such as:
-
Web resources - Such as JS, CSS, and images.
-
Definition files - YAML-based template definitions and dialogs.
-
Template scripts - Such as FreeMarker.
In light development, modules use the file system to provide resources to Magnolia. You can edit files directly from the file system with any tool.
| The file system is one of three locations Magnolia scans for resources. You can read more about resource origins and loading order in Resources. |
Referencing web resources
Use the /.resources path to reference Web resources such as CSS and JavaScript files.
For example, to reference the CSS file <magnolia.resources.dir>/my-module/css/style.css in a FreeMarker script, you use:
<link rel="stylesheet" href="${ctx.contextPath}/.resources/my-module/css/style.css">More information: