The Storyblok Bridge

To build a bridge between Storyblok and your website there needs to be included a script on your page. This script will communicate via iframe with Storyblok to tell the editing interface which component needs to be opened when the user clicks on it.

This is done using a simple HTML comment before that element which is shipped in the draft json by adding the key _editable to each component.

Include the script inside your <body> tag

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

You can get see the preview token (= YOUR_TOKEN) at the dashboard of your space. You can also conditionally exclude the script tag if the user is not in the editmode.

Methods to check for the editmode:

  • Check for the url parameter _storyblok
  • Check for a cookie (You could set a cookie the first time the url has _storyblok in it)

Usage

For a server rendered website the following code will reload your website as soon the user saves or publishes a story.

// Optionally init if you have not provided the ?t parameter to the script tag already.
storyblok.init({
  accessToken: 'your_public_token'
})

storyblok.on('change', function() {
  location.reload(true)
})

storyblok.on('published', function() {
  location.reload(true)
})

storyblok.pingEditor(function() {
  if (storyblok.inEditor) {
    storyblok.enterEditmode()
  }
})

Events

You can listen to events calling the on handler:

storyblok.on('event_name', function(data) {
     console.log(data);
})

For the published event this would look like:

storyblok.on('published', function(data) {
     console.log(data);
    // invalidate cache, ...
})

For the app “Sync Button” there is a special event you can listen to:

storyblok.on('customEvent', function(data) {
    if (data.event == 'start-sync') {
        // Do sync
    }
})
EventWill be emitted
changeafter the user saves the content
publishedafter the user clicks publish
unpublishedafter the user clicks unpublish
enterEditmodeafter the editor has been initialized in the editmode
customEventcustom event used by third party plugins

Functions

storyblok.init(config)

config Object

  • accessToken String: The private token of the Content Delivery API to receive draft versions of content. You can find it in your space dashboard at https://app.storyblok.com.

Example

storyblok.init({
  accessToken: 'xf5dRMMjltLzKOcNgMaU9Att'
})

storyblok.isInEditor() and pingEditor()

With this functions you can check if your user has opened your page inside Storyblok.

Example

storyblok.pingEditor(() => {
  if (storyblok.isInEditor()) {
    // getStory('draft')
  } else {
    // getStory('published')
  }
})

storyblok.get(query, success, error)

Get a single content entry in the frontend.

  • query Object
    • version String: ‘draft’ or ‘published’. Default is ‘published’
  • success Function: Success callback
  • error Function: Error callback

Example

storyblok.get({
  slug: 'home', 
  version: 'draft'
}, (data) => {
  var story = data.story
})

storyblok.getAll(query, success, error)

Get multiple content entries

  • query Object
    • with_tag, String
    • starts_with, String
    • version, String
    • sort_by, String
    • filter_by, String
    • per_page, String
    • page, String
  • success Function, Success callback
  • error Function, Error callback

Example

storyblok.getAll({
  version: 'draft'
}, (data, xhrResponse) => {
  var total = xhrResponse.getResponseHeader('Total')
  var stories = data.stories
})

How to validate if the user is viewing your site in the Storyblok editor?

If the user opens your page in Storyblok we add a few parameters which you can use to securely validate the edit mode.

You will need that validation to load the right version of your content to the right users. The draft version is for the editor and the published version for the public.

A simple validation would be to check if there is the _storyblok parameter in url. This could be done in the frontend or in the backend. But for a secure check we recommend to implement the logic in the backend and validate the _storyblok_tk parameter.

Here are some examples how to check securely if the user is in edit mode:

import crypto from 'crypto'
// getQueryParam = access requests URL param by name

let validationString = getQueryParam('_storyblok_tk[space_id]') + ':' + YOUR_PREVIEW_TOKEN + ':' + getQueryParam('_storyblok_tk[timestamp]')
let validationToken = crypto.createHash('sha1').update(validationString).digest('hex')
if (getQueryParam('_storyblok_tk[token]') == validationToken && 
    getQueryParam('_storyblok_tk[timestamp]') > Math.floor(Date.now()/1000)-3600) { 
    // you're in the edit mode.
    this.editMode = true 
}
$sb = $app['request']->query->get('_storyblok_tk');
if (!empty($sb)) {
    $pre_token = $sb['space_id'] . ':' . YOUR_PREVIEW_TOKEN . ':' . $sb['timestamp'];
    $token = sha1($pre_token);
    if ($token == $sb['token'] && (int)$sb['timestamp'] > strtotime('now') - 3600) {
        $app['config.storyblok.edit_mode'] = true;
        // you're in the edit mode.
    }
}

This are the parameters Storyblok appends to your url:

ParamDescription
_storyblokthe content entries ID
_storyblok_tk[space_id]the space ID
_storyblok_tk[timestamp]a timestamp
_storyblok_tk[token]a validation token. Combination of space_id, timestamp and your preview_token

Documentation