Hello Magnolia for front-end developers

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:

* hello-magnolia.zip

 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. 

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:

1. Open the Pages app.
2. Create a new page. 
3. Enter Hello Magnolia as the Page name.
4. Select the Hello template introduced by your light module and click Next.
5. Enter Hello Magnolia as the Title and This page was created using the hello template as the Introduction text and click Save.
6. 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: 

1. Click on the New main component bar in your Hello Magnolia page.
2. 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

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:

${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.