Hello-cloud - a development tutorial

In this tutorial you will:

In Part A
- Write code using only a few Magnolia CLI commands to create a functional Magnolia light module containing a page template and a component template. The resulting FreeMarker template scripts, the YAML-formatted template definitions and dialog definitions will appear in the light-modules directory.
- Test the code on a Magnolia bundle running locally.
- Send the code to the cloud-based Magnolia Git repository, using the commit and push commands.
In Part B
- Install the code in cloud-based Magnolia environments via the Cockpit.

Prerequisites

Before you start, make sure you have:

Installed and started a Magnolia bundle for local development on your machine
Set up the Integration, UAT, and Live environments in the Cockpit.

A) On your local machine

1. Write new code

Create a light-module directory

Open a shell and create the following light-modules directory (Mac path usage is shown):

/Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules

Create a light module

Change to the light-modules directory and execute the create-light-module command to create a light module called hello-cloud:

mgnl create-light-module hello-cloud

Magnolia CLI creates the following structure in the directory:

~/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules/hello-cloud

hello-cloud/
├── decorations
├── dialogs
│   ├── components
│   └── pages
├── i18n
│   └── hello-cloud-messages_en.properties
├── includes
├── templates
│   ├── components
│   └── pages
└── webresources

Create a page template

Now cd into the newly created hello-cloud directory and execute the following command to create a page, giving the page the name cloudy-page.

cd hello-cloud/
mgnl create-page cloudy-page

All going well, Magnolia CLI creates three files:

Page template definition	`light-modules/hello-cloud/templates/pages/cloudy-page.yaml`
Page template script	`light-modules/hello-cloud/templates/pages/cloudy-page.ftl`
Page dialog definition	`light-modules/hello-cloud/dialogs/pages/cloudy-page.yaml`

In a real-world situation you would edit these files, for instance to apply a stylesheet. In this tutorial we will skip this step to simplify.

Create a component

In the shell, make sure that you are still in the hello-cloud directory. In a Mac or Linux shell, you can use the pwd command to see the path to the current directory:

pwd
/Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/light-modules/hello-cloud

Run the following command to create a component, naming it bluesky-component.

mgnl create-component bluesky-component

Magnolia CLI creates three additional files:

Component template definition	`light-modules/hello-cloud/templates/components/bluesky-component.yaml`
Component template script	`light-modules/hello-cloud/templates/components/bluesky-component.ftl`
Component dialog definition	`light-modules/hello-cloud/hello-cloud/dialogs/components/bluesky-component.yaml`

Again, in a real-world situation you would edit and refine the component even further, but we will not do that in this tutorial.

Make the component available to the page template

We want to make sure that the new component can be used in the new page template. Execute the following Magnolia CLI command to make the bluesky-component available in cloudy-page in the main area.

Before executing the command, have a look a these files:

light-modules/hello-cloud/templates/pages/cloudy-page.yaml
light-modules/hello-cloud/templates/pages/cloudy-page.ftl

Magnolia CLI will modify these files when you run the mgnl add-availability command from the hello-cloud directory:

mgnl add-availability components/bluesky-component pages/cloudy-page@main

Please note that Magnolia CLI may have inserted the area directive at the very end of the .ftl file. Edit cloudy-page.ftl and move the directive to the position that immediately follows the <h1/> tag:

Click here to see how to edit cloudy-page.ftl

See line 15 in the example below. The line number in your file can be different, but make sure you place the area directive after the <h1/> tag.

cloudy-page.ftl

<!DOCTYPE html>
<html xml:lang="${cmsfn.language()}" lang="${cmsfn.language()}">
  <head>
    [@cms.page /]
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>${content.windowTitle!content.title!}</title>
    <meta name="description" content="${content.description!""}" />
    <meta name="keywords" content="${content.keywords!""}" />

  </head>
  <body class="cloudy-page ${cmsfn.language()}">
    <div class="container ">
      <h1>cloudy-page works!</h1>
    [@cms.area name="main"/]
    </div>
  </body>
</html>

Make an MTK component available to the page template

Use the MTK module (Magnolia Templating Kit module) to make the components, such as HTML, available in the cloudy-page of the hello-cloud light module. To make the component available to the cloudy-page template in the main area, execute the following command from the hello-cloud directory:

mgnl add-availability mtk:components/html pages/cloudy-page@main

The command will modify the light-modules/hello-cloud/templates/pages/cloudy-page.yaml file.

2. Test the code

Now it's time to test the new template on your local Magnolia instance. Make sure your local Magnolia is running.

Login to your local Magnolia installation

Use your favorite web browser to open the URL http://localhost:8080/magnoliaAuthor/ . The first request may take some time if Magnolia has to finish installing its modules. When you see the login screen, enter superuser for both the user name and password:

Create a new page with the cloudy-page template

Open the Pages app and add a page. Name it home and select the cloudy-page template:

Open cloudy-page for editing:

Add a component to the MAIN area. Make sure that both the bluesky-component and HTML components are available :

Find hello-cloud in the Resource Files app

Open the Resource Files app (Web Dev > Resource Files). In the tree you should be able to see and verify that the hello-cloud light module is present with all of its resources. The filesystem icon ( ) in the Origin column will indicate that all of the resources in the module are stored on your local filesystem.

3. Send the code to the cloud-based Magnolia repository

When you are satisfied with your new hello-cloud light module, push the changes to the cloud-based Magnolia instance using Git commands . Before you can push, you must add and then commit your changes to Git.

Open the shell and cd to the root directory of the Git repository:

cd /Users/<username>/dev/repo/mgnl-cloud-packages/magnolia-docs/

Add the folder of the new light module to the Git index:

git add light-modules/hello-cloud/

Commit the changes with a meaningful commit message:

 git commit -m "Add light-module 'hello-cloud'"

With this command you have just created a new entry in Git's history. The entry is sent to the Magnolia repository in the next step.

Send your code to the cloud-based Magnolia repository with the Git push command:

git push

If the push is successful, you see some something like this:

Counting objects: 11, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (11/11), 1.40 KiB | 1.40 MiB/s, done.
Total 11 (delta 1), reused 4 (delta 0)
To https://git.magnolia-cms.com/scm/odc/magnolia-docs.git
   79b2c82..ef4fabc  master -> master

Finally, run the git status command. You should get something like this:

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean

Great! You've successfully concluded the first part of the tutorial in which you have created a Magnolia light module and pushed it to your Magnolia Git repository. In the next part of the tutorial you will be working in the Magnolia cockpit.

B) In the Magnolia cockpit

The Magnolia cockpit guides you through the next few actions.

4. Install a development snapshot containing the new light module

In this section you make the most recent changes (the latest commit) available in the Magnolia Integration environment by installing a snapshot.

Reminder: We assume that you have already set up the Integration, UAT, and Live environments in the Cockpit.

Log in to the Magnolia cockpit and click Show package overview > Install an update in the Installed releases section towards the bottom of the page.

On the Install an update page click Install a development snapshot:

A two-step wizard guides you through how to retrieve your latest commit from the Git repository and install it in the Integration environment. The Latest commi t option in the wizard includes the hello-cloud light module you committed to Git in step 3 of this tutorial.

Once you have completed the steps in the wizard, look at the Integration environment in the Package overview page. Note that a branch icon is displayed to indicate that your Git commit snapshot is installed in the Integration environment.

At this point you can check that your module updates are present in the installed snapshot by going to the Magnolia author instance via the Edit content link in the Integration section. The state of the light modules should now be identical in both your local Magnolia instance and the cloud-based Integration environment.

5. Define a release with the hello-cloud module

You now wrap the snapshot carrying the module updates into an installable release. In fact, all of the development snapshots installed in the Integration environment since the last release are wrapped into a single release, but in this tutorial there is only one snapshot to wrap. Click Install an update in the Installed releases section.

On the Install an update page click Define a new release:

Another three-step wizard guides you through how to wrap the snapshot containing the hello-cloud light module into a release.

Once you have completed the steps in the wizard, look at the Integration environment in the Package overview page. Note that the release is assigned a version number that is displayed instead of the branch icon in the Integration environment section . You will refer to this version number later on when installing in environments.

6. Install the new release in the UAT environment

After you have defined the release, you install it in the UAT and Live environments. Start with the installation in the UAT environment.

Click Install an update in the Installed releases section.

On the Install an update page click Install a release:

Another four-step wizard guides you through how to install the release to the UAT or Live environment.

Choose the release version you have just defined and the UAT option in this step of the tutorial.

Once you have completed the steps in the wizard, look at the UAT environment in the Package overview page. Note that the same release version is now displayed in both the Integration and UAT environment sections.

7. Install the release in Live

This is the last step in the whole cycle. Installing a release in the Live environment is almost identical to installing in UAT.

In Package overview click Install an update and on the next screen choose Install a release again.

This time in the four-step wizard, choose the release version you have just installed in the UAT environment and the Live option.

Once you have completed the steps in the wizard, look at the Live environment in the Package overview page. Note that the same release version is now displayed in all the environment sections.

8. Check the result of the installation in Package overview

In Package overview all of the envi ronments should now be running your release version :

You can now open the author instance in the Live environment and create a new page using the hello-cloud template in the very same way as in step 2 above (Test the code). The difference is that the author and public instances are now running as part of your cloud-based Magnolia installation.

For example, here we have added a page named "home" using the cloudy-page template, and added the bluesky-component and HTML components to the main area (with an image and some text):

If you publish the page (and in this example, the image), it looks like this in the Public instance :

Congratulations, you have completed this tutorial!

Have a look at the rest of the Magnolia Cloud or dig further into light module development by learning about front-end development in Magnolia.

Page tree