Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
In this beginner tutorial you will create a simple web page based on a custom-built light module called hello-magnolia
. Your light module will provide a page template and a custom quotation
component for a web page. You will learn how to get content from content repository and display it on the page. You will develop the page using Magnolia CLI, an npm package which facilitates light development with Magnolia.
Magnolia CLI is available in several release versions. This tutorial has been checked against version 2.2.0
.
Install Java
java -version
in a terminal or command prompt. If the system reports a version number, Java is installed on your computer.$ java -version java version "10.0.1" 2018-04-17 Java(TM) SE Runtime Environment 18.3 (build 10.0.1+10)
If you don't have Java, install it:
Install Node.js
To check the version of your node installation run the following command in a shell:
node -v
Install Magnolia CLI
npm install @magnolia/cli -g
Depending on your permissions and the location where you have installed Node.js, you may have to execute the command above with root permissions. Without installation permissions you will notice messages such as npm ERR!
in the shell.
On Linux or Mac OS X to run this command as root use:
sudo npm install @magnolia/cli -g
If the installation is successful, you see the following or a similar output in the shell:
If you already installed Magnolia CLI, update to the latest version:
npm update @magnolia/cli -g
Once you have installed Magnolia CLI, test the installation by running the following command in the shell:
mgnl help
Download and install a Magnolia bundle
For development and testing you need a running instance of Magnolia and a directory for:
- The latest release of the Community Edition of Magnolia, bundled together with the Tomcat server.
- The
light-modules
folder, in which you will develop thehello-magnolia
module.
In this tutorial, we'll use the name magnolia
for the directory.
Download Magnolia
Create the magnolia
directory, cd
into it, open a shell and enter the following command:
mgnl jumpstart
You are prompted to choose a Magnolia bundle, choose 3) magnolia-community-demo-webapp
.
The command:
- Downloads the most recent version of the Magnolia bundle you selected (currently version
/magnolia
directory. ) into the - Creates a
light-modules
folder in the directory. - Changes the default value of the
magnolia.resources.dir
configuration property from${magnolia.home}/modules
to/magnolia/light-modules
for both the Author and the Public instances of Magnolia.
Once the setup operation is complete, you should see a message similar to this one:
info Magnolia has been successfully setup for light development! info You can now open a new terminal tab or window and start it up with the CLI command 'mgnl start' info Magnolia will be ready after a few seconds at localhost:8080/magnoliaAuthor. Username and password is superuser
Below is the folder structure created after running the mgnl jumpstart
command:
magnolia/ ├── apache-tomcat/ │ ├── bin/ │ ├── conf/ │ ├── lib/ │ ├── logs/ │ ├── temp/ │ └── webapps/ │ ├── magnoliaAuthor/ │ ├── magnoliaPublic/ │ └── ROOT/ ├── downloads/ └── light-modules
Install and start Magnolia
In the parent directory of light-modules
, enter:
mgnl start
The command installs and starts Magnolia. This is complete when you see a message like Server startup in 112737 ms
. You can then access the UI of the Author instance.
Log into the Author instance
Go to
http://localhost:8080/magnoliaAuthor
and log in to the Author instance with:
- Username:
superuser
- Password:
superuser
The App launcher is displayed:
Creating a simple page template
Create a module structure for the template
In this section you will create the folder structure of the hello-magnolia
module.
- Go to the
light-modules
folder: Run the following command:
mgnl create-light-module hello-magnolia
The created structure:
hello-magnolia/ ├── decorations/ ├── dialogs/ │ ├── components/ │ └── pages/ ├── i18n/ │ └── hello-magnolia-messages_en.properties ├── README.md ├── includes ├── templates/ │ ├── components/ │ └── pages/ └── webresources/
This is a typical Magnolia module structure where hello-magnolia
is the name of your module.
é
, à
, ç
, ä
, ö
, ü
or special characters such as slashes /
, \
and so on. The name must match the regular expression [a-zA-Z0-9-_]
.Magnolia continuously scans the file system folder defined by the magnolia.resources.dir
property. In this case it looks inside the light-modules
folder, and registers your module(s) automatically. It detects new and modified templates, dialogs and (web)resources.
Click WEB DEV > Resource files in the App launcher and check that the hello-magnolia
module structure has been registered:
The resource is loaded from the file system.
icon in the Origin column indicates that the givenCreate the template
In this section you create a simple page template in your hello-magnolia
module. The page template will be simple in that it will not yet allow you to add editable components to the page.
Start with a static page
Copy the following HTML code and save it as
/hello-magnolia/templates/pages/hello.html
:/hello-magnolia/templates/pages/hello.html<!DOCTYPE html> <html xml:lang="en" lang="en"> <head> <title>Starter Page</title> <link rel="stylesheet" type="text/css" href="../../webresources/css/hello-style.css" media="all" /> </head> <body> <div class="container"> <h1>hello works!</h1> </div> </body> </html>
Create a new
css
folder in/hello-magnolia/webresources/
.Copy the CSS below and save it as
/hello-magnolia/webresources/css/hello-style.css
. We reference this stylesheet in the HTML page and, later on, in a FreeMarker template script.- Check the result. You can do this in two ways:
- By requesting the HTML page via Magnolia. The page should be accessible under the following URL:
http://localhost:8080/magnoliaAuthor/.resources/hello-magnolia/templates/pages/hello.html
Note that by requesting the page in this way you are requesting a static resource file of the Author instance of Magnolia. At this stage of development there is no page called hello created using the Pages app. You may check this by trying to get
http://localhost:8080/magnoliaAuthor/hello.html
. The page will not be available. - By opening the
hello.html
file directly with your web browser.
Note that the browser tab header is "Starter Page", which is provided directly by the content of the
<title>
element in the static HTML page. - By requesting the HTML page via Magnolia. The page should be accessible under the following URL:
In the steps that follow you:
- Turn the static HTML file into a template script file containing FreeMarker directives. The directives make it possible to retrieve content of some parts of the page from the JCR repository, parts such as the content of the
<title>
element. - Create a template definition. It makes the template available to Magnolia's authoring system.
- Create a dialog definition. A dialog definition defines the editable page properties.
Create a page template script
Rename the static HTML document hello.html
to hello.ftl
. The extension .ftl
turns the file into a processed FreeMarker script.
Edit the script so that the final result appears as follows (the list of changes is provided below):
<!DOCTYPE html> <html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}"> <head> [@cms.page /] <title>${content.windowTitle!content.title!}</title> <link rel="stylesheet" type="text/css" href="${ctx.contextPath}/.resources/hello-magnolia/webresources/css/hello-style.css" media="all" /> </head> <body> <div class="container"> <h1>${content.windowTitle!content.title!} works!</h1> </div> </body> </html>
The changes:
- Line 2: Replaced
en
with the${cmsfn.language()}
function to set the value of thelang
attributes. This will make sure that the primary language of the page will be rendered correctly if you decide to localize your web page(s) into more languages. - Line 4: Inserted
[@cms.page /]
as a new line. This directive adds toolbars and makes the page properties dialog available. You will create the definition for this dialog immediately after creating a page template definition. - Line 5: Replaced the static words "Starter page" with the
${content.windowTitle!content.title!}
directive. The content of the<title>
element will then be retrieved from the JCR repository. - Line 6: Changed the CSS reference to use
${ctx.contextPath}
. When the page is created during the rendering process, we need to know the absolute path to the resource. This directive ensures that the path to the resource is full and correct on both the author and the public instances. - Line 11: Replaced the word "hello" in the
<h1/>
element with the${content.windowTitle!content.title!}
directive to render the first part of the page title dynamically using the content of page properties.
Create a page template definition
A template definition gives the template a name and makes it available to the system. It also tells the system which script renders the content. We use YAML to create template definitions.
Copy the template definition code below.
/hello-magnolia/templates/pages/hello.yamltitle: hello templateScript: /hello-magnolia/templates/pages/hello.ftl renderType: freemarker dialog: hello-magnolia:pages/hello visible: true
Save it to a new file
/hello-magnolia/templates/pages/hello.yaml
.
Create a dialog definition for page properties
Copy the following code to a file named hello.yaml
in /hello-magnolia/dialogs/pages/
:
A dialog defined like this allows you to add and edit the values of page properties such as windowTitle
and title
. The content of these properties are stored in the Magnolia JCR repository.
Use the template to create a page
Now you can use the page template to create a page in the Author instance. You can then publish the page to the Public instance.
- Go to Magnolia and open the Pages app:
- Create a new page called
hello
. Start this by clicking Add page from the Action bar on the right hand side: - In the Add page dialog that appears choose the
hello
template as the page template and click Next: - In the Page properties dialog, enter
Hello Magnolia
into the fields Title and Window title. - Click Save changes.
- Click Preview page on the right to preview your page.
- Click Publish. You can then access the page on the Public instance of your Magnolia installation via the URL
http://localhost:8080/magnoliaPublic/hello.html
.
Congratulations! You've created your first Magnolia page built on a page template.
Now let's enhance the content of the page by adding an editable custom-built quotation
component to the area just below the "Hello Magnolia works!" heading.
Creating areas and components
Areas and components help modularize a project and structure pages. Once defined, you can reuse areas and components in many page templates.
Let's create an area with one component to add quotations. At the end the whole page should look like this:
What is an area
Typically you organize pages into smaller elements called areas. Areas allow you to control the page layout and restrict what content editors can place inside the area. Areas are rendered as div
elements in the HTML so you can style them with CSS. Areas also provide repeatability. An area template typically loops through the components inside it, rendering them one by one.
What is a component
A component is the smallest block of content that editors can edit, delete and move as a single unit. Think of a component as content that "belongs together". When you look at a typical Magnolia page, you can identify components easily with that rule of thumb. At its simplest, a component is just a heading and some text that go together.
Define an area
Areas are defined in the page template definition. You do not need to create a separate area definition file.
Edit the /hello-magnolia/templates/pages/hello.yaml
template definition and define the main
area by appending the following code to it:
areas: main: renderType: freemarker
Save the file. In the next step you specify the location of the main
area within the page.
Specify the location of the area and include it in the page
You must place the main
area just below the page heading. To do so, edit the /hello-magnolia/templates/pages/hello.ftl
template script and add a <div/>
element with the area just below the <h1/>
element:
<!DOCTYPE html> <html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}"> <head> [@cms.page /] <title>${content.windowTitle!content.title!}</title> <link rel="stylesheet" type="text/css" href="${ctx.contextPath}/.resources/hello-magnolia/webresources/css/hello-style.css" media="all" /> </head> <body> <div class="container "> <h1>${content.windowTitle!content.title!} works!</h1> <div class="main"> [@cms.area name="main"/] </div> </div> </body> </html>
The FreeMarker expression [@cms.area name="main"/]
includes the area. The <div class="main">
element wraps the expression for styling purposes.
Make sure that the FreeMarker expression [@cms.area name="main"/]
is not included again at the end of the hello.ftl
template script.
Create the quotation component
Make sure you are at the root of your module (/magnolia/light-modules/hello-magnolia
). Use the following CLI command to create the quotation
component and make it available in the main
area of the page template:
mgnl create-component quotation -a pages/hello@main
The command creates the following files:
/hello-magnolia/dialogs/components/quotation.yaml
This definition configures the elements of the dialog./hello-magnolia/templates/components/quotation.yaml
This definition gives the component a name and makes the component available to the system./hello-magnolia/templates/components/quotation.ftl
The template script renders the content of the component.
The command also modifies the /hello-magnolia/templates/pages/hello.yaml
file, in which it adds the availability of the quotation
component in the main
area by appending the following piece of code to it:
availableComponents: quotation: id: hello-magnolia:components/quotation
Configure the dialog fields
The CLI command mgnl create-component
creates a dialog definition with field types which you do not need. Open the dialog definition file /hello-magnolia/dialogs/components/quotation.yaml
for editing, and edit it to appear as follows:
form: label: quotation tabs: - name: tabMain label: Main fields: - name: citedPerson fieldType: text label: Cited Person - name: quotation fieldType: richText label: Quotation actions: commit: class: info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition cancel: class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition
Be careful with the type of whitespace in this code. All the whitespace to the left of the text should be formed using the SPACE character, not the TAB character. For more details on this topic, see the 6.1. Indentation Spaces section in YAML v1.2 specification.
The key content elements in the above dialogue definition – citedPerson
and quotation
– are stored in the JCR repository and rendered in the page by the following code, the component's script.
Configure the component's template script
The FreeMarker script /hello-magnolia/templates/components/quotation.ftl
created by the mgnl create-component
command contains commands with little or no use in the context of this tutorial. Open the file for editing and save it only with the following code:
[#if content.quotation?has_content] <blockquote> ${cmsfn.decode(content).quotation} [#if content.citedPerson?has_content]<cite>${content.citedPerson}</cite>[/#if] </blockquote> [/#if]
The final structure of your hello-magnolia
module in the light-modules
folder should look like this:
hello-magnolia/ ├── decorations/ ├── dialogs/ │ ├── components/ │ │ └── quotation.yaml │ └── pages/ │ └── hello.yaml ├── i18n/ │ └── hello-magnolia-messages_en.properties ├── README.md ├── includes ├── templates/ │ ├── components/ │ │ ├── quotation.ftl │ │ └── quotation.yaml │ └── pages/ │ ├── hello.ftl │ └── hello.yaml └── webresources/ └── css/ └── hello-style.css
Add the component to a page
Now you can add a quotation component to the hello
page with the text and the author of a quotation.
Open the hello
page in the Pages app and click the New main component green bar. Enter your favorite quotation in the dialog:
After saving your quotation, go back to AdminCentral and click Tools > JCR to check that the content of the text fields in the quotation dialog has been stored in the JCR repository for the main
area of the hello page:
After you publish the page, access the final result on the Public instance and see the content of the quotation component in the page:
Congratulations.
You now know the basics of Magnolia templating. Using these techniques you can build websites where non-technical authors can manage content using dialogs.
2 Comments
John Wang
This is a nice tutorial, but I would like to have more control and java libraries at disposal for more complicated scenarios.
So can anyone please share a link to how to do java development on magnolia step-by-step? like on a certain IDE (intellij, eclipse...), how to setup a working magnolia work-space, code, build, deploy?
Christoph Meier
Hi John
Thanks for your feedback. I am glad you liked the "Hello Magnolia" tutorial.
The official Magnolia documentation (documentation.magnolia-cms.com) doesn't provide anymore tutorials specifically for "Working with the IDE xyz to develop Magnolia .." (or something similar).
But Magnolia documentation has some other tutorials which deal with topics to be developped with Java.
Here's an overview for the current available tutorials:
https://documentation.magnolia-cms.com/display/DOCS57/Tutorials
Note that there are als two other Confluence spaces - which are not part of the "official Magnolia documentation" - but which provide useful resources too (but which may be outdated in some cases).
See:
- https://wiki.magnolia-cms.com/display/WIKI
- https://wiki.magnolia-cms.com/display/DEV
Maybe (hopefully) interesting for you there:
=> https://wiki.magnolia-cms.com/display/DEV/Working+with+Eclipse+and+Git
Cheers,
Christoph