Tutorial structure
Prerequisites
You need to be able to install Magnolia and in order to do that, you need Java, Node.js, npm, Git, and access to the Magnolia Cockpit which is provided to you when you signed up for Magnolia Cloud.
If you have any issues with logging into the Cockpit, please contact the Magnolia Cloud Helpdesk.
Java
Magnolia needs a Java Runtime Environment (JRE) from at least version 8. See the Certified stack page to confirm the latest supported Java version. Check your java version by going to your terminal and running java --version
. If you do not see a version number as below, you need to install Java for your operating system.
$ java --version java 13.0.1 2019-10-15 Java(TM) SE Runtime Environment (build 13.0.1+7) Java HotSpot(TM) 64-Bit Server VM (build 13.0.1+7, mixed mode, sharing)
For your OS
Node and npm
You also need Node.js and npm. Check this by running node --version
and npm --version
respectively in your terminal. If you do not see a version (as below), you must install Node.js and npm.
$ node --version v12.18.1 $ npm --version 6.14.5
Install
If you do not have Node installed, go to Node.js to download and install the latest LTS version. For installation instructions of npm, see https://docs.npmjs.com/downloading-and-installing-node-js-and-npm.
Git
Finally, you need Git for version control and pushing local changes to your Magnolia remote repository. Check this by running git --version
. If you do not have git, download the latest stable version from Git's website here.
$ git --version git version 2.27.0
Get Magnolia
Run npm install @magnolia /cli -g
in your terminal where the -g
flag makes Magnolia available to you globally on your machine. To check if Magnolia was installed successfully, run mgnl --version
and you will see the Magnolia CLI version number (as below).
$ mgnl --version Magnolia CLI: 3.1.0 (node.js: v12.18.1)
You may have to run the terminal as an administrator if you receive an error such as npm ERR!
.
MAC or Linux:
sudo npm install @magnolia /cli -g
Windows:
Right click CMD, and choose Run as Administrator.
Jumpstart Magnolia
Now that Magnolia is installed, let's jumpstart it.
- Navigate to the directory where you want to download Magnolia. For example purposes, we'll call this directory
magnolia
. In your
magnolia
directory, runmgnl jumpstart -m <version>
. If prompted, choose option3 magnolia-community-demo-webapp
. If successful, you see:.... info Magnolia has been successfully setup for light development! ....
To make sure it's working, run
mgnl start
from themagnolia
directory and after a few seconds, go to the localhost:8080/magnoliaAuthor in your browser and log in as superuser with the password superuser.For now, shut down the local server by entering
CTRL+C
in your terminal where the server is running.
The jumpstart
command:
- Downloads the Magnolia bundle specified into the
magnolia
directory. - Creates a
light-modules
folder in the directory. - Changes the default value of the
magnolia.resources.dir
configuration property from${magnolia.home}/modules
to/magnolia/light-modules
for both the Author and the Public instances of Magnolia.
Prepare Environments in the Cockpit
In this section, we log in to the Cockpit and set up new Integration , UAT , and Live environments. If these environments were already set up during onboarding, you can skip this step.
If you have any issues with logging into the Cockpit, please contact the Magnolia Cloud Helpdesk.
- Log in to the Cockpit.
- Set up a new Environment for Integration, UAT, and Live. You will need to repeat these steps for each of the three environment types.
- On the landing page by your Subscriptions, click Show Package Overview on the right side of the page.
- Choose Set up environment for the chosen Environment ( Integration, UAT, or Live ).
- Choose the Magnolia version. You can see runtime information regarding the available bundles.
Click Set up <environment name>. The creation of the environment may take some time.
Click OK.
Actions in the Magnolia Cockpit are asynchronous. You receive a notification when the Environment is up and running.
- Copy or note your Magnolia Cloud .git repository from the Cockpit. This is found under Additional Information on the Package Overview page.
Create a Light Module
OK, so let's create something - specifically a light module. We are now back on your local machine in the magnolia
folder where we installed Magnolia.
If you are curious to know more about light modules, check them out here. But, let's continue on for now.
- In the root
magnolia
folder, initialize a git repository and add your Magnolia Cloud repo as the remote origin.- run
git init
- run
git remote add origin <yourMagnoliaRemoteRepo>
. This is what you just copied from the Cockpit. - run
git remote -v
and you should see your Magnolia repo as theorigin
for bothfetch
andpush
. - run
git pull origin master
and now you're ready to make some local changes. This may take a minute.
- run
- Navigate down one level to your
light-modules
directory. Run
mgnl create-light-module forest
. Magnolia CLI has now created the following for you:The forest light module is now ready. Navigate to
light-modules/forest
. Create a page template in forest usingmgnl create-page big-tree
.That command created:light-modules/forest/templates/pages/big-tree.yaml
A Page template script
light-modules/forest/templates/pages/big-tree.ftl
A Page dialog definition
light-modules/forest/dialogs/pages/big-tree.yaml
In
light-modules/forest
, runmgnl create-component nest
to create a component.That command created:A Component template definition
light-modules/forest/templates/components/nest.yaml
A Component template script
light-modules/forest/templates/components/nest.ftl
Component dialog definition
light-modules/forest/dialogs/components/nest.yaml
We need to make the nest component available to the big-tree page template. Still in
light-modules/forest
, runmgnl add-availability components/nest pages/big-tree@main
.That command:Added
[@cms.area name="main"/]
to:light-modules/forest/templates/components/big-tree.yaml
Added the component
nest
with anid:forest:components/nest
to:light-modules/forest/templates/components/big-tree.ftl
In
light-modules/forest/templates/pages/big-tree.ftl
, make sure the main area is inside the<div class="container">
as so:<div class="container"> <h1>big-tree works!</h1> [@cms.area name="main"/] </div>
Make the MTK module (Magnolia Templating Kit module) HTML available to the big-tree page. From
light-modules/forest
, runmgnl add-availability mtk:components/html pages/big-tree@main
. Yourtemplates/pages/big-tree.yaml
file should now look like:Let's add some simple functionality. Navigate to and open
/magnolia/light-modules/forest/templates/pages/big-tree.ftl
.Uncomment the
resfn.css
andrefsn.js
snippets.Save the File.
big-tree.ftl.... ${resfn.css(["/forest/.*css"])!} </head> .... ${resfn.js(["/forest/.*js"])!} </body>
Navigate to and open
/magnolia/light-modules/forest/templates/components/nest.ftl
.Add a simple button and div below the
content.title
section at the top of the file.Save the File.
nest.ftl<div class="nest"> [#if content.title?has_content] <h2>${content.title!}</h2> [/#if] <!-- add the button and div below --> <button onclick="tweet()">Click me</button> <div id="birdie"><h2>I'm a wee birdie</h2></div> ....
Create a new folder called css at
forest/webresources
.Navigate to the new
forest/webresources/css
folder.Create a file called styles.css.
Copy and paste the code below into styles.css.
Save the File.
styles.cssdiv.nest { background-color: #8c720b; padding: 100px; border-radius: 15px 50px; color: white; } button { padding: 5px; background-color: rgb(129, 126, 125); color: whitesmoke; border-radius: 8px; box-shadow: -1px 0px 11px -3px rgba(0, 0, 0, 0.671); cursor: pointer; } #birdie { display: none; }
Finally, create a new folder called js at
forest/webresources
.Navigate to the new
forest/webresources/js
folder.Create a file called tweet.js.
Copy and paste the code below into the tweet.js file.
Save the File.
tweet.jsfunction tweet() { var x = document.getElementById("birdie"); if (x.style.display === "none") { x.style.display = "block"; } else { x.style.display = "none"; } }
Local test
- In the root
magnolia
folder, runmgnl start
and then use your favorite web browser to open the URLhttp://localhost:8080/magnoliaAuthor/
. - Create a new page with using your big-tree page template and choose the nest component.
- Navigate to the Pages App via the icon on the top bar.
- Click Add Page.
Name the page home and click on big-tree template.
- Double-click the newly-created home page.
Add the nest component to the page.
- Navigate to the Pages App via the
Make sure your forest module is in your Resource Files app.
Use the search bar at the top and type Resource Files.
Push your changes
If you are happy that all is well locally, let's push those changes to your Magnolia Cloud repository.
- In the the
magnolia
folder (the parent directory of your light-modules) stop the local server withCTRL+C
. - Run
git add . && git commit -m "flyAway" && git push origin master
.
Install git changes in the Cockpit
Go back to your Cockpit and log in using your provided credentials.
- Navigate to My Subscription Packages > Subscription > Install an Update.
Choose Install a development snapshot. Choose Branch > Master in the on-screen wizard.
On the Install an Update page, Choose Define a new release. Follow the on-screen wizard.
On the Install an Update Page, Choose Install a release. Follow the on-screen wizard for the UAT and repeat for the Live Environment as well.
Create a Page
- Navigate to your Live Environment under Environments.
Go into the Author space by clicking on the author URL under the Artifact ID.
Edit the Home page by right clicking it and choosing Change Template and change the template to use your big-tree page template.
- Publish the page.
- Click Preview Page.
- Once in Preview, click Publish. This assigns a publishing task to your publishing group.
- Navigate to Tasks, found in the top navigation bar.
- Select the task and click Assign to Me.
- Navigate to the Assigned Tab in Tasks.
- Click on the task assigned to you.
- Click Preview Task.
- Once in Preview, click Approve and Publish.
Take a bow, my friend. You're done. You have successfully:
- Logged in to your Cockpit.
- Set up Integration, UAT, and Live environments.
- Made changes locally via Magnolia CLI, pushed them to Magnolia Cloud, and implemented those changes.
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 .