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.
Welcome to the Hello Magnolia tutorial for front-end developers!
In this tutorial, you will download a fully functional light module to your file system and view the result in Magnolia. You will then make some changes in the files and see the impact your changes have.
Download the light module
Download this zip:
Extract it to
/Users/<username>/dev/light-modules/
if you followed the example in Install Magnolia, or to the location where you decided to put your light-modules
folder. Remove the version number from the extracted folder name. It should be just
hello-magnolia
.
Module structure
Your file system should now look like this:
hello-magnolia/ ├── dialogs/ │ ├── components/ │ │ └── quotation.yaml │ └── pages/ │ └── hello.yaml ├── webresources/ │ └── css/ │ └── style.css └── templates/ ├── components/ │ ├── quotation.ftl │ └── quotation.yaml └── pages/ ├── hello.ftl └── hello.yaml
Log into Magnolia
If you haven't already done so, make sure that Magnolia is started and log in.
http://localhost:8080/magnoliaAuthor
and sign in as:- Username:
superuser
- Password:
superuser
The app launcher is displayed and Magnolia is ready to use.
View the module files in the Resource Files app
Open the Web Dev > Resource Files app and see the resource files that make up the hello-magnolia light module:
Note the file icon in the Origin column indicating that these resources are file-based. You can double click on any resource to view it directly in Magnolia.
Key templating files
Every Magnolia template needs a definition and a script. A template definition gives the template a name and makes it available to the system. Here we use YAML to create template definitions. The template definition also tells the system which script renders the content.
The template script contains the rendering instructions. A script can be completely static but it usually includes editable content fragments or other dynamically assigned values provided by templating functions (for instance cmsfn to fetch content) or Rendering context objects. Here we use FreeMarker to create template scripts.
Dialogs enable editors to enter content to be displayed by a template. A template definition can reference a dialog definition (also YAML-based) that specifies the input fields to displayed to editors.
Use the template in a page
You can use the templates provided by the hello-magnolia
light module right away:
- Open the Pages app.
- Create a new page.
- Enter
Hello Magnolia
as the Page name. - Select the
Hello template
introduced by your light module and click Next. - Enter
Hello Magnolia
as the Title andThis page was created using the hello template
as the Introduction text and click Save. - Open the page for editing.
Add a component to the page
The Hello Magnolia light module contains a component called quotation.
Add this component to the page you created:
- Click on the New main component bar in your Hello Magnolia page.
- In the Quotation dialog box, enter your favorite quote and the author.
Tweak your light module
Now that you have seen the hello-magnolia
light module working in Magnolia, make some changes. You will see Magnolia automatically detects any changes you make in your file system.
Add a new field to the component dialog
Currently, the component dialog definition provides two fields: quotation
and citedPerson
.
form: tabs: - name: tabTexts label: Quotation fields: - name: quotation class: info.magnolia.ui.form.field.definition.RichTextFieldDefinition label: Quotation - name: citedPerson class: info.magnolia.ui.form.field.definition.TextFieldDefinition label: Cited person actions: commit: class: info.magnolia.ui.admincentral.dialog.action.SaveDialogActionDefinition cancel: class: info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition
Add a third field called quoteSource
.
- name: quoteSource class: info.magnolia.ui.form.field.definition.TextFieldDefinition label: Quotation source
Reference a field by its name
Instead of defining the type of a field using the class
property, you can reference the type using the fieldType
property, which takes the field's short and easy-to-remember alias name as the value.
For example, use fieldType: text
instead of class: info.magnolia.ui.form.field.definition.TextFieldDefinition
.
To view the field alias names, look in the Definitions app. See also Referencing fields.
Edit your component on your Hello Magnolia page. You see the field you added at the bottom of the dialog.
You must now change the template script to render this new content on the page.
Update the component template script
When rendering content you should test whether it exists. At the moment, at least the quotation must exist, otherwise the whole component will not be rendered. Take a look at your quotation.ftl
file:
[#if content.quotation?has_content] <blockquote> ${cmsfn.decode(content).quotation} [#if content.citedPerson?has_content]<cite>${content.citedPerson}</cite>[/#if] </blockquote> [/#if]
Add the following line to the blockquote section to render the Quotation source field's content in the page:
[#if content.quoteSource?has_content]<div class="quoteSource">${content.quoteSource}</div>[/#if]
Refresh your page in Magnolia to see the Quotation source field's content rendered in the page you created:
Add an additional resource
Currently, your hello.ftl
page template script links to the style.css
file in your light-modules folder (line 8):
[#assign title = content.title!"Hello Magnolia :-)"] <!DOCTYPE html> <html> <head> <title>${title}</title> <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Raleway:200" type="text/css"> <link rel="stylesheet" href="${ctx.contextPath}/.resources/hello-magnolia/webresources/css/style.css"> [@cms.page /] </head> <body> <div class="container"> <header> <h1>${title}</h1> [#if content.introText?has_content]<p>${content.introText}</p>[/#if] </header> <div class="main"> [@cms.area name="main"/] </div> </div> </body> </html>
Create a second CSS file in the webresources folder called style2.css
, containing the following style:
div.quoteSource { color: #ff0000; font-style: italic; }
Add the following statement below line 8 in the template script to link to your new CSS file:
<link rel="stylesheet" href="${ctx.contextPath}/.resources/hello-magnolia/webresources/css/style2.css">
As a result, the new style is applied to the Quotation source rendered on your page:
Alternatively, you can use
resfn
to link to all the CSS files in the hello-magnolia
module by replacing lines 8 and 9 with a pattern such as:
${resfn.css("/hello-magnolia/.*css")}
Congratulations!
You have finished this getting started tutorial for front-end developers, and have learned the key Magnolia concepts.
Go further
Now you have completed this tutorial, have a look at:
- Hello Magnolia - A step by step walkthrough of creating the Hello Magnolia light module.
- CLI overview - Watch the CLI Video to learn how to quickly create modules, and page and component templates.
- Magnolia CLI walkthrough - Walks you through the basic steps and commands required to create a Magnolia light module using our CLI and reuse an exisiting module from npm.
- Working with images in Magnolia - Learn how to handle images with Magnolia, including both storing the image or a reference to an asset with a dialog and rendering the image in a template script.
- Creating a website with Magnolia - Learn how to create templates and how to display content from a content app.