@magnolia/cli-create-virtual-uri v1.0.0-preview

CLI Create Virtual Uri Plugin

NOTE: This version of the Create Virtual Uri plugin is still under development. The README will be updated continuously as we refine the plugin.

The Create Virtual Uri Plugin is a part of the Magnolia CLI's plugin system. The command creates a virtual URI mapping configuration file (a YAML definition file) in the light module. The command succeeds only if the current directory (or the directory defined by the -lmp option) is a light module with a minimal folder structure. The file with a mapping is created in the virtualUriMappings folder. The folder is created by the command if it does not exist yet. The file created while executing this command is based on the files in the prototypes folder of your configuration.

Installation

Install plugin via npm:

npm i @magnolia/cli-create-virtual-uri

Add CreateVirtualUriPlugin to mgnl.config.js file:

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

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

Usage

npm run mgnl create-virtual-uri -- <virtualUriName> [options]

Command-line parameter

• <virtualUriName>, The name of the new URI configuration, required

Command-line options

You can customize the create-virtual-uri plugin's actions using these command-line options:

• -lmp, --light-module-path <path>, The path to the light module
• -f, --fromUri <uri>, The pattern to be matched in the requested URI. Enclose the value in quotes.
• -t, --toUri <prefix:uri>, A concrete URI that the request is mapped to. Enclose the <prefix:uri> value in quotes.
• -P, --prototype <prototype>, The name of the prototype variant to create the mapping.
  • If neither --prototype nor --prototypeDir is specified, the '_default' prototype from the default prototype directory is automatically used.
  • If --prototype is specified without --prototypeDir, the chosen prototype must be one of the following from the default prototype directory: '_default', 'regexp', or 'empty'.
  • If --prototypeDir is specified without --prototype, the plugin searches for a '_default' prototype within the specified custom prototype directory.
  • If both --prototypeDir and --prototype are specified, the chosen prototype must be located within the custom prototype directory specified by --prototypeDir.
• -pd, --prototypeDir <path>, Sets the path to a custom prototype directory. This overrides the use of the default prototype directory. When specified, available prototypes are looked up in this directory.

Available Prototypes

1) Default Prototypes

• Following prototypes are available: _default, regexp and empty.
  • The _default variant uses the DefaultVirtualUriMapping class.
  • The regexp variant uses the RegexpVirtualUriMapping class.
  • The empty variant does not assign any default class. Requires manual specification of the class to use.

2) Overriding the Default Prototypes Directory

• Custom prototype directory structure:

  /myCustomTemplates
  |-- /virtual-uri
  |   |-- /myTemplate
  |   |-- |-- /__name__.yaml

  1) Using command line option
  • Use --prototypeDir <path> to specify a custom directory
  • Example:

     ```bash
     npm run mgnl create-virtual-uri -- myMapping --prototypeDir '/Path/to/myCustomTemplates'
     ```

    2) Using constructor argument - If custom prototypes are frequently used, pass the directory path directly to the constructor. - Example:

      ```js
      import CreateVirtualUriPlugin from "@magnolia/cli-create-virtual-uri";
      
      export default {
        commands: [
          new CreateVirtualUriPlugin({prototypeDir: '/Path/to/myCustomTemplates'})
        ]
      };
      ```

• Note: The --prototypeDir option takes the highest priority.

Example

1) Create virtual uri using the default template

In a light module, eg:
```
/my-light-module
|-- /templates
|   |-- /componenets
|   |-- /pages
```

Run following command:
```bash
npm run mgnl create-virtual-uri -- myMapping 
```

Which will create:
```
/my-light-module
|-- /templates
|   |-- /componenets
|   |-- /pages
|-- /virtualUriMappings
|   |-- /myMapping.yaml
```

myMapping.yaml:
```yaml
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
fromUri: 
toUri:
```

2) Create virtual uri using the default template with specified from and to options

In a light module, eg:
```
/my-light-module
|-- /templates
|   |-- /componenets
|   |-- /pages
```

Run following command:
```bash
npm run mgnl create-virtual-uri -- myFooMapping --fromUri '/foo' --toUri 'forward:/bar' 
```

Which will create:
```
/my-light-module
|-- /templates
|   |-- /componenets
|   |-- /pages
|-- /virtualUriMappings
|   |-- /myFooMapping.yaml
```

myFooMapping.yaml:
```yaml
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
fromUri: /foo
toUri: forward:/bar
```