Part II - Creating a light module

Part I - Installing and setting up the CLI and Magnolia is a prerequisite to Part II.

In the second part of this tutorial, you create a light module called bucket-list-module. From there, we create templates to build out the list.

Each page represents an item on our list. Each component provides a way of adding content to the bucket list, such as a description of the activity or an image to illustrate it.

Create a light module

To create a light module, open the light-modules directory and run the following command in a shell:

mgnl create-light-module bucket-list-module

In this tutorial, the module is called bucket-list-module.

The following directory tree is created:

/bucket-list-module/
├── README.md
├── decorations
├── dialogs
│ ├── components
│ └── pages
├── i18n
│ └── bucket-list-module-messages_en.properties
├── includes
│ └── README.txt
├── templates
│ ├── components
│ └── pages
└── webresources

Check the result in Magnolia:

In Magnolia, open the Resource Files app.
Check the light module you created appears in the browser:

Light module structure in the Resource Files app

Search for apps or for content across all your apps using the Find Bar. Open an app directly from the Find Bar using the command open <app-title> app, for example, type open pages app. You must use the exact app title, as it appears in the App Launcher.

Create a page

In the shell, change into the bucket-list-module folder and run the following command:

mgnl create-page bucket-list -P my-page-prototype

This command creates all the files needed for a page template definition called bucket-list based on the my-page-prototype variant you created.

Additional files are created in the module tree:

/bucket-list-module/
├── README.md
├── decorations
├── dialogs
│   ├── components
│   └── pages
│       └── bucket-list.yaml
├── i18n
│   └── bucket-list-module-messages_en.properties
├── includes
│   └── README.txt
├── templates
│   ├── components
│   └── pages
│       ├── bucket-list.ftl
│       └── bucket-list.yaml
└── webresources
    └── css
        └── bucket-list.css

Check the result in Magnolia:

In Magnolia, open the Pages app.
Click Add page.
Enter the name item 1 for your page.
Select the bucket-list template for your new page and click Next.
Enter the title Dive with sharks in the page properties dialog.

This dialog is based on the <light-modules>/mgnl-cli-prototypes/page/my-page-prototype/templates/pages/__name__.yaml variant you created.
Save your changes.
Open the page.

There is no main area or component on the page you created yet but you can already see the styling from the CSS file you added in the prototype variant.

Create the `activity` component

First we add an activity component to provide a title and description for the activity in the bucket list.

To create a component called activity, make sure you are still in the bucket-list-module folder and run the following command in a shell:

mgnl create-component activity -P my-component-prototype

Go to Magnolia again and refresh your page.

Note that there is still no main area or component on the page you created.

Make the `activity` component available

Run the following command in a shell:

mgnl add-availability activity bucket-list@main

Now you should move the FreeMarker expression [@cms.area name="main"/] to inside the HTML body tag in your pages template script.

To do so:

Open your light-modules/bucket-list-module/templates/pages/bucket-list.ftl file in a text editor.
Add a <div/> element with the area just below the <h1/> element.

Move the expression [@cms.area name="main"/] to inside the new <div/> element.

light-modules/bucket-list-module/templates/pages/bucket-list.ftl

<!DOCTYPE html>
<html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}">
  <head>
   <link rel="stylesheet" type="text/css" href="${ctx.contextPath}/.resources/bucket-list-module/webresources/css/bucket-list.css" media="all" />
    [@cms.page /]
    <title>${content.windowTitle!content.title!}</title>
  </head>
  <body>
    <div class="container ">
      <h1>${content.windowTitle!content.title!}</h1>
      <div class="main">  (2)
         [@cms.area name="main"/] (1)
      </div>
    </div>
  </body>
</html>

1	The FreeMarker expression `[@cms.area name="main"/]` includes the area.
2	The `<div class="main">` element wraps the expression for styling purposes.

Go to Magnolia again and refresh your page. Notice that the component activity is available in a new area called main.

Added the activity component

Click the New main component green bar to add the component to your page.

Go ahead and add a title and description for the first item on your bucket list.

Add availability for some pre-existing components

You can make components from other modules, light or otherwise, available in your page template. We will make the following two components provided by the Magnolia Templating Kit module available in our page (in the main area):

image component, to provide an illustration for our bucket list item.
linkList component, to make a list of links to the different item pages.

To make the image component available, run the following command in a shell:

mgnl add-availability mtk2:components/image pages/bucket-list@main

To make the link list component available, run the following command in a shell:

mgnl add-availability mtk2:components/linkList pages/bucket-list@main

When adding a component to your page, you can now select the Image component delivered with the MTK module.

Select the Image component and the before first component option to add the component to your page before the activity component. Upload an image of your choice.

Preview your page:

Image component added with an example image

Now repeat the steps to add another page called item 2 with another of your own top bucket list picks in the activity component. We decided to go hot air ballooning after shark diving!

Create a parent page to list the items

In the step before we added availability for the Link list component provided by the MTK. Let’s use it to create a parent page listing all the items on our bucket list.

Create a new page called list, based on the bucket-list template, with the title My bucket list.

Drag and drop your two item pages under the new list page. If you didn’t create a second item, just move the shark diving page.

Open the list page and add the Link list component to the main area.

Add a Subtitle and select Ordered list as the list style.

Adding Link list component

In the Link list component, add links to the two item pages. You don’t need to enter a title: the title of the page selected in the Page link field is used by default.

Select link targets for the link list component

Click Preview page to see what the My bucket list page will look like once published. You can click on the links you entered to access your bucket list item pages.

Previewing the final Buckwt list page

Congratulations! You have used the Magnolia CLI to create a fully functional light module with a page template and several components.

Next: Part III - Reusing a light module from npm

Credits:

Tiger shark image by Albert Kok (own work) CC BY-SA 3.0 (http://creativecommons.org/licenses/by-sa/3.0), via Wikimedia Commons.

Part II - Creating a light module

Create a light module

Create a page

Create the activity component

Make the activity component available

Add availability for some pre-existing components

Create a parent page to list the items

Location

Main doc sections

Create the `activity` component

Make the `activity` component available