Skip to content

Field Plugins (Legacy)

A legacy field plugin is a Vue.js 2.5.2 component extended with helpers in the window.Storyblok.plugin variable. It defines a custom field type, such as a color picker or a Google Maps location selector.

In 2023, Storyblok launched a new SDK for developing field plugins. While older field plugins only worked with Vue 2.5, the new SDK is framework-agnostic: develop with any frontend framework, including Vue 3 and React, or with plain JavaScript. The new SDK also offers newer features, in-depth documentation, and TypeScript support, and Storyblok maintains it.

Follow this guide to upgrade a legacy field plugin from Vue 2.5 to Vue 3.

A simplistic legacy field plugin may look like this:

const Fieldtype = {
mixins: [window.Storyblok.plugin],
template: `<div><input v-model="model.example" /></div>`,
methods: {
initWith() {
return {
plugin: "test-field-plugin",
example: "Hello World!",
};
},
pluginCreated() {
console.log("plugin:created");
},
},
watch: {
model: {
handler: function (value) {
this.$emit("changed-model", value);
},
deep: true,
},
},
};

Whenever model changes, the plugin emits a changed-model event to its parent. Storyblok injects a hidden parent component, the field type wrapper, that receives this event and forwards it to the Visual Editor with postMessage. All communication uses $emit('some-event').

To create a field plugin with the field plugin CLI, run the following command in the terminal:

Terminal window
npx @storyblok/field-plugin-cli@latest create --template vue3

For a working example, open src/components/FieldPluginExample/index.vue.

The legacy component above becomes the following:

<script setup>
import { useFieldPlugin } from "@storyblok/field-plugin/vue3";
const plugin = useFieldPlugin({
validateContent: (content) => ({
content: typeof content === "string" ? content : "",
}),
});
</script>
<template>
<div v-if="plugin.type === 'loaded'">
<input :value="plugin.data.content" @input="plugin.actions.setContent($event.target.value)" />
</div>
</template>

The this.$emit('changed-model', value) call becomes plugin.actions.setContent(value).

useFieldPlugin starts in a loading state. Use plugin.data and plugin.actions once plugin.type is loaded. The validateContent function validates the saved content and sets default values for missing keys.

In the legacy version, window.Storyblok.plugin injected all the data into this of the root component.

const Fieldtype = {
mixins: [window.Storyblok.plugin],
// ...
watch: {
model: {
handler: function (value) {
console.log("💡 data", {
blockId: this.blockId,
contentmodel: this.contentmodel,
model: this.model,
schema: this.schema,
spaceId: this.spaceId,
storyId: this.storyId,
storyItem: this.storyItem,
token: this.token,
uid: this.uid,
userId: this.userId,
});
this.$emit("changed-model", value);
},
deep: true,
},
},
};

The useFieldPlugin composable handles the messaging for you:

import { watchEffect } from "vue";
import { useFieldPlugin } from "@storyblok/field-plugin/vue3";
const plugin = useFieldPlugin();
watchEffect(() => {
if (plugin.type === "loaded") {
console.log(plugin.data);
}
});

Use the useFieldPlugin composable to run actions. In the following examples, plugin is the return value of useFieldPlugin(). Call actions in event handlers when plugin.type is loaded.

// Set content
// legacy
this.$emit("changed-model", value);
// new
plugin.actions.setContent(value);
// Toggle modal
// legacy
this.$emit("toggle-modal", booleanValue);
// new
plugin.actions.setModalOpen(booleanValue);
// Request the context
// legacy
this.$emit("get-context");
this.$onGetContext(() => {
console.log(this.storyItem);
});
// new: resolves with the current story data
const story = await plugin.actions.requestContext();
// Select an asset
// legacy: you had to include this proxy component
// <sb-asset-selector :uid="uid" field="your_model_attribute"></sb-asset-selector>
// new
const asset = await plugin.actions.selectAsset();
console.log(asset.filename);
Change Item Description
Added content In the legacy version, you had to send an object containing a plugin property (for example, { plugin: "my-plugin", some: "value" }). Now content can be anything that the structured clone algorithm can serialize, such as a string, boolean, number, object, or array. Pass content from a field plugin to Storyblok’s Visual Editor with postMessage. To learn more about what you can send, read the structured clone algorithm.
Removed initWith window.Storyblok.plugin called the initWith method. The useFieldPlugin composable replaces it.
Changed Content defaults plugin.data.content holds the stored value as is, without a default. To set a type and a default, pass validateContent to useFieldPlugin.
Removed pluginCreated Use the standard lifecycle callbacks, such as onMounted().
Removed Default style The legacy API injected a default CSS file (https://plugins.storyblok.com/plugin-assets/css/index-latest.css). The new version gives you full control over the styling. To match the Storyblok editor, follow Style the field plugin.
Removed api The storyblok-js-client is no longer included by default. To include it, run npm install storyblok-js-client.
Removed $sb

To create a new field plugin, open the Partner Portal or your organization, select Field-types, and choose New Field-type. Enter a unique name slug. Storyblok redirects you to the plugin editor.

To create a field plugin that only you can access, open My Account → My Plugins ans select New Field-type.

The plugin editor lets you prototype your idea in the browser. The left side shows a demo field plugin, which is a basic Vue.js component. On the right side, a preview shows the plugin, and you can enable the local development mode.

The top left shows the plugin name and versions. The plugin name must match the name in the initWith() method.

To update the local preview, select Save. To update the plugin wherever Storyblok uses it, select Publish.

Storyblok passes the input options to the preview instance of your plugin. When you add the plugin to a schema or field, Storyblok adds the option keys you enter here to the new plugin instance.

  • Space ID: the space that Storyblok passes to your plugin as preview configuration.
  • Options: key-value pairs of configuration options that Storyblok passes to your preview.

Use the options to pass API endpoints or other input to the plugin. Access any option, for example, the endpoint option, inside the plugin with this.options.endpoint or in the template with {{ options.endpoint }}.

The plugin output contains all fields defined in the initWith method and all your model properties. Storyblok stores only the properties of the model property and returns them in the Content Delivery API. For local variables, such as helpers, use Vue data instead.

In the Settings area, submit your plugin for review and assign it to spaces where you’re an owner, admin, or collaborator. Once you assign the plugin to a space, the admin of that space can use it in their components and content types. You can also delete your field plugin here.

To build more complex plugins, develop the plugin in a local development environment with your editor of choice. This lets you load other plugins and organize your code in multiple files.

  1. Clone the repository and start the development server

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

    The development server runs on http://localhost:8080.

  2. Change the URL of the development server

    Change the URL to https://app.storyblok.com. Learn how to serve a local development server over HTTPS on macOS and Windows.

  3. Change the plugin name

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

    initWith() {
    return {
    // needs to be equal to your storyblok plugin name
    plugin: 'my-plugin-name',
    title: '',
    description: ''
    }
    }
  4. Enable the local development mode

    In the plugin editor, enable the local development mode to load your local environment into the field plugin preview.

  5. Deploy the plugin

    Run npm run build, copy the content of the dist/export.js file into the editor text field in Storyblok, and select Save. Storyblok now shows your plugin without a running local server. If the plugin name in Storyblok doesn’t match the name in the initWith() method in Plugin.vue, the import fails.

Your plugin runs in a sandbox, so it can’t access other DOM elements of the app.storyblok.com application. Instead, Storyblok passes specific properties and methods to the plugin.

Property Description
model Current value of the plugin, which Storyblok saves and returns in the API
options Options parsed from the schema options array
schema Schema options object
uid UID of the parent component
spaceId ID of the current space
storyItem Object of the current story
sbLanguage Current language
api API function to call the Content Delivery API
token Draft token of the current space
blockId UID of the block the field plugin is active in (undefined outside of the Visual Editor)
userId ID of the user who’s using the interface
Method Description
initWith Defines the initial data of the plugin
pluginCreated Initializes the plugin, for example, to load data from Storyblok or external sources, or to load and initialize a WYSIWYG editor

The $sb variable contains commonly used helper functions.

Helper Description
$sb.getScript Loads external resources with a callback
this.$sb.getScript("https://use.fontawesome.com/releases/v5.0.9/js/all.js", () => {
// script available
});

Storyblok events let the plugin change the sandbox’s appearance and behavior in the parent app.storyblok.com application.

Event Description
this.$emit('toggle-modal', true) Opens the plugin in a full-screen overlay
this.$emit('toggle-modal', false) Closes the full-screen overlay

To read the current story, emit the get-context event:

this.$emit("get-context");
this.$onGetContext(() => {
console.log(this.storyItem);
});

Use Storyblok’s built-in proxy components in your field plugin for user input that requires access to the Management API.

This proxy component lets the user select an image and sets the image URL on an attribute of your field plugin. The field attribute is the key of your model attribute.

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

The field attribute must match a property of the model object that you return from the initWith method.

Last updated:

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.