Important

You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get the updated information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Create Editor Components

Hint

GrapesJS component description is available in the GrapesJS documentation, as well as the way of creating component types.

To simplify adding new types of component there, component type builders were created that include all needed data of a new component type. Under the hood, they implement the same actions that are propose in the GrapesJS documentation but make component type declaration more structured and convenient.

Type Builder

To create your own component type, first create a descendant of BaseTypeBuilder:

import BaseTypeBuilder from 'orocms/js/app/grapesjs/type-builders/base-type-builder';

const SomeNewComponent = BaseTypeBuilder.extend({
    button: {
        label: 'Button label',
        category: 'Basic',
        attributes: {
            'class': 'fa fa-hand-pointer-o'
        }
    },

    modelMixin: {
        defaults: {
            classes: ['component-class', 'some-class'],
            tagName: 'span',
            content: 'Inner content'
        },

        someMethod() {
            // Some custom logic
        }
    },

    viewMixin: {
        onRender() {
            // Some custom logic
        }
    },

    editorEvents: {
        'component:create': 'onCreate',
        'prevent component:selected': 'onSelect'
    },

    commands: {
        'my-command': () => {
            // Some custom logic
        }
    },

    usedTags: ['div', 'span'],

    constructor: function SomeNewComponent(options) {
        SomeNewComponent.__super__.constructor.call(this, options);
    },

    onInit() {
        this.editor.runCommand('my-command');
    },

    onCreate() {
        // Some custom logic
    },

    onSelect() {
        // Some custom logic
    },

    isComponent(el) {
        let result = null;

        if (el.tagName === 'sometag') {
            result = {
                type: this.componentType
            };
        }

        return result;
    }
});

export default SomeNewComponent;

Properties

componentType String The name of a new component type
parentType String The name of the component type that used as a parent. If it is not determined, use the default type
editor Object An instance of GrapesJS WYSIWYG
button Object Data to register a panel button (if required for the new component type)
label String The button label
category String Place the button to the category container
attributes Object An object of the attributes such as class name or data attribute
modelMixin Object Methods and props used to extend the WYSIWYG component model. Prop defaults is merged with the default model attributes.
viewMixin Object Methods and props used to extend the WYSIWYG component view
isComponent Function Identify the the component type
onInit Function Call after the component is initialized
commands Object The key is the command name and the value is the command callback
editorEvents Object The key is the event name and the value is the name of the builder method
template HTML Set the component template; if the template is not set, the button will use its own component type as content.
getButtonTemplateData Function Return data for the button template

Component Type Registration

Register the created type builder in the component manager:

import ComponentManager from 'orocms/js/app/grapesjs/plugins/components/component-manager';
import SomeTypeBuilder from 'orocms/js/app/grapesjs/type-builders/some-type-builder';

ComponentManager.registerComponentTypes({
    'some': {
        Constructor: SomeTypeBuilder
    }
});

The best way to create an appmodule is to make sure that the builder is registered before the application starts.