- Article Editor

Examples

The easiest way to learn how to create your blocks is by examples. Here are some plugins with custom blocks created by us and examples that you can download and study:

Creating block

Let's say that our content should have a block of tags, with the ability to create and edit them. For example, this html should be parsed in Article as a tags block:

<div class="tags">
    <span class="tag">Tag 1</span>
    <span class="tag">Tag 2</span>
</div>

To do this, you need to create a block code, for example, like this:

ArticleEditor.add('block', 'block.tags', {
    mixins: ['block'],
    type: 'tags',
    translations: {
        'en': {
             "blocks": {
                 "tags": "Tags"
             }
        }
    },
    parser: {
        tag: 'div',
        parse: function($el) {
            return ($el.hasClass('tags')) ? 'tags' : false;
        }
    },
    toolbar: {
        add: {
            command: 'addbar.popup',
            title: ''
        },
        tags: {
            command: 'tags.edit',
            title: '',
            icon: '<svg ...>'
        }
    },
    control: {
        trash: {
            command: 'block.remove',
            title: ''
        },
        duplicate: {
            command: 'block.duplicate',
            title: ''
        }
    },
    create: function() {
        return this.dom('<div>').addClass('tags');
    }
});

Let's see what it's made of.

mixins

The mixins parameter indicates that the block will inherit methods from Block.instance. This will allow you to work with a custom block inside the editor the same way as with an already built in block.

type

Indicates the name or type of block.

parser

This parameter tells the editor which tag the block has and which class or attribute the block should have when parsing content.

toolbar

This parameter sets the buttons that will be displayed in toolbar when you click on the block. You can turn off the toolbar by specifying false.

ArticleEditor.add('block', 'block.myblock', {
    mixins: ['block'],
    type: 'myblock',
    toolbar: false

    ...

});

control

This parameter sets the buttons that will be displayed in control when you click on the block. You can turn off the control by specifying false.

ArticleEditor.add('block', 'block.myblock', {
    mixins: ['block'],
    type: 'myblock',
    control: false

    ...

});

create

The method of block creation. This method can be called if a block is created via addbar or using this.app.create:

var myblock = this.app.create('block.myblock');

nested

A true value will indicate that there may be other blocks inside the block.

ArticleEditor.add('block', 'block.myblock', {
    mixins: ['block'],
    type: 'myblock',
    nested: true

    ...

});

editable

A true value will indicate that the block content is editable.

ArticleEditor.add('block', 'block.myblock', {
    mixins: ['block'],
    type: 'myblock',
    editable: true

    ...

});

Create a block from a source

An instance of the block can be created in the plugin via the app.create method with the source specified. For example:

var $source = this.dom('<div class="tags"></div>');
var instance = this.app.create('block.myblock', $source);

Create a block with params

An instance of the block can be created in the plugin via the app.create method with parameters passed to build the block. For example:

var params = { param1: 1, param2: 2  };
var instance = this.app.create('block.myblock', false, params);

In this case the parameters are passed to the build block method.

ArticleEditor.add('block', 'block.myblock', {
    mixins: ['block'],
    type: 'myblock',
    ...
    build: function(params) {
        this.$block.attr('param1', params.param1);
    }
    ...
});

Summary

Example Tags Plugin shows a fully created custom block, how to add its icon to the toolbar, addbar, and how to edit content of the block.

Docs

Documentation

How to create a custom block