Creating a Storyblok field type plugin

We built Storyblok with a robust and flexible plugin system to give you the possibility to extend the editor with custom fields like a color picker or a google maps location selector.

In this Tutorial, we will create a field type plugin to extend the Storyblok editor with a meta-tag plugin. It will contain meta-tag fields and a little preview how they will look like in Google.

This is how the result will look like:

Storyblok editing capabilities

1. Set up a local development environment

You can develop your plugin locally or directly in Storyblok. We will clone the field type repository to get a local development server with hot reload and babel.

git clone https://github.com/storyblok/storyblok-fieldtype my-plugin
cd my-plugin
npm install

Finally, you can start the development server.

npm run dev

This command will open your browser with a preview of the plugin.

Storyblok Endresult

2. Starting development

We are using the popular Vue.js framework for the component system of Storyblok. Before starting development, you should read the Vue.js guides.

Open the file src/Plugin.vue and edit the template part of it. The browser should refresh directly after you saved the file.

If you want to style the elements in your plugin, you should use the p namespace .p-[yourplugin]__your-element. In the example, the name of the plugin is metatags and we have to show google-title in blue:

<template>
  <div class="p-metatags__google-title">{{ model.title }}</div>
</template>
<style>
  .p-metatags__google-title {
    color: blue;
  }
</style>

The script part explained:

<script>
export default {
  // This mixin extends a standard Vue.js component and 
  // triggers 'plugin:created' and 'plugin:destroyed' events
  mixins: [window.Storyblok.plugin],
  methods: {
    // This will be used to initialize the plugin with data if no data is defined. 
    // You need to at least set the plugin name.
    initWith: function() {
      return {
        plugin: 'metatags', // required
        title: 'Your title' // add as much as objects you want
      }
    }
  },
  events: {
    // Triggered after the plugin has been inserted and the data has been passed
    'plugin:created': function() {
      console.log('plugin:created')
    },
    // Triggered after the plugin has been removed from DOM
    'plugin:destroyed': function() {
      console.log('plugin:destroyed')
    }
  },
  watch: {
    // To pass the user input to Storyblok you need to 
    // emit the event 'changed-model' and pass the value
    'model': {
      handler: function (value) {
        this.$emit('changed-model', value);
      },
      deep: true
    }
  }
}
</script>

3. Publish the plugin on Storyblok

Create a new plugin in Storyblok providing a unique name.

Storyblok Plugin Endresult

In your plugin project insert the name of the plugin you just created in Storyblok.

<script>
export default {
  initWith: function() {
      return {
        plugin: 'INSERT_PLUGIN_NAME',
...

Now execute the build process

npm run build

The file export.js will be saved into the dist folder. Copy the content of this file into the code editor of your plugin in Storyblok.

Storyblok Editor

4. Use the plugin

After creating the plugin, you can define it in the schema configuration of your components. Choose ‘Custom Plugins’ as the type and search for your plugin.

Storyblok use the plugin

Documentation