Block extensions

The Editor can be extended with additional block plugins.

Anatomy of a block plugin

Block plugins are regular Kirby plugins. They are stored in /site/plugins. A basic block plugin is made up of a custom snippet, defined in your index.php and a block Vue component defined in your index.js.

/site/plugins/custom-block/
/site/plugins/custom-block/index.php
/site/plugins/custom-block/index.js
/site/plugins/custom-block/index.css
/site/plugins/custom-block/snippets/custom.php

Defining a snippet

// /site/plugins/custom-block/index.php
Kirby::plugin('yourname/custom-block', [
  'snippets' => [
    'editor/custom' => __DIR__ . '/snippets/custom.php
  ]
]);

The snippet can contain any HTML for the block. Check out the block snippets guide for all available variables in snippets.

<!-- /site/plugins/custom-block/snippets/custom.php -->
<p>Hello world</p>

Registering your block Vue component

You must use the editor.block registering method to create a new block type. As the first argument, you pass the type for the block. This will also correspond with the loaded snippet. As a second argument, you can pass the Vue component definition object.

// /site/plugins/custom-block/index.js

editor.block("custom", {
  label: "Custom",
  icon: "alert",
  template: "<p>Hello world</p>"
});

The passed object is a regular Vue component definition with a few additional options.

label

The label is used in the dropdown menu of the editor.

icon

The icon will be used in the dropdown menu of the editor. You can use all icons from our reference: https://getkirby.com/docs/reference/panel/icons

CSS

The editor wraps each block in a generic wrapper div with a CSS class that follows this scheme:

k-editor-$type-block

You can use this to create scoped CSS for your block plugin.

/* /site/plugins/custom-block/index.css */
.k-editor-custom-block p {
  background: red;
}

Single file components

If you prefer to have a build process and use Vue single file components you can pass your component directly to the editor.block method:

// /site/plugins/custom-block/index.js

import CustomBlock from "./components/CustomBlock.vue"

editor.block("custom", CustomBlock);

The script block of your single file component must contain the additional block attributes though.

<template>
  <p>Hello world</p>
</template>

<script>
// /site/plugins/custom-block/src/components/CustomBlock.vue
export default {
  label: "Custom",
  icon: "alert"
}
</script>

<style>
.k-editor-custom-block p {
  background: red;
}
</style>

Extending existing block types

You can extend any existing block component. This is perfect when you want to add custom styling or custom methods to an already existing block type.

editor.block("intro", {
  extends: "paragraph",
  label: "Intro",
  icon: "text"
});

Custom Block Models

A block plugin can load a custom block class for its type. This adds additional possibilities to change the behaviour and API response of the Block object.

In order for the editor to pick up your custom block model class, the class name must follow this scheme

Kirby\Editor\{$type}Block

Here's an example from the image block:

Kirby\Editor\ImageBlock

We recommend to load custom block classes with our load() helper in your index.php

load([
  'kirby\editor\customblock' => __DIR__ . '/CustomBlock.php'
]);

Plugin examples

You can find a set of plugin examples here: https://github.com/bastianallgeier/editor/tree/master/examples