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

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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

Manually

  1. Run the following command in the project folder.

    npm install @magnolia/cli-create-block-plugin

  2. 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

-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"

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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"

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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"

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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"

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

Create a new block based on a specific prototype

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

Windows users using PowerShell must enclose the two consecutive hyphens (--) in quotes:

npm run mgnl "--" ...

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

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

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.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia CLI docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules