Creating a Storyblok field type plugin

We built Storyblok with a robust and flexible plugin system to give our customers the power to extend the editor with custom fields like a color picker or a google maps location selector. It’s basically a Vue.js 2.5.2 component extended with a few helpers in the ‘window.Storyblok.plugin’ variable.

This is a typical field type plugin:

A field type plugin

How to develop field type plugins

You can develop field type plugins inside Storyblok using ES6 Javascript. On the top left corner you can find the official and personal “Plugins” in the submenu.

Storyblok Plugin Endresult

Available Vue.js properties

The properties that are passed to the field type are:

  • options: Options parsed from the schema options array
  • schema: Schema options object
  • uid: Uid of the parent component
  • spaceId: Space id of the current space
  • storyId: Story id of the current story
  • model: Current value of the fieldtype
  • api: Api function to call the delivery api
  • token: Draft token of the current space

Methods

  • initWith: Should be used to define the initial data of the plugin.
  • pluginCreated: Should be used to initialize the plugin. Examples: Load data from Storyblok or external sources, Load and initialize a WYSIWYG editor.

Helper

In the $sb variable are stored commonly used helper functions.

$sb.getScript(scriptName, loadedCallback)

This method can be called to get external scripts.

this.$sb.getScript('https://use.fontawesome.com/releases/v5.0.9/js/all.js', () => {})

Proxy Components

Proxy components are Vue.js components which you can use in your custom field-type for user inputs that require access to the management API.

Asset selector
This proxy component let’s the user select an image and sets the image url to an attribute of your custom field-type. The field attribute needs to be the key of your model attribute. Following an example:

<sb-asset-selector :uid="uid" field="your_model_attribute">
</sb-asset-selector>

…more proxy components
Do you have an idea for a proxy component? Just talk with us at the live chat to request one.

How to call the Storyblok API?

In fieldtypes, you can use ‘this.api’ to get access to the Storyblok delivery api. For example, you can use it to build a selectbox of stories.

this.api.get(`cdn/stories`)
.then((res) => {
  this.stories = res.data.stories
})

How to pass options?

To pass options that are configurable in the schema definition define the option keys in the ‘Input’ box. The values will be available in the ‘this.options’ object.

Img

How to use the field type 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

Local development

If you want to create more complex plugins you have also the option to develop a plugin with a local dev environment using your favorite editor. This let’s you load other plugins and organize your code in multiple files.

There is also a great tutorial about plugin development on Markus Oberlehner’s blog: https://markus.oberlehner.net/blog/building-a-custom-storyblok-field-type-plugin-with-vue/

How to develop plugins locally

1. Start by cloning the field-type repository and run the dev server.

$ git clone https://github.com/storyblok/storyblok-fieldtype
$ cd storyblok-fieldtype
$ npm install
$ npm run dev

This will spin up a server on http://localhost:8080.

2. Next you need to change the url of the Storyblok app from https://app.storyblok.com to http://app.storyblok.com as your local environment runs on http.

3. Open the file Plugin.vue and change the plugin name in the initWith method to the one you created in Storyblok.

4. Now you can click the checkbox “Enable local dev mode” to load your local environment into the field-type preview and start developing your plugin.

Local development

5. When you finished developing your plugin you need to run npm run build and copy the content of the file src/vendor/export.js into the editor text field of the Storyblok app and click the publish button.

Documentation