Understanding the Visual Editor

required:

This chapter assumes you’ve read Content Structures and understand how to access your content.

The Visual Editor enables your editors to edit their content with an in context preview, including the possibility to click on Components in their website. This feature is optional and does not depend on any specific technology. It will not alter the structure of HTML or rearrange your DOM. The visual editor will not affect your production sites as it can be enabled only when inside of the Storyblok UI. The visual editor will not allow inline editing; changing content will always be done in the Storyblok UI and the normal form inputs and custom fields you have defined for your content types and bloks.

Screenshot of the visual editor

  • {1} Visual Editor - Preview: Your project embedded in an iFrame
  • {2} Visual Editor - Content: Bloks and Fields on the right-hand side

Visual Editor - Preview

Visual Editor Preview

The left-hand side of the Visual Editor contains an iframe of your actual website, which we call Preview. This is not something we will render on our end, it is in fact your own implementation hosted on your infrastructure completely decoupled from Storyblok. You can configure the domain we’re using to embed your site in the Space Setting under General > Location (default environment). You can configure multiple Preview URLs which enables you to add development and deployment environments as an option for the Preview source.

While your project is embedded in the Visual Editor, we will append the current full_slug of the Story you’re currently editing and add additional query params to your Preview URL. Those parameters allow you to identify when to load the draft content for the Visual Editor Preview if embedded.

warn:

Make sure to not have X-Frame-Options enabled for your iframe preview environment.

hint:

When using http for your Preview URLs the Storyblok UI will redirect to a non https version as well, otherwise Browser Security restrictions won’t allow us to embed your site. This is only recommended for local development domains such as http://localhost or similar. The API requests to the Management API will still be done using https.

Preview URL structure

https://www.yourdomain.com/articles/my-first-article?_storyblok=67341&...
          └── Preview URL      │                          │
                               └── full_slug              └── additional Query Params

Additional Query Params

Query Param Description
_storyblok the numeric story ID
_storyblok_tk[space_id] the space ID
_storyblok_tk[timestamp] a unix timestamp
_storyblok_tk[token] a validation token. Combination of _storyblok_tk[space_id], _storyblok_tk[timestamp] and your Preview Token
_storyblok_release id of the active release
_storyblok_lang currently selected language
_storyblok_c content type of the story
hint:

Redirects can remove the URL parameters above and result in the Storyblok JS Bridge not being initialized. Make sure to not have redirects or to pass the query parameters accordingly.

Visual Editor - Content

Visual Editor Content Area

In this area of the Visual Editor you and your editors are able to adjust and change your content by using the Fields and Bloks you’ve defined for your content type.

Bridge between the Visual Editor Preview and Content

We’ve created a toolkit that enables you to set-up a bridge between the Visual Editor Content and your project embedded in the Preview. We refer to this toolkit as Storyblok JS Bridge. The Storyblok JS Bridge enables you to listen to events such as change, published, unpublished and input. You can allow click events on your own HTML elements which will then open up the correct Story and Blok in the Visual Editor Content area.

The Storyblok JS Bridge is used for two main tasks

  1. Enabling click events on your HTML elements to open up in the Visual Editor Content area.
  2. Listen to Visual Editor events to update your content or trigger processes.

Installing the Storyblok JS Bridge

Installation of the Storyblok JS Bridge is done by including a script tag on your site or using one of our modules for specific technologies.

<script src="//app.storyblok.com/f/storyblok-latest.js?t=YOUR_PREVIEW_TOKEN" type="text/javascript">
</script>
hint:

The Storyblok JS Bridge does not have to be included in production builds of your site.

Initializing the Storyblok JS Bridge

The Storyblok JS Bridge is automatically initialized when you have the ?t=YOUR_PREVIEW_TOKEN parameter included as shown in the script tag above. If you want to programmatically initialize the Storyblok JS Bridge because you only want it to be enabled if you’re inside the iframe, you can remove that parameter and use the init function.

// Initialize the Storyblok JS Bridge
window.storyblok.init({
  accessToken: 'YOUR_PREVIEW_TOKEN'
})

// Ping the Visual Editor and enter Editmode manually
window.storyblok.pingEditor(function() {
  if (window.storyblok.inEditor) {
    window.storyblok.enterEditmode()
  }
})

Enabling click events on your HTML Elements

To enable the click events that will send messages to the Visual Editor you will have to output the content of the _editable property before each of your own HTML Elements. The content of the _editable property contains a HTML comment for each Story and Blok. The Storyblok JS Bridge will then automatically register click events of the HTML Element that follow that HTML comment.

Example Explanation

When you load one Story using the URL parameter version=draft from the Content Delivery API you will end up with a response like this:

{
  "story": {
    "id": 172223,
    "content": {
      "_editable": "<!--#storyblok#{\"name\": \"page\", \"space\": \"14141\", \"uid\": \"b370f32d-cd89-4dd3-9437-16b5e9746b31\", \"id\": \"172223\"}-->",
      "component": "page",
      "body": [
        {
          "_editable": "<!--#storyblok#{\"name\": \"hero\", \"space\": \"14141\", \"uid\": \"98b685a1-da10-4df2-837e-3429d5ea6f88\", \"id\": \"172223\"}-->",
          "component":"hero",
          "headline": "This is my headline!"
        }
      ]
    }
  }
}
learn:

Read more about the different versions of your Content in Accessing your Content.

We can then push that data through any template engine or framework of your choice to render HTML.

{{story.content._editable}}
<div class="content-type">
    {% for blok in story.content.body %}
        {{blok._editable}}
        <div class="blok">
            {{blok.custom_field}}
        </div>
    {% endfor %}
</div>
hint:

You can use any templating engine you want. The example above is using Mustache syntax.

We end up with HTML that looks like this:

<!--#storyblok#{\"name\": \"page\", \"space\": \"14141\", \"uid\": \"b370f32d-cd89-4dd3-9437-16b5e9746b31\", \"id\": \"172223\"}-->
<div class="content-type">
    <!--#storyblok#{\"name\": \"hero\", \"space\": \"14141\", \"uid\": \"98b685a1-da10-4df2-837e-3429d5ea6f88\", \"id\": \"172223\"}-->
    <div class="blok">
        This is my headline!
    </div>
</div>

The result of combining the template and the loaded draft content is the above HTML, which will be loaded by the browser. At this point, the Storyblok JS Bridge will be loaded and initialized. Your part of the integration is already done by adding the HTML comments and from here on out the Storyblok JS Bridge will take over.

During this initialization the Storyblok JS Bridge looks for every HTML comment in your HTML. Each HTML comment starting with <!--#storyblok# will be parsed. The parsed JSON will then be used to add two HTML attributes data-blok-c and data-blok-uid and the class storyblok--outline to the HTML element right after the HTML comment.

<!--#storyblok#{\"name\": \"page\", \"space\": \"14141\", \"uid\": \"b370f32d-cd89-4dd3-9437-16b5e9746b31\", \"id\": \"172223\"}-->
<div class="content-type storyblok--outline" data-blok-c="{escapedJSONData}" data-blok-uid="b370f32d-cd89-4dd3-9437-16b5e9746b31">
    <!--#storyblok#{\"name\": \"hero\", \"space\": \"14141\", \"uid\": \"98b685a1-da10-4df2-837e-3429d5ea6f88\", \"id\": \"172223\"}-->
    <div class="blok storyblok--outline" data-blok-c="{escapedJSONData}" data-blok-uid="98b685a1-da10-4df2-837e-3429d5ea6f88">
        This is my headline!
    </div>
</div>

The class storyblok--outline will add a dotted border to your HTML element while hovering on your site in the Visual Editor Preview. Once you click on one HTML element the name of the blok will be added with a █ #09b3af colored border to show which Blok is currently selected.

In this process the Storyblok JS Bridge will also register the click EventListeners on your HTML elements that will open up the Story or Blok in the Visual Editor Content area.

Listen to the Visual Editor events

Events you can listen to in your own site using the Storyblok JS Bridge are events the Visual Editor sends through the Storyblok JS Bridge so you can react on content changes and UI actions. Some of the events sent to the Storyblok JS Bridge include a payload for you to use in your project.

// listen to a single event
window.storyblok.on('event_name', (payload) => {
    console.log(payload);
})

// listen to multiple events
window.storyblok.on(['event_name_1', 'event_name_2'], (payload) => {
    console.log(payload);
})

Example Event Usage: Change and Published

To get a new version of the content every time the Save or Publish button is pressed, listen to the change and published events and trigger a reload. You can also update your state manually by loading the content from the Content Delivery API.

// Listens on multiple events and does a basic website refresh
window.storyblok.on(['change', 'published'], () => {
  window.location.reload(true);
})

Example Event Usage: Input

To update the content in your project on input changes in the Visual Editor Content area even before the content is saved you can use the input event. The payload passed in the input event contains the updated Story you can use to update your projects content state in real time.

hint:

The content is not saved yet and therefore this does not give access to any Content Delivery API functionality such as resolve_relations or even the _editable property on Bloks. To enhance the received payload with at least the _editable properties we added the addComments to the Storyblok JS Bridge for you.


window.storyblok.on('input', (payload) => {
  // Current unsaved Story without _editable properties
  console.log(payload.story.content)

  // Add _editable properties to keep the Storyblok JS Bridge active after the content updates.
  let updatedStoryContent = window.storyblok.addComments(payload.story.content, payload.story.id)

  // Story object including _editable properties for each component.
  console.log(updatedStoryContent)

  // Use to update your projects content state 
})

Visual Editor Event Types

Event Name Will be emitted
input after a user changes the value of a field
change after the user saves the content
published after the user clicks publish
unpublished after the user clicks unpublish
enterEditmode after the editor has been initialized in the editmode
customEvent after a custom event was fired in a custom field type