How to Integrate Storyblok Visual Editor with Magento 2

Storyblok is a great choice to integrate a Headless CMS into Magento 2 eCommerce stores. It can be used as an alternative to Magento Commerce's Page Builder as it provides all of its features and it allows for a more pleasant developer experience when it comes to creating custom blocks.

By integrating Storyblok to help manage your content, you will instantly benefit from the following features:

• Pages with Visual Editor
• Editable Sections
• Custom Fields
• Internationalisation Support
• Content Scheduling, and more!

See how easy it is to start using Storyblok with Magento 2.

Please watch the following video if you would love to see the demo of the solution and hear directly from the author what are the benefits of this approach.

Requirements

The module only lists Magento 2.4 in the Magento Marketplace but it does work with Magento 2.3 as long as it’s running PHP 7.3 or later. You can also install it directly from Packagist.

Before we start

Before starting, you’ll need to create an account in Storyblok. You can use their free tier at first, but you will definitely want to upgrade to one of their paid plans if you want to use the more powerful features.

After creating your account make sure to create a new space so you can start configuring the module in the Magento admin area.

Installation

You can install the Storyblok Integration the same way as any other Magento 2 module, in the project root run:

        
      composer require medialounge/magento2-storyblok-integration
php bin/magento setup:upgrade
    

Configuration

There are only 3 settings you will need to setup after installing the module, you can access them by going to Stores → Configuration → Media Lounge → Storyblok:

Enable

Whether the module is enabled or not.

API Key (required)

Storyblok API Key, you can get it from your Storyblok space by going to Settings → API-Keys. Make sure the "Access Level" is set to "preview".

Webhook Secret (required)

Random string that will be used to authenticate requests coming from Storyblok, it’s recommended to use a 20+ characters alphanumeric string.

After this is set, make sure to use the same value in your Storyblok Space by going to Settings → General → Webhook secret.

Also, make sure to add your Magento 2 website URL in Settings → General → Location so you are able to preview it on Storyblok.

Creating your first page

With the module configured you can start creating content in Storyblok. Go to Content → + Entry and give it any name you want.

At first the page will look rather empty, but you should be able to see a live preview of your Magento 2 website in the Storyblok Visual Editor.

Creating your first block

Now for the fun part! Create your first block- you’ll use one of the default Luma banners as inspiration to make it reusable across our site.

You can structure the block’s schema in a few different ways, but to showcase some of the Storyblok Integration module features, make it with the following:

1. Background Image: Asset
2. Title: Text
3. Content: Richtext
4. Button: Block (we’ll come back to this later)

After creating your Banner block, it should look something like this:

Because there isn’t a template for this block, you end up with a debug message with all the data that is available, as well as the path where it expects the PHTML template file to be in, so you just need to create a new file in your custom theme.

        
      <?php /** @var MediaLounge\Storyblok\Block\Container\Element $block */ ?>

<div class="block-promo">
    <img 
        src="<?= $block->getImage()['filename'] ?>" 
        alt="<?= __('New Luma Collection') ?>"
    >
    <div class="content">
        <?= $block->getTitle() ?>
    </div>
</div>
    

Inside this template you have access to the Storyblok fields as part of the block's data, so you can access them by using the $block->getData('field_name') method or magic methods if you prefer $block->getFieldName().

At this point you can see a live preview of our new block’s content:

It still looks rather plain but you can match the original Luma styles with some CSS:

Helper Methods

To help render some special fields, the Storyblok Integration module includes a couple of helper methods.

$block->renderWysiwyg(array $arrContent)

When using "Richtext" fields, this method will ensure that HTML elements are rendered.

In this example, use it to render the “Content” field’s data:

        
      <?php /** @var MediaLounge\Storyblok\Block\Container\Element $block */ ?>

<div class="block-promo">
    <img 
        src="<?= $block->getImage()['filename'] ?>" 
        alt="<?= __('New Luma Collection') ?>"
    >
    <div class="content">
        <?= $block->getTitle() ?>
        <?= $block->renderWysiwyg($block->getContent()) ?>
    </div>
</div>
    

$block->transformImage(string $image, string $param = '')

Storyblok offers an Image Service that allows you to transform an image's size, format, and quality, plus many other things. This method provides a convenient way of interacting with it so you are able to modify images on the fly.

In this example, you can use it to ensure that your image is always at most 1280x460 pixels in size. Go even further by resizing your image down to 768x768 pixels for smaller screens and using the smart cropping option to make sure faces are used as a focal point.

        
      <?php /** @var MediaLounge\Storyblok\Block\Container\Element $block */ ?>

<div class="block-promo">
    <picture>
        <source
            srcset="<?= $block->transformImage($block->getImage()['filename'], '1280x460') ?>"
            media="(min-width: 768px)"
        >
        <img
            src="<?= $block->transformImage($block->getImage()['filename'], '768x768/smart') ?>"
            alt="<?= __('New Luma Collection') ?>"
        >
    </picture>
    <div class="content">
        <?= $block->getTitle() ?>
        <?= $block->renderWysiwyg($block->getContent()) ?>
    </div>
</div>
    

So far, your Banner block should look something like this:

Nesting blocks

One of the best things about Storyblok is that it allows you to nest individual blocks into each other, and the Magento 2 Integration module supports this feature as well.

Put this into practice by making the button in your banner a standalone block. Repeat the same process as before and create a new Button block with the following schema:

1. Text: Text
2. URL: Link

        
      <?php /** @var MediaLounge\Storyblok\Block\Container\Element $block */ ?>

<a href="<?= $block->getData('url')['cached_url'] ?>">
    <?= $block->getText() ?>
</a>
    

After adding some CSS you should be able to use your new button as a standalone block in the Storyblok Visual Editor:

To use it on your banner block, you need to edit its schema and include a new field with a type of Block. This lets you nest any kind of block inside your banner.

For this example, restrict this field a bit more. You can make it so that only one component is allowed (the Button block), and also prevent multiple buttons from being added.

Finally, you need to edit your banner block template to specify where you want nested components to render. Do this by using Magento’s $block->getChildHtml() method.

        
      <?php /** @var MediaLounge\Storyblok\Block\Container\Element $block */ ?>

<div class="block-promo">
    <picture>
        <source
            srcset="<?= $block->transformImage($block->getImage()['filename'], '1280x460') ?>"
            media="(min-width: 768px)"
        >
        <img
            src="<?= $block->transformImage($block->getImage()['filename'], '768x768/smart') ?>"
            alt="<?= __('New Luma Collection') ?>"
        >
    </picture>
    <div class="content">
        <?= $block->getTitle() ?>
        <?= $block->renderWysiwyg($block->getContent()) ?>

        <?= $block->getChildHtml() ?>
    </div>
</div>
    

This way your new button block will be rendered just under the banner’s content.

From here on out, it's just a matter of repeating the same process for all custom blocks. And by adding some CSS and JS, you can create either simple or very complex layouts using the Storyblok interface.

Publishing your page

So far you’ve been previewing your changes within Storyblok, but once you’re happy with your page’s look and feel, you can make it available in the Magento 2 website by clicking the Publish button in the top right.

Final Thoughts

That’s how easy it is to manage content in Magento 2 using Storyblok! There are many more features available in the Integration Module that can be used to take your eCommerce shop to the next level.

If you want to know more, look through the README in the public GitHub repo.