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:
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 |
|
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 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:
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.