Component management with components.js

components.js is a flexible approach for defining, customizing, and managing components available in the elements panel of eWizard Editor. With it, you can register your components globally for further use in content items and control which components are shown or hidden, apply custom styles, define attributes, etc.

Using components.js, you can:

• Define custom attributes for components
• Set component properties
• Add custom styles to components
• Hide components from the sidebar
• Use custom templates for adding components to content layout
• Add icons for components in the sidebar
• Set component names displayed in the sidebar
• Extend ewizardConfig with additional options

Version requirement

To use components.js ensure your toolset is up-to-date:

• eWizard.js 5.25.0 and later

• eWizard CLI 0.37.0 and later

Basic usage

1. Create a components.js file under the /components/ folder:

<content-item-name>/common/components/components.js

2.Add the default export to components.js:

export default function () {
    return [];
}

3. Define components.
   Each component is an object in components.js. Consider the following:
   • The name and component fields are mandatory
   • The component value must be a valid component type

Here’s an example components.js file:

import wizText from "my-text-component";

export default function () {
    return [
        {
            name: "my-text-component",
            component: wizText,
            attrs: {
                text: "Hello World",
                style: "color: red; font-size: 20px;"
            },
            ewizardConfig: {
                icon: require("my-text-component/icon.png"),
                label: {
                    eng: "My header text"
                },
                name: "my-header-text",
                templatePath: "/templates/my-header.html",
            },
        }
    ];
}

Field	Description	Type
name	Your component's name. Must match the component subdirectory name. You can register several component with the same name, for example, to add different styles to each instance.	String
component	An imported component. The value must match the imported object.	Enum
attrs	Optional attributes of your component. Applied to the component when it's dragged from the Components tab to the layout in eWizard Editor.	Object
ewizardConfig	A configuration object with defined properties to control your component behavior and visual representation in eWizard Editor. Must share the same defined fields as the component's ewizard.config.js configuration.	Object
showInComponentsTab	Component visibility in eWizard Editor's Components tab.	Boolean

4. Build and test:
   • Use wiz-archive or wiz-dev to build or bundle your content item.
   • Upload the content item to eWizard Library and open it in Editor to check if the components appear.

Advanced features

The same component can have different attributes, styles, icons, or templates. This allows you to create variations for specific use cases:

import wizImage from "wiz-image";
import wizText from "wiz-text";

export default function () {
    return [
        {
            name: "wiz-text",
            component: wizText,
            attrs: {
                text: 'Header',
                style: `
                  font-family: 'Dancing Script';
                  text-align: center;
                  font-size: 44px;
                `
            },
            ewizardConfig: {
                icon: require('wiz-text/icon.png'),
                label: {
                    eng: '[Components.js] wiz-text #1',
                },
                name: 'header',
                showInComponentsTab: false
            },
        },
        {
            name: "wiz-text",
            component: wizText,
            attrs: {
                style: `
                    border: none;
                    background-color: #63abea;
                    `
            },
            ewizardConfig: {
                icon: require('wiz-text/icon.png'),
                label: {
                    eng: '[Components.js] Sub header',
                },
                name: 'ub-header',
                id: 'wt4',
            }
        },
        {
            name: "wiz-text",
            component: wizText,
            attrs: {
                style: `color: #ffffff;`
            },
            ewizardConfig: {
                icon: require('./custom-text/icon.png'),
                label: {
                    eng: '[Components.js] CUSTOM wiz-text',
                },
                name: '& wiz &',
                id: 'wt2',
                templatePath: './custom-text/ewizard.template.vue',
            }
        },
        {
            name: "wiz-text",
            component: wizText,
            attrs: {
                text: 'Lorem ipsum',
            },
            ewizardConfig: {
                icon: require('./custom-text-2/icon.png'),
                label: {
                    eng: '[Components.js] Paragraph',
                },
                name: '& wiz &',
                id: 'wt3',
                templatePath: './custom-text-2/ewizard.template.vue',
            }
        },
    ];
}

In this example, the same wiz-text component is registered with different attributes and configurations: a header, subheader, and two paragraphs.

Registered component

In the example above, eWizard will register the first component only. However, in the eWizard Editor all the variations will be available for use.

Add custom templates

To create custom templates for components, define a .template.vue template file. The file name must follow this pattern: my-component.template.vue:

<!-- my-component.template.vue -->

<template>
    <wiz-container
            id="container"
            elementType=""
    >
        <wiz-text
                id="text"
                text="Hello world!"
        ></wiz-text>
    </wiz-container>
</template>

In components.js, link the template using the templatePath property:

{
   name: "wiz-text",
   component: wizText,
   ewizardConfig: {
       ...
       templatePath: "./templates/my-custom-template.template.vue"
    }
}

Group components for eWizard Editor

To improve navigation, especially in templates with numerous components, eWizard Editor supports component grouping. This feature requires implementation within your content item template.

To implement component groups:

1. Define a group constant.
   In components.js, define a constant (e.g. emailGroups) to store your group configurations.
2. Add group identifiers.
   Use the keys of this constant as unique identifiers for each group.
3. Define group data.
   The values associated with each key must contain the required group data like group's display name and description.
4. Map components to the groups.
   Add a group property to each component definition in your components.js. The value of this property must correspond to group identifiers you defined in emailGroups.

For example,

const emailGroups = {
    text: {
        label: 'Text',
        description: 'Text components',
    },
    assets: {
        label: 'Media',
        description: 'Media components',
    },
    interactive: {
        label: 'Others',
        description: 'Interactive components',
    },
};

export default function () {
    return [
        // ....
        {
            name: 'wiz-image',
            component: WizImage,
            showInComponentsTab: true,
            group: emailGroups.assets,
            ...
        },
    ]
    //...
}

With this configuration, your template in eWizard Editor will display components grouped according to your definitions.