GrapesJS UI Components

The Jmix framework supports several GrapesJS UI components:

  • grapesJsHtmlEditor - a base HTML editor without any applied plugins.

  • grapesJsWebpageHtmlEditor - an HTML editor suitable for webpage development with applied webpage, customcode plugins.

  • grapesJsNewsletterHtmlEditor - an HTML editor suitable for newsletter development with applied newsletter, customcode plugins.

    The grapesJsNewsletterHtmlEditor component has an additional inlineCss attribute. If it is enabled, then CSS classes will be inlined in HTML.

The example below demonstrates how to create a grapesJsHtmlEditor component:

<window xmlns="http://jmix.io/schema/ui/window"
        caption="Grapes JS Screen"
        xmlns:grapesjs="http://jmix.io/schema/grapesjs/ui">
    <layout expand="htmlEditor" spacing="true">
        <grapesjs:grapesJsHtmlEditor id="htmlEditor">
            <grapesjs:plugin name="basicBlocks"/>
        </grapesjs:grapesJsHtmlEditor>
    </layout>
</window>

All GrapesJS UI components provide following methods:

  • setValue(String value) - to set HTML content for the component;

  • getValue() - to get HTML content from the component;

  • runCommand(String command) - to run command;

  • stopCommand(String command) - to stop command.

Disabled Blocks

You can define a comma-separated list of blocks that should be disabled, for example:

<grapesjs:grapesJsHtmlEditor id="htmlEditor">
    <grapesjs:disabledBlocks>
        map,tabs
    </grapesjs:disabledBlocks>
</grapesjs:grapesJsHtmlEditor>

Plugins

UI components can be extended with plugins using the plugin element. A plugin can be selected from the predefined plugins list or configured as a new plugin.

The following default available plugins are supported:

  • basicBlocks - this plugin contains some basic blocks for the GrapesJS editor (see the GrapesJS Basic Blocks documentation).

  • ckeditor - this plugin replaces the default Rich Text Editor with CKEditor (see the GrapesJS CKEditor documentation).

  • customcode - this plugin adds a possibility to embed custom code (see the GrapesJS Custom Code documentation).

  • flexBlocks - this plugin adds the Flexbox block, which allows creating easily flexible and responsive columns (see the GrapesJS Blocks Flexbox documentation).

  • forms - this plugin adds some basic form components and blocks to make working with forms easier (see the GrapesJS Forms documentation).

  • newsletter - this preset configures GrapesJS to be used as a Newsletter Builder with some unique features and blocks composed specifically for being rendered correctly inside all major email clients (see the GrapesJS Newsletter Preset documentation).

  • postcss - this plugin enables custom CSS parser via PostCSS (see the GrapesJS Parser PostCSS documentation).

  • styleFilter - this plugin adds the filter type input to the Style Manager in GrapesJS (see the GrapesJS Style Filter documentation).

  • tabs - simple tabs component plugin for GrapesJS (see the GrapesJS Tabs documentation).

  • tooltip - simple, CSS only, tooltip component for GrapesJS (see the GrapesJS Tooltip documentation).

  • touch - this plugin enables touch support for the GrapesJS editor (see the GrapesJS Touch documentation).

  • tuiImageEditor - this plugin adds the TOAST UI Image Editor on Image Components in GrapesJS (see the GrapesJS TOAST UI Image Editor documentation).

  • webpage - this preset configures GrapesJS to be used as a Webpage Builder (see the GrapesJS Preset Webpage documentation).

Here is an example of defining grapesJsNewsletterHtmlEditor with plugins:

<grapesjs:grapesJsNewsletterHtmlEditor id="templateEditor"
                                       inlineCss="true"
                                       height="100%" width="100%">
    <grapesjs:disabledBlocks>
        map
    </grapesjs:disabledBlocks>
    <grapesjs:plugin name="basicBlocks"/>
    <grapesjs:plugin name="forms"/>
    <grapesjs:plugin name="styleFilter"/>
    <grapesjs:plugin name="ckeditor">
        <grapesjs:optionsPath>
            /io/jmix/grapesjs/plugins/gjs-plugin-ckeditor.js
        </grapesjs:optionsPath>
    </grapesjs:plugin>
    <grapesjs:plugin name="forms"/>
    <grapesjs:plugin name="flexBlocks"/>
    <grapesjs:plugin name="tuiImageEditor"/>
    <grapesjs:plugin name="customcode"/>
    <grapesjs:plugin name="postcss"/>
    <grapesjs:plugin name="styleFilter"/>
    <grapesjs:plugin name="webpage">
        <grapesjs:options> (1)
            <![CDATA[
            {
            "modalImportTitle" : "Import HTML"
            }
            ]]>
        </grapesjs:options>
    </grapesjs:plugin>
</grapesjs:grapesJsNewsletterHtmlEditor>
1 Define custom plugin options.

Custom project plugins can be registered via the io.jmix.grapesjs.component.GjsPluginsRepository class.

Custom Blocks

Custom blocks can be added to the component using the block element with the following parameters:

  • name - a unique block id;

  • label - a name of the block;

  • category - group the block inside a category;

  • content - HTML content;

  • contentPath - path to HTML content;

  • attributes - block attributes.

The example below demonstrates how to create a custom block:

<grapesjs:block>
    <grapesjs:name>h1-block</grapesjs:name>
    <grapesjs:label>Heading</grapesjs:label>
    <grapesjs:category>Basic</grapesjs:category>
    <grapesjs:content>
        <![CDATA[<h1>Put your title here</h1>]]>
    </grapesjs:content>
    <grapesjs:attributes>
        <![CDATA[
            {
                title: 'Insert h1 block',
                class:'fa fa-th'
            }
        ]]>
    </grapesjs:attributes>
</grapesjs:block>

Custom project blocks can be registered via the io.jmix.grapesjs.component.GjsBlocksRepository class. Registered blocks can be added to UI components by the name attribute.

In the example below, we create a Spring bean, where register a new custom block:

@Component
public class BlocksRegister {

    @Autowired
    protected GjsBlocksRepository gjsBlocksRepository;

    @Authenticated
    public void registerBlock() {
        GjsBlock testBlock = new GjsBlock(); (1)
        testBlock.setName("h1-block");
        testBlock.setLabel("Heading");
        testBlock.setCategory("Basic");
        testBlock.setContent("<h1>Put your title here</h1>");
        testBlock.setAttributes("{" +
                "              title: 'Insert h1 block',\n" +
                "              class:'fa fa-th'\n" +
                "       }");
        gjsBlocksRepository.registerBlock(testBlock); (2)
    }
}
1 Create an instance of GrapesJS block.
2 Register custom GrapesJS block, which can be used in the XML descriptor.

Then we add an earlier registered block in the XML descriptor:

<grapesjs:grapesJsHtmlEditor id="htmlEditor">
    <grapesjs:disabledBlocks>
        map,tabs
    </grapesjs:disabledBlocks>
    <grapesjs:block name="h1-block"/>
</grapesjs:grapesJsHtmlEditor>

Please use class:'fa <fa-icon>' in the attributes parameter to use Font Awesome icon.