Jumpstarting a FreeMarker-based Magnolia project

After creating a new project directory and running the Magnolia CLI jumpstart plugin, you’re prompted to choose from available templates:

? Choose a template
  1) standard-webapps (Magnolia without any content)
  2) demo-webapps (Magnolia with travel demo)
  3) headless (Magnolia with headless starter projects)

Select 2) demo-webapps and press Enter.

Selecting a starter project

Next, choose the desired starter project for your edition:

? Choose a template
  1) magnolia-community-demo-webapp
  2) magnolia-dx-core-demo-webapp

For this guide, select 1) magnolia-community-demo-webapp.

This command downloads and configures all necessary files into the current working directory.

Understanding the project structure

Your new project directory includes:

apache-tomcat/ - Tomcat with Magnolia webapp
light-modules/ - Directory for your light modules
mgnl.config.js - Configuration for Magnolia CLI and its plugins
mgnl.error.log - Log file for Magnolia CLI plugin execution

Magnolia CLI configuration

Inside mgnl.config.js, you see default plugins such as:

plugins: [
  new CreateComponentPlugin({...}),
  new CreatePagePlugin({...}),
  new CreateLightModulePlugin({...}),
  new CreateAppPlugin({...}),
  new StartPlugin({...})
]

These plugins define how the CLI behaves when you create templates, components, or light modules.

Creating pages and components with CLI

Magnolia CLI provides commands to scaffold FreeMarker-based templates and configuration.

Create a new light module

To start with a light module:

npm run mgnl -- create-light-module "my-lm"

This command creates the folder structure for your module and registers it in mgnl.config.js.

Create a new page template

To create a new page template, run:

npm run mgnl -- create-page HomePage

Add an area inside the <body> … </body> element in the /Path/to/project/light-modules/my-lm/templates/pages/HomePage.ftl template manually:

[@cms.area name="main"/]

Create a new component

To create a new component inside HomePage, run:

npm run mgnl -- create-component Banner -a HomePage

This command generates a component template and adds it to HomePage inside my-lm.

Starting Magnolia CMS

In the project root, run:

npm run mgnl -- start

After the Magnolia instance is successfully started, visit http://localhost:8080.

Login

Go to http://localhost:8080/magnoliaAuthor and sign in as a superuser :

Username: superuser
Password: superuser

Magnolia is ready to use and gives you a list of suggestions to get started.

superuser is a system administrator account that has permissions to do everything. It’s useful for testing.

Creating pages and content in Magnolia

Open the Pages app in AdminCentral.
Create a new page using the HomePage template.
Add the Banner component to the main area of the page.
Visit http://localhost:8080 to see your new content coming from Magnolia and rendered with FreeMarker.

Next Steps

You successfully jumpstarted a FreeMarker-based Magnolia project.

Here are some ideas for what to explore next:

Configure your setup - adjust mgnl.config.js to match your project’s needs.
Create your own CLI plugin - extend the CLI using generate-plugin.
Build a content app and a content type, then render the content in your FreeMarker template.

Want to try a headless project instead?

Feedback

DX Core