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
Content Scheduling, and more!
See how easy it is to start using Storyblok with Magento 2.
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.
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
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:
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.
If you have problems loading the website preview you might need to add ALLOW-FROM storyblok.com to your X-Frame-Options header. You can do this in your env.php file or in your web server configuration settings.
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:
Background Image: Asset
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.
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
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:
To help render some special fields, the Storyblok Integration module includes a couple of helper methods.
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:
$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.
So far, your Banner block should look something like this:
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:
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
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.
To make sure the Magento 2 Integration clears the page’s cache automatically, set the following URL in your Storyblok Space under Settings → General → Story published & unpublished and Datasource entry saved: http://yourmagento.url/storyblok/cache/clean
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.
|Storyblok Plugin in Magento Store||https://marketplace.magento.com/medialounge-magento2-storyblok-integration.html|
|Storyblok eCommerce Documentation||https://www.storyblok.com/docs/guide/integrations/ecommerce|