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.
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):
Create a light module
create-light-module command to create a light module called
hello-cloud in the directory you have just created:
Speaking of module names in general, please remember to use only the characters from the
[a-zA-Z0-9-_] regex range when creating a module name.
Magnolia CLI creates the following structure in the directory:
Create a page template
cd into the newly created
hello-cloud directory and execute the following command to create a page, giving the page the name
All going well, Magnolia CLI creates three files:
|Page template definition|
|Page template script|
|Page dialog definition|
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:
Run the following command to create a component, naming it
Magnolia CLI creates three additional files:
|Component template definition|
|Component template script|
|Component dialog definition|
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
Before executing the command, have a look a these files:
Magnolia CLI will modify these files when you run the
mgnl add-availability command from the
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
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.
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
The command will modify the
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
Add a component to the MAIN area. Make sure that both the
HTMLcomponents 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:
Add the folder of the new light module to the Git index:
Commit the changes with a meaningful commit message:
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
If the push is successful, you see some something like this:
Finally, run the
git status command. You should get something like this:
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.Great!
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
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!