Create Block plugin

A plugin to create a block in a light module.

Package name

@magnolia/cli-create-block-plugin

Repository link

@magnolia/cli-create-block-plugin

Latest version

Magnolia CLI create block plugin - latest version tag

Changelog link

CHANGELOG.md

Prototypes available

_default: contains a dialog and template with examples of properties used most often.
empty: contains an empty dialog and template.

Installing

The plugin doesn’t come pre-installed with the Magnolia CLI. You must add it to the mgnl.config.js project file.

The plugin is installed automatically by the Jumpstart plugin if it is defined in a project template.

With add-plugin

Run the following command in the project folder.

npm run mgnl -- add-plugin @magnolia/cli-create-block-plugin

The command automatically downloads, installs, and registers the plugin in mgnl.config.js.

Manually

Run the following command in the project folder.
```
npm install @magnolia/cli-create-block-plugin
```

Modify the mgnl.config.js file accordingly.

import CreateBlockPlugin from "@magnolia/cli-create-block-plugin";

export default {
  plugins: [
    new CreateBlockPlugin()
  ]
};

Usage

Command

create-block <name> [options]

Options

Form (short and long) Description

Form (short and long)	Description
`-lm [name]` `--light-module [name]`	Sets the light module for the block. By default, uses the directory specified in the `mgnl.config.js` file.
`-pd <path>` `--prototype-dir <path>`	Use a path to the custom prototype templates directory as the prototype source for block creation.
`-p [name]` `--prototype [name]`	Selects a prototype for block creation.
`-v` `--version`	Displays the version.
`-h` `--help`	Displays help information.

-lm [name]

--light-module [name]

Sets the light module for the block. By default, uses the directory specified in the mgnl.config.js file.

-pd <path>

--prototype-dir <path>

Use a path to the custom prototype templates directory as the prototype source for block creation.

-p [name]

--prototype [name]

Selects a prototype for block creation.

-v

--version

Displays the version.

-h

--help

Displays help information.

Examples

In the following examples, assume that the mgnl.config.js file looks like this:

import CreateBlockPlugin from "@magnolia/cli-create-block-plugin";

export default {
  plugins: [
    new CreateBlockPlugin()
  ]
};

For more information, see Configuring plugins.

Create a new block

npm run mgnl -- create-block "my-block"

This command creates a new block called my-block based on the _default prototype.

The plugin will prompt you to:

Choose a directory containing all light modules.
Choose a light module directory where the new block will be created.

The plugin writes the following properties to the mgnl.config.js file:

Global
- lightModulesPath
Plugin
- lightModule

Create a new block in a specific light module

npm run mgnl -- create-block "my-block" --light-module "my-lm"

The command creates a new block called my-block based on the _default prototype in the my-lm light module.

The plugin prompts you to choose a directory containing all light modules. If the my-lm light module doesn’t exist in the light modules directory, the plugin prompts you to select another one.

The plugin writes the following properties to the mgnl.config.js file:

Global
- lightModulesPath
Plugin
- lightModule

Create a new block based on a prototype from a custom prototypes directory

npm run mgnl -- create-block "my-block" --prototype-dir "/path/to/custom-prototypes-dir/block"

This command creates a new block called my-block based on the _default prototype from /path/to/custom-prototypes-dir/block.

The plugin will prompt you to:

Choose a directory containing all light modules.
Choose a light module directory where the new block will be created.

If the _default prototype is not present in the custom prototypes directory, it prompts you to choose another prototype.

The plugin writes the following properties to the mgnl.config.js file:

Global
- lightModulesPath
Plugin
- lightModule
- prototypeDir
- prototype

The structure of the custom prototypes directory can be:

custom-prototypes-dir/
  └── block/
    └── _default/
      └── blocks/
        └── {{name}}.yaml
      └── templates/
        └── blocks/
          └── {{name}}.ftl
          └── {{name}}.yaml
    └── my-first-prototype/
      └── blocks/
        └── {{name}}.yaml
      └── templates/
        └── blocks/
          └── {{name}}.ftl
          └── {{name}}.yaml
    └── my-second-prototype/
      └── blocks/
        └── {{name}}.yaml
      └── templates/
        └── blocks
          └── {{name}}.ftl
          └── {{name}}.yaml

To use the custom my-second-prototype, run:

npm run mgnl -- create-block "my-block" --prototype-dir "/path/to/custom-prototypes-dir/block" --prototype "my-second-prototype"

Create a new block based on a specific prototype

npm run mgnl -- create-block "my-block" --prototype "empty"

The command creates a new block called my-block based on the empty prototype.

The plugin will prompt you to:

Choose a directory containing all light modules.
Choose a light module directory where the new block will be created.

The Create Block plugin contains the _default and "empty" prototypes. To choose a custom prototype from a custom prototypes directory, use the --prototype with --prototype-dir option.

The plugin writes the following properties to the mgnl.config.js file:

Global
- lightModulesPath
Plugin
- lightModule
- prototype

Configuration

You can set the following properties in mgnl.config.js to predefine the plugin’s behavior.

Global properties

Property name Description

Property name	Description
`lightModulesPath`	The path to a directory containing all light modules.
`lightModule`	The name of a light module where the block will be created. Alternative forms: `-lm [name]`, `--light-module [name]`

lightModulesPath

The path to a directory containing all light modules.

lightModule

The name of a light module where the block will be created.

Alternative forms: -lm [name], --light-module [name]

Plugin properties

Property name Description

Property name	Description
`lightModule`	The name of a light module where the block will be created. Alternative forms: `-lm [name]`, `--light-module [name]`
`prototypeDir`	The path to a custom prototypes directory. Alternative forms: `-pd <path>, --prototype-dir <path>`
`prototype`	The name of a prototype. Alternative forms: `-p [name]`, `--prototype [name]`

lightModule

The name of a light module where the block will be created.

Alternative forms: -lm [name], --light-module [name]

prototypeDir

The path to a custom prototypes directory.

Alternative forms: -pd <path>, --prototype-dir <path>

prototype

The name of a prototype.

Alternative forms: -p [name], --prototype [name]

For more information, see Configuring plugins.

Create Block plugin

Installing

With add-plugin

Manually

Usage

Command

Options

Examples

Create a new block

Create a new block in a specific light module

Create a new block based on a prototype from a custom prototypes directory

Create a new block based on a specific prototype

Configuration

Global properties

Plugin properties

Location

Main doc sections