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
Remove the version number from the extracted folder name. It should be just
Your file system should now look like this:
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:
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.
Hello Magnoliaas the Page name.
- Select the
Hello templateintroduced by your light module and click Next.
Hello Magnoliaas the Title and
This page was created using the hello templateas 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:
Add a third field called
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
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
Add the following line to the blockquote section to render the Quotation source field's content in the page:
Refresh your page in Magnolia to see the Quotation source field's content rendered in the page you created:
Add an additional resource
hello.ftl page template script links to the
style.css file in your light-modules folder (line 8):
Create a second CSS file in the webresources folder called
style2.css, containing the following style:
Add the following statement below line 8 in the template script to link to your new CSS file:
As a result, the new style is applied to the Quotation source rendered on your page:
Alternatively, you can use
to link to all the CSS files in the
hello-magnolia module by replacing lines 8 and 9 with a pattern such as:
You have finished this getting started tutorial for front-end developers, and have learned the key Magnolia concepts.
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.