Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
...
width | 370 |
---|---|
float | right |
class | menu |
Youtube | ||||||
---|---|---|---|---|---|---|
|
...
Artifact resource link | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
...
Magnolia CLI is an an npm package providing a command line interface (CLI) tool to set up and facilitate light development with Magnolia. This page describes how to install, set up and use its commands.
The commands of the Magnolia CLI package facilitate the creation of a light module skeleton: the folders and files that form a typical Magnolia light module. We assume that you are already familiar with some Magnolia basics of creating light modules, templates and dialogs.
Table of Contents | ||||
---|---|---|---|---|
|
The Magnolia CLI tool runs on Node.js. Make sure you have Node.js version 6.10+ installed (node.js may be easily installed via package managers).
To check the version of your node installation run the following command in a shell:
Code Pro |
---|
node -v |
Node.js provides two branches:
If your node version is below 6.10, install the latest version of the LTS branch (see node.js/download).
...
Bestpractice |
---|
Install Magnolia CLI globally.
|
The instructions that follow are based on the global npm package installation.
To install, run the following command in a shell:
Code Block |
---|
npm install @magnolia/cli -g |
Depending on your permissions and the Node.js installation location, you may have to execute the above command with root permissions. On Linux or OS-X to run this command as root use:
Code Block |
---|
sudo npm install @magnolia/cli -g |
If the installation is successful, the output in the shell should be similar to this:
Expand | ||
---|---|---|
| ||
|
If you have already installed the CLI and want to update to the latest version, use:
Code Block |
---|
npm update @magnolia/cli -g |
To test the installation, run the following command in the shell:
Code Block | ||
---|---|---|
| ||
mgnl help |
Expand | ||
---|---|---|
| ||
|
...
The Magnolia CLI package provides autocompletion for bash, C-shell and Windows PowerShell.
To install/enable autocompletion, use:
Code Block |
---|
mgnl tab-completion install |
To uninstall it, use:
Code Block |
---|
mgnl tab-completion uninstall |
A successful installation of autocompletion will display a list of files to which the tab-completion script has been appended.
To test the autocompletion installation type mgnl
and then successively hit the Tab key to scroll through the available commands.
Note | ||
---|---|---|
On Windows autocompletion is only available in PowerShell. If it does not work as expected after installation you may have to change your execution policy. To do this, in PowerShell run as Administrator:
|
...
If you have already used autocompletion with Magnolia CLI version below 2.0, you may want to uninstall the "old" autocompletion manually. To do so, remove the following line in your bash settings (in ~/.profile or ~/.bashrc):
Code Pro |
---|
source /usr/local/lib/node_modules/@magnolia/cli/extra/mgnl-autocompletion.sh |
Magnolia CLI is configured in these files/folders:
...
The configuration file defining the folders of the light module skeleton and some other things.
When a CLI command is executed, the system searches for the JSON configuration.
Note |
---|
Do not modify the |
Tip |
---|
|
The global configuration is created during the global installation of the Magnolia CLI package. On Linux or OS-X the global configuration files are typically located in the /usr/local/lib/node_modules/@magnolia/cli
folder.
The CLI commands use the global configuration if no local configuration is found in the current directory or in its parent folders.
...
For different projects you can create various local configurations with the Copy of Magnolia CLI
command. This command creates local configuration files in the /wherever/you-have/executed/the-customize-local-config-command
folder.
The local configuration is created as a copy of the current configuration (used during execution of the customize-local-config
command), which you can edit to define project specific prototypes or dependencies.
When executing commands from within the local configuration folders or subfolders, the local configuration is used.
Note |
---|
You cannot mix global and local configurations. When adding a local configuration it must be complete: it must contain the If Magnolia CLI finds the |
...
This JSON file contains basic configurations which are used when running the Magnolia CLI commands. Here is a partial list of the properties which you might want to edit:
...
The URL used to download the bundle.
We do not recommend editing this property.
...
A map of artifacts to be added to the WEB-INF/lib
directory.
...
magnoliaAuthor
,
magnoliaPublic
...
If set these properties override the same properties in the magnolia.properties file by overwriting them there.
Note that you cannot set the magnolia.resources.dir
property since Magnolia CLI overrides it.
The properties are used to update the magnolia.properties files (on both public and author) when executing the jumpstart command.
...
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
This version of mgnl.json may not include all parameters described below. |
...
When executing either the create-page
or the create-component
command, new files are created from the prototype files. These prototype files are located in the mgnl-cli-prototypes
folder.
Code Pro |
---|
<configuration>/mgnl-cli-prototypes/
├── README.md.tpl
├── component
│ ├── definition.yaml
│ ├── dialog.yaml
│ └── template.ftl
└── page
├── definition.yaml
├── dialog.yaml
└── template.ftl |
Tip |
---|
Add the |
help
Run the help command to list all the available commands of the Magnolia CLI package.
mgnl help [<command>]
...
optional
Shows basic help for the <command>
specified as the option.
Without the option, a list of available CLI commands will be displayed (same as entering mgnl -h
).
.
Go to the latest version of Magnolia documentation for information about Magnolia CLI, including how to install, set up and use its commands.
tab-completion
Run the command to install or uninstall Copy of Magnolia CLI for Magnolia CLI commands.
mgnl tab-completion <command>
...
Code Pro |
---|
mgnl tab-completion install |
A successful installation will display a list of files to which the tab-completion script has been appended.
customize-local-config
Run this command to create a local configuration. It installs the files for the local configuration within the current directory, or within the directory defined by the optional -p <path>
parameter.
mgnl customize-local-config [options]
...
optional
The path into which the mgnl-cli-prototypes
folder and mgnl-cli.json
file are installed.
Code Pro |
---|
mgnl customize-local-config -p ~/dev/mgnl/light-modules/ |
jumpstart
This command downloads, unpacks and pre-configures a Magnolia Tomcat bundle. It creates folders for the Tomcat server and for the light modules according to the configuration.
By default the command downloads the latest released version of the magnolia-community-demo-bundle
. Use the -e
parameter to get the EE Pro demo bundle (magnolia-enterprise-pro-demo-bundle
) instead. These bundles contain the Magnolia Travel Demo. Chose a specific version by providing the -m
parameter.
Info |
---|
The jumpstart command installs the bundle within the current directory. You may remove the |
mgnl jumpstart [options]
...
optional
The -p option for the jumpstart command specifies the path to the light modules root folder which is observed for changes, not to an alternative location for the bundle to be installed.
The path to the light modules root folder is set by the magnolia.resources.dir
property in the magnolia.properties
file of the installed Magnolia bundle.
If no path is provided:
light-modules
is created in the current folder.magnolia.resources.dir=${magnolia.home}/../../../light-modules
...
optional
The desired version of the Magnolia bundle. If not provided, defaults to the latest version of the chosen bundle (magnolia-community-demo-bundle or magnolia-enterprise-pro-demo-bundle).
...
optional
If provided, a sample light module under the light modules root folder with the given name is created.
...
-e
...
optional (since 1.0.5)
Downloads a magnolia-enterprise-pro-demo-bundle
. Requires credentials to Magnolia Nexus.
...
optional (since 2.2.0)
Downloads a Magnolia Cloud bundle. Requires credentials to Magnolia Nexus.
Code Pro | ||
---|---|---|
| ||
mgnl jumpstart -e -m 5.4.5 |
Note | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
When running the See
|
start
This command starts up Magnolia and displays the main log file (apache-tomcat/logs/catalina.out
). Magnolia CLI looks in the current working directory or parent directories for the nearest folder with a name that starts with "apache-tomcat". To stop Magnolia, simply use CTRL+C.
mgnl start [options]
...
optional
The path to the apache-tomcat
folder. If no path is provided, Magnolia CLI will look in the current working directory or in the parent directories for the nearest folder with a name that starts with "apache-tomcat".
...
optional
Does NOT ignore the open files limit check. The files limit check is ignored by default. See Too many open files for more.
Code Pro |
---|
mgnl start -p C:/magnolia-installations/magnolia-5.5.1/apache-tomcat-8.5.5 |
create-light-module
This command creates a new light module in the form of a set of empty light module folders and the following two files:
README.md
, in the root folder of the module.<moduleName>-messages_en.properties
, in the i18n
folder this command creates.The name of the light module should be provided as a parameter when calling the command. The light module is created in the current directory or in the directory specified with the optional -p <path>
parameter.
mgnl create-light-module [<moduleName>] [
options
]
...
optional (but recommended)
The name of the new light module.
Avoid spaces and special characters since this name is used as folder name.
If no <moduleName>
is given, the name of the actual directory will be used as the module's name. This can be useful in case the folder for the light module already exists.
...
optional
The path of the parent directory for the new light module. If omitted, the new light module is created within the current folder.
Code Block |
---|
mgnl create-light-module my-module |
Code Block |
---|
mgnl create-light-module my-module -p ../../light-modules/ |
Expand | ||
---|---|---|
| ||
|
create-page
This command creates a new page template including:
The command succeeds only if the current directory (or the directory defined by the optional -p <path>
parameter) is a light module with a minimal folder structure. The files which are created when executing this command are built from the files in the Copy of Magnolia CLI
folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a page template.
mgnl create-page <templateName> [
options
]
...
required
The name of the new page template. The template name cannot contain spaces.
...
optional
The path to the light module to add the new template to.
If the parameter is omitted, the command must be run within an existing light module folder.
Code Pro |
---|
mgnl create-page my-page |
Note |
---|
If you do not use the |
Expand | ||
---|---|---|
| ||
|
add-availability
This command makes a component available to a page by:
cms:area
directive to the template script (if it is not already there).The command only succeeds if the current directory (or the directory defined by the -p <path>
parameter) is a light module with a minimal folder structure and if the page specified by the second argument exists.
mgnl add-availability <[module-id:]path-to-component> <path-to-page[@area]> [options]
...
required
The component you want to make available.
Must at least contain the path to a component.
Can optionally start with the module identifier [module‑id:]
. If the module identifier is not used, Magnolia CLI assumes the component belongs to the current light module or to the light module specified by the -p <path>
option.
Magnolia CLI does not check the existence of the specified component.
...
required
The page you want to make the component available to.
The parameter starts with the path to the page template within the templates directory and it must end with an area name [@area]
. If the area does not exist yet, the command adds an area to both the template script and the template definition.
If no area is specified, the command defaults to main
area (if it exists) or creates main
area (if it does not).
...
optional
The path to the light module that contains the page template.
If the parameter is omitted, the command must be run in an existing light module folder.
...
This example makes a component from the mtk
module available to the page named my-page
in the area named main
:
Code Pro |
---|
mgnl add-availability mtk:components/textImage pages/my-page@main |
This example makes the component my-component
available to the page my-page
. Both the component and the page are part of the light module located at /Users/jdoe/dev/mgnl/light-modules/my-module/
:
Code Pro |
---|
mgnl add-availability components/my-component pages/my-page@main -p /Users/jdoe/dev/mgnl/light-modules/my-module/ |
create-component
This command creates a new component template including:
Optionally, the component can be made available to a page using the -a
option (internally calling the Copy of Magnolia CLI
command).
The command succeeds only if the current directory (or the directory defined by the -p
option) is a light module with a minimal folder structure.
The files which are created while executing this command are based on the files in the mgnl-cli-prototypes
folder of your configuration. The files contain some standard code with some commonly used properties. This is generally a good starting point to build a component template.
mgnl create-component <name> [options]
...
required
The name of the new component template. The name cannot contain spaces.
...
optional
The path to the light module you want to add the component template to.
If the parameter is omitted, the command must be run within an existing light module folder.
...
optional
The page you want to make the component available to. When you specify this option, Copy of Magnolia CLI
is called after the creation of component to make it available in a page area.
The parameter must start with the path to the page template within the templates directory and it must end with an area name. If the area does not exist yet, the command adds an area to both the template script and the template definition. If no area is specified, the command defaults to main
area (if it exists) or creates main
area (if it does not).
...
optional
Add this parameter to autogenerate the component instead of providing plain availability. As for the -a
option the target area and page must be specified.
Code Pro |
---|
mgnl create-component my-component -a pages/my-page@footer -p /Users/johndoe/dev/mgnl/light-modules/my-module/ |
search
...
mgnl search [<query>]
...
optional
The search query sent to the npm's API (see https://api-docs.npms.io).
By default the command sends keywords:magnolia-light-module
with every search instance to make the search results more relevant to Magnolia light modules.
Code Pro |
---|
mgnl search language-switcher
info 1 result found
info
info 1) language-switcher-magnolia
info 2017-02-25 1.0.5
info Language Switcher - Component template for Magnolia CMS
info magnolia |
install
...
mgnl install <light-module-name> [options]
...
required
At least one name of a light module to be downloaded from npm. If installing more than one module from the repository, separate the module names with a space.
...
optional
The path to the light-modules folder.
If omitted, mgnl is searching for the nearest apache-tomcat*
folder and checks the value of the magnolia.resources.dir
property as defined within the webapps of the folder.
Code Pro |
---|
mgnl install google-maps-magnolia mgnl-bobby -p /Users/johndoe/dev/mgnl/light-modules/other-users-modules/ |
The following is the minimal folder structure to be recognized by the Magnolia CLI as a Magnolia light module.
Code Pro |
---|
<module-name>/
└── templates/
├── components/
└── pages/ |
If one of these folders is missing, Magnolia CLI refuses to execute create-page
, create-component
and add-availability
.
The Magnolia CLI is under continuous development. Since the video at the top of the page was created there have been subtle enhancements. Note the following differences:
[time: 5:37]
In 2.1.0 the output of the mgnl create-component list -a pages/demo-page
command adds a seventh field to cli-demo/dialogs/components/list.yaml
:
Code Block | ||
---|---|---|
| ||
- name: caption
class: info.magnolia.ui.form.field.definition.TextFieldDefinition
label: Image Caption |
[time: 5:59]
The video has a static value in the alt
attribute of the img
element in cli-demo/templates/components/list.ftl
:
Code Block | ||
---|---|---|
| ||
<img src='${imageLink!}' class='img-responsive' alt='image'> |
compared to the dynamically generated value in v2.1.0:
Code Block | ||
---|---|---|
| ||
<img src='${imageLink!}' class='img-responsive' alt='${content.caption!"image"}'> |
mgnl -help
command is different in v2.1.0....
-c
(--cloud
) has been added to the jumpstart
command. mgnl jumpstart -c
downloads and sets up a Magnolia Cloud bundle. It requires credentials to access Magnolia Nexus.-p
option is set when executing the jumpstart
command, the magnolia.resources.dir
property in the magnolia.properties
file is set to a relative path by default: info magnolia.resources.dir=${magnolia.home}/../../../light-modules
alt
attribute uses the caption
property. NPMCLI-31__lightDevModuleFolder__
for the name of the corresponding light module can be used in all prototypes files for page and component templates (in mgnl-cli-prototypes/page/*
and mgnl-cli-prototypes/component
). NPMCLI-84tab-completion install
command, if completed successfully, will also display the files (together with their paths) to which the autocompletion script has been appended. NPMCLI-107lib/locales/
). The messages in English are located in the en
subfolder. NPMCLI-91Expand | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
...
Version 2.0 of the Magnolia CLI contains many improvements and bugfixes. Here is an incomplete list of the new or changed features:
start
for easy start, stop and logging of Magnolia. NPMCLI-58mgnl tab-completion
.setup
command renamed to customize-local-config
command. NPMCLI-101 add-availability
command defaults to main area when no area is specified. NPMCLI-48create-light-module
command generates README files. NPMCLI-62...
title | Click here for a complete list of the issues which have been resolved in version 2.0 |
---|
...