This page describes how you can use and define a prototype variant in Magnolia CLI v3 to create a new block, component, light module, page and virtual URI definition.
Prototypes and prototype variants
Magnolia CLI v3 comes with the following prototypes:
- Light module
- Virtual URI
Each of these prototypes comes in two or three pre-configured variants one of which is applied when executing a create command. The variants speed up the creation of a light module or its components. You can tweak each of the variants according to your needs or even create your own variants. They are stored in the
mgnl-cli-prototypes folder of your Magnolia CLI installation. Please be aware that the installation can reflect either a local or a global configuration, see Global and local configurations for more information.
Upon a clean installation of CLI v3 the folder has the following structure:
The level 2 directory names in the prototypes folder correspond with the following prototypes variants. You can refer to a variant by the name attached to the
-P option in the create commands:
_default– To create a default structure for the given element. Same as not specifying a prototype variant at all. If you use this variant to create a virtual URI mapping configuration, the URI mapping is based on the
empty– To create a minimalistic structure of the element. If you use this variant to create a virtual URI mapping configuration, no URI mapping class is specified in the configuration.
regexp– To create a virtual URI mapping configuration based on the
comprehensive– To create a light module with the most complete (=comprehensive) structure. The following structure is created when issuing the
mgnl create-light-module fooModule -P comprehensivecommand:Click here to expand...
Without specifying the prototype or, alternatively, by adding
-P _default, the structure looks like this:Click here to expand...
For comparison, see the light module structure created with the
mgnl create-light-module fooModulecommand in Magnolia CLI v2:Click here to expand...
Prototype variant root folder
The root folder of a prototype variant is like the root folder of a light module folder. Whatever is added into the root of a prototype variant folder is added also to the corresponding level(s) of the light module folder when you execute a specific create command. You can add custom files to prototype variants according to your needs (see the example below).
Placeholder variables in prototype files
In a prototype variant and even in its filename you can use the following placeholder variables:
__lightDevModuleFolder__Replaced with the name of the current light module.
__dialog__Replaced with the dialog definition ID (see referencing dialogs).
__fromUri__Replaced with the name of the
fromUriconfiguration in a virtual URI mapping.
__toUri__Replaced with the name of the
toUriconfiguration in a virtual URI mapping.
__template__Replaced with the template definition ID in block, page and component prototypes (see referencing templates).
__templateScript__Replaced with the name and path of a template script.
__name__Replaced with the name of the item being generated, for instance the name of a page template.
The stock Magnolia page template prototype variant called
with-js-modelcontains also a pre-configured prototype file
__name__.js. The prototype file has the following content (the multiline comment at the beginning was removed intentionally):
After executing, for example, the command
mgnl create-page visitor-counter -P with-js-model, the prototype file is used to create a new file called
visitor-counter.jsin the page template folder of your light module. The newly created file has the following content:
Notice the change happening at lines 1 and 20: using the
__modelName__variable in the prototype file takes the name
visitor-counterfrom the create command and turns it to UpperCamelCase when creating the target file.
Using prototype variants
A prototype variant is applied any time you use one of the following CLI commands:
Listing the available variants
The variants that are available for use with a create command can be listed via the
help command, for example:
In the stock installation of Magnolia CLI v3, the command lists these three variants:
with-js-model. If you create a new variant and attach it to a given prototype, the new variant also appears in the output of the
Applying a variant
To create a new item from a prototype variant, use a create comand and append
--prototype) followed by the name of a variant. For example:
This command wil create a page template from the
empty page prototype variant.
If you do not specify a prototype variant, or, alternatively, if you append
-P _default to a create command, Magnolia CLI applies the
_default prototype variant and creates the item from the
_default subdirectory of the given item in the
mgnl-cli-prototypes folder. The output of the following two example commands is then the same.
Creating a custom variant
You can create a custom prototype variant and add it to one of the five prototypes to create a new block, component, light module, page or a virtual URI configuration. The short tutorial below shows how to create a new page prototype variant called
- Is based on the
emptyvariant provided by Magnolia.
- Uses the word Welcome as a
h1header on the page.
- Has the header styled by a stylesheet (CSS) file and the stylesheet linked to the template script via two CLI variables.
Remember that the root folder of a prototype variant is like the root folder of a light-module folder. Whatever is added into the root a prototype variant folder is added to the corresponding levels of the light module folder when you execute the specific create command.
Example: Front-Page variant
To create the
Front-Page prototype variant:
mgnl-cli-prototypesfolder, go to the
pagefolder and make a copy of the existing
emptysubfolder in it.
Rename the copy to
webresources/csssubdirectory in it. Switch to the
csssubdirectory and create a new file called
In bash shell you can use the following command for this step:
__name__.cssfile to have the following content:
Save the stylesheet file. The content of the
pagefolder now looks like this:Click here to expand...
../Front-Page/templates/pages/__name__.ftlfile for editing and save it with the following content:
Line 4: The link to the style definition of your
Front-Pagetemplate. There are two CLI variables in the link that make sure the style definition is linked correctly with your page:
__lightDevModuleFolder__variable in the path generates a part of the path to the light module in which you create the page.
__name__variable generates a matching name for the stylesheet file.
Line 7: The element that displays the
h1header on your page.
Now, the next series of steps shows how to create a new page tempate based on the
Front-Page prototype variant.
- Go to the light module in which you want to create a page from the new
Front-Pageprototype variant. You may create it in a new light module, see the
create-light-modulecommand for creating light module templates.
You may also check that the
Front-Pagevariant is available for the
create-pagecommand. Do that by entering:
In the output of the command you should find a line showing the availability of the
Finally, create a page template by entering the following command:
webresources/cssfolders of the light module now have new template files created from the
If you keep your light module in the directory observed by the magnolia.resources.dir property, the new page template and any subseqent changes to it are picked up by Magnolia instantly. The template is available under the name
indexin the Pages app. A new page based on the this template should look as follows in the app:
You may now modify the page template by specifying areas in it and allowing components in them.