Create Virtual Uri plugin

A plugin to create a Virtual URI mapping configuration file in a light module. The file is created in the virtualUriMappings directory in the module. The directory is created by the command if it doesn’t exist yet.

Package name

@magnolia/cli-create-light-module-plugin

Repository link

@magnolia/cli-create-virtual-uri-plugin

Latest version

Magnolia CLI create virtual uri plugin - latest version tag

Changelog link

CHANGELOG.md

Prototypes available

  • _default - uses the DefaultVirtualUriMapping class.

  • regexp - uses the RegexpVirtualUriMapping class.

  • empty - doesn’t assign any class by default, you must set it manually.

Installing

The plugin doesn’t come pre-installed with 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-virtual-uri-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 the mgnl.config.js file.

Manually

  1. Run the following command in the project folder.

    npm install @magnolia/cli-create-virtual-uri-plugin

  2. Modify the mgnl.config.js file accordingly.

    import CreateVirtualUriPlugin from "@magnolia/cli-create-virtual-uri-plugin";

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

Usage

Command

create-virtual-uri <name> [options]

Options

Form (short and long) Description

-f <uri>

--from <uri>

Sets the pattern to match in the requested uri. By default, uses an empty string.

-t <prefix:uri>

--to <prefix:uri>

Maps the request to a concrete uri. By default, uses an empty string.

The following action prefixes are supported:

  • redirect:

  • permanent:

  • forward:

-lm [name]

--light-module [name]

Sets a light module for the virtual uri mapping. By default, uses the directory specified in the mgnl.config.js file.

-pd <path>

--prototype-dir <path>

The path to a custom prototype templates directory as the prototype source to create a mapping.

-p [name]

--prototype [name]

A prototype to create a virtual uri mapping.

-v

--version

Displays the version.

-h

--help

Displays help information.

Create mapping examples

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

import CreateVirtualUriPlugin from "@magnolia/cli-create-virtual-uri-plugin";

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

For more information, see Configuring plugins.

Based on the _default prototype

npm run mgnl -- create-virtual-uri "my-vu"

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

npm run mgnl "--" ...

This command creates a new virtual URI mapping called my-vu 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 virtual URI mapping will be created.

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

  • Global

    • lightModulesPath

  • Plugin

    • lightModule

With a fromUri value

npm run mgnl -- create-virtual-uri "my-vu" --from "/foo"

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

npm run mgnl "--" ...

This command creates a new virtual URI mapping called my-vu based on the _default prototype, with /foo as the value for the fromUri property.

The plugin will prompt you to:

  • Choose a directory containing all light modules.

  • Choose a light module directory where the new virtual URI mapping will be created.

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

  • Global

    • lightModulesPath

  • Plugin

    • lightModule

With a toUri value

npm run mgnl -- create-virtual-uri "my-vu" --to "forward:/bar"

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

npm run mgnl "--" ...

This command creates a new virtual URI mapping called my-vu based on the _default prototype, with forward:/bar as the value for the toUri property.

The plugin will prompt you to:

  • Choose a directory containing all light modules.

  • Choose a light module directory where the new virtual URI mapping will be created.

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

  • Global

    • lightModulesPath

  • Plugin

    • lightModule

In a specific light module

npm run mgnl -- create-virtual-uri "my-vu" --light-module "my-lm"

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

npm run mgnl "--" ...

This command creates a new virtual URI mapping called my-vu based on the _default prototype in the my-lm light module.

The plugin will prompt you to choose a directory containing all light modules.

If the my-lm light module doesn’t exist yet in the light modules directory, the plugin will prompt you to select another one.

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

  • Global

    • lightModulesPath

  • Plugin

    • lightModule

Using a specific prototype

npm run mgnl -- create-virtual-uri "my-vu" --prototype "regexp"

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

npm run mgnl "--" ...

This command creates a new virtual URI mapping called my-vu based on the regexp prototype.

The plugin will prompt you to:

  • Choose a directory containing all light modules.

  • Choose a light module directory where the new virtual URI will be created.

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

  • Global

    • lightModulesPath

  • Plugin

    • lightModule

    • prototype

Using a prototype from a custom prototypes directory

npm run mgnl -- create-virtual-uri "my-vu" --prototype-dir "/path/to/custom-prototypes-dir/virtual-uri"

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

npm run mgnl "--" ...

This command creates a new virtual URI mapping called my-vu based on the _default prototype from /path/to/custom-prototypes-dir/virtual-uri.

The plugin will prompt you to:

  • Choose a directory containing all light modules.

  • Choose a light module directory where the new virtual URI will be created.

  • Choose a prototype if the _default prototype isn’t present in the custom prototypes directory.

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/
  └── virtual-uri/
    └── _default/
      └── virtualUriMappings/
        └── {{name}}.yaml
    └── my-first-prototype/
      └── virtualUriMappings/
        └── {{name}}.yaml
    └── my-second-prototype/
      └── virtualUriMappings/
        └── {{name}}.yaml

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

npm run mgnl -- create-virtual-uri "my-vu" --prototype-dir "/path/to/custom-prototypes-dir/virtual-uri" --prototype "my-second-prototype"

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

npm run mgnl "--" ...

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 virtual uri will be created.

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

Plugin properties

Property name Description

lightModule

The name of a light module where the virtual uri 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