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 -p 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.
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()
]
};
npm run mgnl create-virtual-uri -- <virtualUriName> [options]
-
<virtualUriName>
, The name of the new URI configuration, required
You can customize the create-virtual-uri plugin's actions using these command-line options:
-
-p, --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.
- If neither
-
-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.
- 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.
- Overriding the Default Prototypes Directory
- Custom prototype directory structure:
/myCustomTemplates |-- /virtual-uri | |-- /myTemplate | |-- |-- /__name__.yaml
- Using command line option
- Use
--prototypeDir <path>
to specify a custom directory - Example:
npm run mgnl create-virtual-uri -- myMapping --prototypeDir '/Path/to/myCustomTemplates'
- Use
- Using constructor argument
- If custom prototypes are frequently used, pass the directory path directly to the constructor.
- Example:
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.
- Custom prototype directory structure:
-
Create virtual uri using the default template
In a light module, eg:
/my-light-module |-- /templates | |-- /componenets | |-- /pages
Run following command:
npm run mgnl create-virtual-uri -- myMapping
Which will create:
/my-light-module |-- /templates | |-- /componenets | |-- /pages |-- /virtualUriMappings | |-- /myMapping.yaml
myMapping.yaml:
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping fromUri: toUri:
-
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:
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:
class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping fromUri: /foo toUri: forward:/bar