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.
Migrate to the field plugin SDK
Section titled “Migrate to the field plugin SDK”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 legacy field plugin
Section titled “A legacy field plugin”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').
A new field plugin
Section titled “A new field plugin”To create a field plugin with the field plugin CLI, run the following command in the terminal:
npx @storyblok/field-plugin-cli@latest create --template vue3For 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.
Get data
Section titled “Get data”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); }});Actions
Section titled “Actions”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
// legacythis.$emit("changed-model", value);
// newplugin.actions.setContent(value);
// Toggle modal
// legacythis.$emit("toggle-modal", booleanValue);
// newplugin.actions.setModalOpen(booleanValue);
// Request the context
// legacythis.$emit("get-context");this.$onGetContext(() => { console.log(this.storyItem);});
// new: resolves with the current story dataconst 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>
// newconst asset = await plugin.actions.selectAsset();console.log(asset.filename);Summary of changes
Section titled “Summary of changes”| 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 |
Create a legacy field plugin
Section titled “Create a legacy field plugin”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 }}.
Output
Section titled “Output”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.
Settings
Section titled “Settings”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.
Local development
Section titled “Local development”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.
-
Clone the repository and start the development server
Terminal window git clone https://github.com/storyblok/storyblok-fieldtypecd storyblok-fieldtypenpm installnpm run devThe development server runs on
http://localhost:8080. -
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. -
Change the plugin name
Open the
src/Plugin.vuefile and change the plugin name in theinitWithmethod to the name you created in Storyblok.initWith() {return {// needs to be equal to your storyblok plugin nameplugin: 'my-plugin-name',title: '',description: ''}} -
Enable the local development mode
In the plugin editor, enable the local development mode to load your local environment into the field plugin preview.
-
Deploy the plugin
Run
npm run build, copy the content of thedist/export.jsfile 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 theinitWith()method inPlugin.vue, the import fails.
API reference
Section titled “API reference”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.
Properties
Section titled “Properties”| 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 |
Methods
Section titled “Methods”| 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 |
Helpers
Section titled “Helpers”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});Events
Section titled “Events”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 |
Get the current context
Section titled “Get the current context”To read the current story, emit the get-context event:
this.$emit("get-context");this.$onGetContext(() => { console.log(this.storyItem);});Built-in components
Section titled “Built-in components”Use Storyblok’s built-in proxy components in your field plugin for user input that requires access to the Management API.
Asset selector
Section titled “Asset selector”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.
Was this page helpful?
This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.
- Need help?Contact support (opens in a new window)
- Something isn’t right?Check system status (opens in a new window)
Get in touch with the Storyblok community