editor.js/docs/block-tunes.md

Block Tunes

Similar with Tools represented Blocks, you can create Block Tunes and connect it to particular Tool or for all Tools.

Block Tunes allows you to set any additional options to Blocks. For example, with corresponded Block Tunes you can mark Block as «spoiler», give it an anchor, set a background, and so on.

Base structure

Tune's class should have the isTune property (static getter) set to true.

Block Tune must implement the render() method which returns an HTML Element that will be appended to the Block Settings panel.

• render() — create a button

Also, you can provide optional methods

• wrap() — wraps Block content with own HTML elements
• save() — save Tunes state on Editor's save

At the constructor of Tune's class exemplar you will receive an object with following parameters:

Parameter	Description
api	Editor's API obejct
config	Configuration of Block Tool Tune is connected to (might be useful in some cases)
block	Block API methods for block Tune is connected to
data	Saved Tune data

---

render(): HTMLElement

Method that returns button to append to the block settings area

Parameters

Method does not accept any parameters

Return value

type	description
HTMLElement	element that will be added to the block settings area

---

wrap(blockContent: HTMLElement): HTMLElement

Method that accepts Block's content and wrap it with your own layout. Might be useful if you want to modify Block appearance.

class Tune {
    wrap(blockContent) {
        const myWrapper = document.createElement('div');

        myWrapper.append(blockContent);

        return myWrapper;
    }
}

Parameters

name	type	description
blockContent	HTMLElement	Block's content (might be wrapped by other Tunes)

Return value

type	description
HTMLElement	Your element that wraps block content

---

save()

Method should return Tune's state you want to save to Editor's output

Parameters

No parameters

Return value

type	description
any	any data you want to save

---

static prepare()

If you need to prepare some data for Tune (eg. load external script, create HTML nodes in the document, etc) you can use the static prepare() method.

It accepts tunes config passed on Editor's initialization as an argument:

class Tune {
  static prepare(config) {
    loadScript();
    insertNodes();
    ...
  }
}

Parameters

type	description
object	your Tune configuration

Return value

No return value

---

static reset()

On Editor destroy you can use an opposite method reset to clean up all prepared data:

class Tune {
  static reset() {
    cleanUpScripts();
    deleteNodes();
  ...
  }
}

Parameters

No parameters

Return value

No return value

---

static get sanitize()

If your Tune inserts any HTML markup into Block's content you need to provide sanitize configuration, so your HTML is not trimmed on save.

Please see more information at sanitizer page.

class Tune {
  static get sanitize() {
    return {
      sup: true
    }
  }
}

Format

Tunes data is saved to tunes property of output object:

{
  blocks: [
    {
      type: 'paragraph',
      data: {
        text: 'This is paragraph with Tune'
      },
      tunes: {
        'my-tune-name': {},
        favorite: true,
        anchor: 'might be string'
      }
    }
  ]
}