Multi-layout templates

Real-life use cases

See real-life use cases for multi-layout templates with dynamic themes.

With eWizard.js, you can create master templates that support multiple content item layouts. Each layout functions as a distinct template with its theme, blocks, and components. To implement a multiple-layout template, organize each layout in a dedicated directory within the ./layouts folder of your master template.

.
├─layouts/
|  ├─invitation/
|  └─follow-up/

You can rename the ./layouts directory or customize the path to specific layouts. See template path customization.

Working with layouts

To build your project with a specific layout, use the --layout flag with your required layout name:

wiz dev --layout invitation

To view the result, open the ./index.html file in your browser. Your content item display will contain the specified theme, blocks, and components.

Live reload options

For live reload, use the wiz dev --live or wiz dev --watch options. For example, run

wiz dev --live --layout invitation

This command builds your content item with invitation and starts a local server on http://localhost:3000/ with live reload.

To create ZIP package with a specific layout, run:

wiz archive --layout invitation

This generates a invitation.zip file in your project's root directory.

Specify all the required layout names to create packages for multiple layouts with one command:

wiz archive --layout invitation follow-up

This creates individual ZIP files for every layout you provide.

Read more about the wiz dev --layout and wiz archive --layout eWizard CLI commands.

Template path modification

You can modify both the name of the layouts directory and the paths to specific layouts that you build with wiz dev --layout or wiz archive --layout.

For this, do the following:

1. Go to ./.ewizard/settings.json in your multiple-layout template.

2. Set the desired name for the layouts directory using the layouts key:

// ./ewizard/settings.json
{
  "path": {
    "layouts": "campaign"
  }
}

In this example, layouts will be stored under the ./campaign directory instead of ./layouts

Alternatively, you can define deeper paths for organizing the layouts hierarchically:

// ./ewizard/settings.json
{
  "path": {
    "layouts": "campaign/breathe-easy/invitation"
  }
}

Layout root container for nested paths

When specifying nested paths, the first directory (/campaign/ in this example) represents the root container for all layouts.

Defining a path to layouts with wiz archive creates packages for all layouts located in the specified path. To exclude unwanted layouts, add their parent directory to the ignore array in ./ewizard/settings.json of your master template, while providing the location of the required layout under the path array:

{
    "path": {
      "layouts": "campaign/breathe-easy/invitation"
    },
    // Other settings
    "archive": {
        "ignore": [
          "campaign"
        ]
      }
}

In this example, running wiz archive generates a package for the /breathe-easy/invitation layout only. The rest of the layouts in the campaign folder won't be archived.

Build a template with specific layouts and themes

To build a project with a specific layout and theme, ensure the ./layouts/your-layout-name directory follows this structure:

.
├─.ewizard/
├─common/
|  └─blocks-library/
|     ├─blocks.json
|     └─blocks-themes.json
├─themes/
|  ├─current-theme/
|  └─themes.json
├─App.vue
├─package.json
└─settings.json

Key configuration files

• Theme directory:
  • The current-theme directory must match the name specified in the theme.current field in ./settings.json.
• Block definitions:
  • List the IDs of blocks to be used in the current theme in ./layouts/your-layout-name/common/blocks-library/blocks.json.

  // ./layouts/your-layout-name/common/blocks-library/blocks.json    
  {
    "components": [
      { "id": "header-capitalized" },
      { "id": "header-in-sentence-case" }
    ]
  }

• Theme-specific block configuration:
  • In ./layouts/your-layout-name/common/blocks-library/blocks-themes.json, configure block appearance in eWizard Editor.

// ./layouts/your-layout-name/common/blocks-library/blocks-themes.json

{
  "themes": {
    "aethercare": {
      "blocks": [
        {
          "id": "header-capitalized",
          "name": "Header capitalized",
          "icon": {
            "icon": "themes/aethercare/blocks-icons/header-capitalized/icon-aethercare-invitation-ukraine-ukr.png"
          }
        },
        {
          "id": "header-in-sentence-case",
          "name": "Header in sentence case",
          "icon": {
            "icon": "themes/aethercare/blocks-icons/header-in-sentence-case/icon-aethercare-follow-up-ukraine-ukr.png"
          }
        }
      ]
    }
  }
}

• Theme availability
  • Define theme metadata and brand dependencies in ./layouts/your-layout-name/themes/themes.json for the ADD NEW popup in eWizard Library.

// ./layouts/your-layout-name/themes/themes.json

{
    "themes": [
      {
        "id": "aethercare",
        "name": "AetherCare",
        "dependencies": {
          "brand": ["aethercare-brand"]
        }
      }
    ]
  }

Current-theme build

As a shorthand to build a project with the theme defined under the /themes/current/ theme, run wiz archive as follows:

wiz archive --layout [LAYOUT_NAME] --current-theme

Building layouts with a specific layout and theme optimizes the resulting archive size by including only the necessary blocks for the specified layout and theme.