Cli Create Page Plugin

This plugin creates a new page based on templates provided from available npm packages:

• @magnolia/cli-freemarker-prototypes
• @magnolia/cli-angular-prototypes
• @magnolia/cli-react-prototypes
• @magnolia/cli-vue-prototypes

Installation

Install plugin via npm:

npm i @magnolia/cli-create-page

Add CreatePagePlugin to mgnl.config.js file:

import CreatePagePlugin from "@magnolia/cli-create-page";

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

Usage

npm run mgnl create-page -- <name> [options]

Command-line parameter

• <name>, The name of the new page, required

Command-line options

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

• -lm, --light-module <name>, set the light module for the page template; defaults to the directory specified in mgnl.config.js file
• -P, --prototype [prototype], select a prototype for page creation

Options that can be set in mgnl.config.js file:

• type, lightModulePath, componentMappingFilePath are shared between 'CreateComponentPlugin' and 'CreatePagePlugin'
• pagesSpaPath, framework, prototype, templateData, templateArgs are for 'CreatePagePlugin' only

import CreatePagePlugin from "@magnolia/cli-create-page";

export default {
  type: 'ts',
  lightModulesPath: './magnolia/light-modules',
  lightModule: 'spa-lm',
  componentMappingFilePath: './spa/react-minimal/src/magnolia.config.js',
  
  commands: [
    new CreatePagePlugin({
      pagesSpaPath: './spa/react-minimal/src/pages',
      framework: '@magnolia/cli-react-prototypes',
      prototype: "_default",
      templateData: {
        // {{customName}} in .hbs file
        customName: "customValue"
      },
      templateArgs: {
        // Use default light module template from cli-create-page-template if page template doesn't have any, default true
        useDefaultLightModuleTemplate: true,
        // For headless only:
        /*
         * Remove extension from import string, default false:
         *  - true => import { pageName } from ./path/to/page;
         *  - false => import { pageName } from ./path/to/page.js;
         */
        removeExtension: false,
        /*
         * Use named import, default false:
         *  - true => import { pageName } from ./path/to/page;
         *  - false => import pageName from ./path/to/page;
         */
        namedImport: true,
        /*
         * Specify the file to use for imports when multiple files in template exist, it selects based on the following logic:
         * 1. Single file: Directly use it.
         * 2. Multiple files: Prefers 'index' prefixed, then page-named file ({{name}}). If neither is uniquely identifiable, manual specification is required.
         * Example structure and import behavior:
         * /tsx
         * |--/index.tsx (default import)
         * |--/{{name}}.tsx
         * |--/{{name}}.stories.tsx
         * |--/{{name}}.model.tsx
         *
         * - not set => import pageName from ./path/to/index.tsx;
         * - '{{name}}.tsx' => import pageName from ./path/to/{{name}}.tsx;
         */
        importSource: '{{name}}.tsx'
      }
    })
  ]
};

Example

Examples are shown in a headless/minimal-headless-spa-demos/dx-core/latest project.

Download with:

npx @magnolia/cli@preview jumpstart -t headless/minimal-headless-spa-demos/dx-core/latest

Install CreatePagePlugin

npm i @magnolia/cli-create-page

Add to mgnl.config.js

import CreatePagePlugin from "@magnolia/cli-create-page";

export default {
  type: 'js',
  lightModulesPath: './magnolia/light-modules',
  lightModule: 'spa-lm',
  componentMappingFilePath: './spa/react-minimal/src/magnolia.config.js',
  
  logger: {
    filename: "./mgnl.error.log",
    fileLevel: "warn",
    consoleLevel: "debug"
  },
  commands: [
    new CreatePagePlugin({
      pagesSpaPath: './spa/react-minimal/src/pages',
      framework: '@magnolia/cli-react-prototypes',
      prototype: '_default',
      templateArgs: {
        removeExtension: true
      }
    })
  ]
};

Example 1: Create page with @magnolia/cli-react-prototypes stored in npx repository

Run:

npm run mgnl -- create-page About

Will create following files:

• /PATH/TO/PROJECT/magnolia/light-modules/spa-lm/dialogs/pages/About.yaml

  label: Page Properties
  form:
    properties:
      title:
        label: Title
        $type: textField
        i18n: true

• /PATH/TO/PROJECT/magnolia/light-modules/spa-lm/templates/pages/About.yaml

  renderType: spa
  class: info.magnolia.rendering.spa.renderer.SpaRenderableDefinition
    
  title: About
  dialog: spa-lm:pages/About
  baseUrl: http://localhost:3000
  routeTemplate: '/{language}{{@path}}'
  # templateScript: /spa-lm/webresources/build/index.html
    
  areas:
    main:
      title: Main Area
    
    extras:
      title: Extras Area

• /PATH/TO/PROJECT/spa/react-minimal/src/pages/About.js

  import React from 'react';
  import { EditableArea } from '@magnolia/react-editor';
    
  const About = props => {
    const { main, extras, title } = props;
    
    return (
      <div className="About">
        <div>[Basic Page]</div>
        <h1>{title || props.metadata['@name']}</h1>
    
        <main>
          <div>[Main Area]</div>
          {main && <EditableArea className="Area" content={main} />}
        </main>
    
        <div>
          <div>[Secondary Area]</div>
          {extras && <EditableArea className="Area" content={extras} />}
        </div>
      </div>
    )
  };
    
  export default About;

Will modify following file:

• /PATH/TO/PROJECT/spa/react-minimal/src/magnolia.config.js

  import AboutPage from './pages/About'
  import Basic from './pages/Basic';
  import Contact from './pages/Contact';
  import Headline from './components/Headline';
  import Image from './components/Image';
  import Paragraph from './components/Paragraph';
  import Expander from './components/Expander';
  import List from './components/List';
  import Item from './components/Item';
  import Personalization from './pages/Personalization';
  
  const config = {
    'componentMappings': {
      'react-minimal-lm:pages/basic': Basic,
      'react-minimal-lm:pages/contact': Contact,
      'react-minimal-lm:pages/personalization': Personalization,
  
      'react-minimal-lm:pages/basic-autogeneration': Basic,
      'react-minimal-lm:pages/contact-inheritance': Contact,
  
      'spa-lm:components/headline': Headline,
      'spa-lm:components/image': Image,
      'spa-lm:components/paragraph': Paragraph,
      'spa-lm:components/expander': Expander,
      'spa-lm:components/list': List,
      'spa-lm:components/listItem': Item,
      'spa-lm:pages/About': AboutPage
    }
  };
  
  export default config;

Example 2: Create page with locally cloned @magnolia/cli-react-prototypes

Clone: cli-react-prototypes

Change framework in mgnl.config.js:

import CreatePagePlugin from "@magnolia/cli-create-page";

export default {
  ...
  commands: [
    new CreatePagePlugin({
      pagesSpaPath: './spa/react-minimal/src/pages',
      framework: '/Path/To/Cloned/cli-react-prototypes',
      prototype: '_default',
      templateArgs: {
        removeExtension: true
      }
    })
  ]
};

Run:

npm run mgnl -- create-page About

Will behave like Example 1, but use the local 'pages' folder.