How to use the Magnolia CLI tool

Published on September 2, 2016 by Tomas Gregovsky



Originally I wrote this blog post a couple of weeks ago but just after it was published, the public beta version of Magnolia CLI tool was released which includes a couple of changes so here I am revisiting the original blog post to match with the latest version.

 

Those of you who attended this year's Magnolia Conference in Basel may have seen me and my colleague Jan Haderka giving a presentation - The world's fastest CMS for front end developers, where the first part shows a brand new Magnolia CLI tool. That was the first time we previewed this tool and now that it's finally public (well just as an alpha version, but why not to give it a try) let's have a look at how this tool can really speed up front-enders live while working with Magnolia light development.  

 

So what does it do?

While using light development and working with light modules, creating pages and components templates, front-end developers have to follow up some coding practices (such as a light module folder structure), for each component create 3 different files (yaml definition, yaml dialog and template script), of course in different folders, as well as use the right paths and id.s to reference them. Then for dialog, when you need to add a field, you usually have to go to Magnolia documentation page, find the proper field definition and copy and paste into dialog. If you want to add this component to a page, you also have to go and edit that page, define a new area and in template script add code to render that area. Again, probably after searching and copying and pasting from a document or elsewhere. Imagine having to do this for dozens of components and pages! At the end it gets really boring. But what's worse, it is vulnerable to typos and can easily be misunderstood by someone completely new. 

 

Instead of that, with the CLI - Command Line Interface tool, all this mess can be reduced to a single command like this: 

 

Which will automatically generate all the material in the right locations such as: 

  • New file with template definition <light-module>/templates/components/myTextComponent.yaml referencing new template script and new dialog (see next points)
  • New file with dialog definition <light-module>/dialogs/components/myTextComponent.yaml with 6 mostly used fields definitions (text, rich text, image, internal link, multivalue, select). You can easily go and remove or modify what you don’t want.
  • New file with template script <light-module>/templates/components/myTextComponent.ftl with basic code to render all properties from default dialog (title, image, internal link, list of categories, etc…). Again this is easy to reduce or modify.
  • Modified <light-module>/templates/pages/home.yaml with added availability for myTextComponent in ‘main’ area. 
  • Added freemarker code to render main area in home page template script if the area is new. 

Yes, all that is handled and preconfigured just by typing that command.

Now that I hope I've got you interested in this tool, let's see how to install it and all that you can do with it.

 

Installation

The CLI tool runs on Node.js, so the first thing you need to do is have Node.js installed with version at least 4.4.7+. You can check from command line which version you have:

“node -v”

 

And it is distributed as NPM module so that means that installation is easy. CLI tool is in public beta version at the time of writing this blog post so it must be installed from our registry. And it needs to be installed globally. So the installation command is:

npm --registry=https://npm.magnolia-cms.com/repository/npm install @magnolia/cli@beta -g

*In case of reinstalling it later and gettiing a “write permission” error, do it as superuser (with “sudo” at beginning)

 

Quickly confirm that the CLI tool is installed and ready to use by checking help:

mgnl help

 

Create anything

In case you already have an existing light module, just navigate to that folder in terminal and you can start creating components and pages (skip next command). 

Otherwise, if you don't have a light module yet let's start and create it:

mgnl create-light-module abc

Which will create the basic folder structure needed for light module ‘abc’. E.g page and components templates folders, the same for dialogs, webresources, etc… 

 

Then navigate to the light module itself (or alternatively use --path <path> parameter) and create a page:

cd abc
mgnl create-page home

or:

mgnl create-page home --path abc

As result we have a new page definition (with running Magnolia immediately available) for our home page.

The page itself is a simple definition with default page property dialog for such things as titles, navigation titles, keywords, etc… and simple page template script which you have to open to edit to place your html layout or/and load resources on the page.

To make it easier there are already 3 examples of how to render css or js on page and it is just about uncommenting that one you want to use - html tag with direct link, over theme or neat-resources (hcmcfn) which I would recommend (neat-resources module must be installed), because then just dropping css or js into webresources folder they will be loaded on the page.

 

But back to our CLI, the next command we can use is to create, for example, an intro component:

mgnl create-component intro --available pages/home@introArea

This will create all files (definition, dialog, ftl) needed for a new intro component. It will also edit the home page definition and add availability into ‘introArea’. In case when this area does not exist yet (like now in our example) then it is created. Alternatively you may skip to specify area (@introArea) in command and then ‘main’ area will be automatically used. 

Instead of ‘--available’ it is possible to use shorter ‘-a’ same as ‘-g’ for ‘--autogenerate’, which instead of making a component available will make it autogenerated. And you can also use this command to make a component available in another component. So for instance, the example of command for creating component ‘logo’ autogenerated in the ‘main’ area of ‘header’ component may look like:

mgnl create-component logo -g components/header

 

All these availability features can be also used just for making component available with ‘add-availability’ command:

mgnl add-availability mtk:components/link pages/home@footerArea

*in current beta version target area (e.g. @footerArea) always has to be specified (even if it is main area)
 

Jumpstart

There is no doubt that the commands above are the main time saver, but there are also a couple of other features in the CLI tool which can make your developer life easier. One of them is a  ‘jumpstart’ - this command is used to jumpstart Magnolia projects. Let's start again just after the installation of the CLI tool, then (in another working directory) run command:

mgnl jumpstart

Will download latest version of Magnolia CE, unpack Apache Tomcat server, configure Magnolia properties file including pointing to just created light-modules folder where new light modules should be created and from where Magnolia will automatically load them. 

 

Customization

During all of these actions there are a lot of things happening and some of them you can customize. Firstly, what you have to do is to run command:

mgnl setup

Which will expose you mgnl-cli.json configuration file you may edit to change some stuff happening during jumpstart or creating light module e.g. which Magnolia version has to be downloaded. Let's have a look at some properties which can be modified:

 

  • setupMagnolia.downloadUrl - url of Magnolia bundle which has to be downloaded during jumpstart
  • setupMagnolia.webapps - list of properties which have to be edited in magnolia.properties files
  • setupMagnolia.downloadJars - additional jar libraries which have to be downloaded and copied to WEB-INF/lib folders of all webapps
  • lightDevFoldersInModule - list of folders which will be created in the light module

*But please be careful here. I would recommend not to touch any other configuration that you haven't added by yourself before. 

 

Other than mgnl-cli.json ‘mgnl setup’ also exposes your template definition prototypes, which are then in ‘mgnl-cli-prototypes’ folder and by editing them (e.g. /mgnl-cli-prototypes/components/dialog.yaml) you can completely change how definitions (dialogs, templates, template scripts) for your future created components will look like. 

 

Use it the way you want to 

So in the scope of all that I've mentioned above, the Magnolia CLI tool can be used for jumpstarting from nothing to downloading the latest Magnolia. You can set up everything you need and it will get to the stage where you just start developing templates just with your text editor and locally running Magnolia without IDE or other advanced developer setups. 

This can be pretty handy especially for new Magnolia front-end devs who with default configuration can get Magnolia set up and installed with just a few commands (installation of cli, jumpstart) and start creating pages and components almost without Magnolia knowledge and potentially start to learn from stuff they just created.

Or as an advanced developer, when you have your project already running, just open your light module folder and shoot new components just like with a machine gun. 



Comments



{{item.userId}}   {{item.timestamp | timestampToDate}}

About the author Tomas Gregovsky

Tomas Gregovsky is a web and front end developer with 15 years of experience. He joined Magnolia three years ago and focuses on the development of Magnolia’s websites. In his free time, he likes to spend time with his family and friends, snowboard and watch American football. He mostly blogs about using Magnolia as a front-end developer.


See all posts on Tomas Gregovsky

Demo site Contact us Free trial