Important

You are browsing upcoming documentation for version 6.1 of OroCommerce, scheduled for release in 2025. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date 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.

Creating Type In Single Module

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

src/{YourBundleName}/Resources/js/app/grapesjs/types/some-type.js

import BaseType from 'orocms/js/app/grapesjs/types/base-type';

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

    modelProps: {
        defaults: {
            classes: ['component-class', 'some-class'],
            tagName: 'span'
        },

        // Optional: Define some functionality after model was created
        // Example: Add default child components
        init() {
            const components = this.get('components');

            if (!components.length) {
                components.add([{
                    type: 'textnode',
                    content: 'Inner content'
                }]);
            }
        }

        someMethod() {
            // Some custom logic
        },

        // Optional: Define the parent type name that will be extended in the model
        extend: 'parent-type',

        // Optional: Following GrapesJS documentation could define some methods which going to extend for type model
        extendFn: ['someMethod']
    },

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

        // Optional: Defining parent type name, it type going to extend for view
        extendView: 'parent-type',

        // Optional: Following GrapesJS documentation could define some methods which going to extend for type view
        extendFnView: ['someMethod']
    },

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

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

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

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

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

    onCreate(model) {
        if (this.isOwnModel(model)) {
            // Some custom logic
        }
    },

    onSelect(model) {
        if (this.isOwnModel(model)) {
            // Some custom logic
        }
    },

    isComponent(el) {
        return el.nodeType === Node.ELEMENT_NODE && el.tagName === 'SPAN' && el.classList.contains('some-class');
    }
}, {
    // Define static property with type name
    type: 'some-type'
});

export default SomeType;

Creating Type With Function Constructors

You can define the model and the view type as a constructor function, as this gives you more freedom when implementing the required logic. You can provide a more advance method to extend existing types in the editor. You can also separate large components into different modules, as illustrated in the example below.

Example

Create a type model module called some-type-model.js. It is similar to other Backbone components but should be created in a special function with BaseTypeModel and other options in the function attributes.

src/{YourBundleName}/Resources/js/app/grapesjs/types/some-type/some-type-model.js

export default (BaseTypeModel, {editor}) => {
    const SomeTypeModel = BaseTypeModel.extend({
        constructor: function SomeTypeModel(...args) {
            // Note: Constructor should always return super
            return SomeTypeModel.__super__.constructor.apply(this, args);
        },

        init() {
            const components = this.get('components');

            if (!components.length) {
                components.add([{
                    type: 'textnode',
                    content: 'Inner content'
                }]);
            }
        },

        getAttributes(opts = {}) {
            const attributes = SomeTypeModel.__super__.getAttributes.call(this, opts);

            attributes['new-attr'] = 'Attribute value';

            return attributes;
        }
    });

    Object.defineProperty(SomeTypeModel.prototype, 'defaults', {
        value: {
            ...SomeTypeModel.prototype.defaults,
            classes: ['component-class', 'some-class'],
            tagName: 'span'
        }
    });

    return SomeTypeModel;
};

Create a type view module some-type-view.js the same way you create a type model.

src/{YourBundleName}/Resources/js/app/grapesjs/types/some-type/some-type-view.js

export default (BaseTypeView, {editor}) => {
    const SomeTypeView = BaseTypeView.extend({
        constructor: function SomeTypeView(...args) {
            // Notice: Constructor should always returns super
            return SomeTypeView.__super__.constructor.apply(this, args);
        },

        onRender() {
            // Do something after rendered
        }
    });

    return SomeTypeView;
};

Create a component of type some-type. It is similar to Creating Type In Single Module but the model and the view are placed in separate modules. Import them into the header of main module and set in properties ModelType and ViewType.

src/{YourBundleName}/Resources/js/app/grapesjs/types/some-type/index.js

import BaseType from 'orocms/js/app/grapesjs/types/base-type';
import ModelType from './some-type-model.js';
import ViewType from './some-type-view.js';

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

    ModelType,

    ViewType,

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

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

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

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

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

    onCreate() {
        // Some custom logic
    },

    onSelect() {
        // Some custom logic
    },

    isComponent(el) {
        return el.nodeType === Node.ELEMENT_NODE && el.tagName === 'SPAN' && el.classList.contains('some-class');
    }
}, {
    // Define static property with type name
    type: 'some-type'
});

export default SomeType;

Properties

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
TypeModel	Function	Defining model as the constructor function
TypeView	Function	Defining view as the constructor function
modelProps	Object	Methods and props used to extend the WYSIWYG component model. Prop defaults is merged with the default model attributes.
viewProps	Object	Methods and props used to extend the WYSIWYG component view
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.

Static Properties

type	String	Required	Define the component type name
priority	Number	Optional	Define the priority order to apply the component type. It is important when creating a type from a parent type

Methods

Name	Return	Options	Description
getTypeModelOptions	Object		Return object with properties from wrapper component for provide in the type model instance.
getTypeViewOptions	Object		Return object with properties from wrapper component for provide in the type model instance
getButtonTemplateData	Object		Return data for the button template
isOwnModel	Boolean	TypeModel	Detect is it model instance of for current type
onInit		Object	Hook after wrapper component initialized
getType	String		Get component type name
isComponent	Object|String|Boolean	DOMNode	Identify the the component type

Component Type Registration

For registering new type need create plugin or use exists plugin. Plugins loading dynamical, required add to jsmodules.yml dynamic path

Hint

Pay attention type should registered before editor initialized.

Register the created type builder with the component manager:

src/{YourBundleName}/Resources/js/app/grapesjs/plugins/foo-plugin.js

import GrapesJS from 'grapesjs';
import ComponentManager from 'orocms/js/app/grapesjs/plugins/components/component-manager';
import SomeTypeBuilder from '{yourbundlename}/js/app/grapesjs/types/some-type';

export default GrapesJS.plugins.add('foo-plugin', () => {
    ComponentManager.registerComponentTypes({
        'some': {
            Constructor: SomeTypeBuilder
        }
    });
});

Use Symfony Form Type Extension to add the new plugin to the WYSIWYG field. For more information about Symfony forms, see form type extension.

src/{YourBundleName}/Form/Extension/FooWysiwygTypeExtension.php

<?php

namespace App\Form\Extension;

use Symfony\Component\Form\AbstractTypeExtension;
use Symfony\Component\Form\Extension\Core\Type\FileType;

class FooWysiwygTypeExtension extends AbstractTypeExtension
{
    public function finishView(FormView $view, FormInterface $form, array $options): void
    {
        $pageComponentOptions = json_decode($view->vars['attr']['data-page-component-options'] ?? '', true);
        $pageComponentOptions['builderPlugins']['foo-plugin']['jsmodule'] = '{yourbundlename}/js/app/grapesjs/plugins/foo-plugin';
        $view->vars['attr']['data-page-component-options'] = json_encode($pageComponentOptions);
    }

    /**
     * Returns an array of extended types.
     */
    public static function getExtendedTypes(): iterable
    {
        return [WYSIWYGType::class];
    }
}

Add the path to the file to dynamic imports in jsmodules.yml. If jsmodules.yml does not exist, you need to create it. For more information about jsmodules.yml, see JS Modules.

src/{YourBundleName}/Resources/config/jsmodules.yml

dynamic-imports:
    foo_app:
        - {yourbundlename}/js/app/grapesjs/plugins/foo-plugin