Storyblok Visual Editor Integration for Magento 2

Magento 2 Storyblok Integration

For a while now at Media Lounge we’ve been looking for the best solution to deliver a rich content driven experience that’s not only easy for store owners and maintainers to use but also for developers and agencies to build with and extend.

We’ve always found the current state of content management for Magento 2 very limited, if you’ve used Magento for a significant amount of time you’ll be familiar with some of these approaches:

CMS Pages

If you need to create a standalone page for your e-commerce store you will probably start with these. Magento provides a WYSIWYG editor powered by TinyMCE that lets us add almost any kind of HTML content that we want and, while this works fine for simple pages, it can become harder to maintain the more complex the page layout gets.

CMS Pages WYSIWYG

Editing content like this requires good knowledge of HTML and even that doesn’t solve all the problems. What if you need custom CSS or JS? What about variable content? You can’t even preview how the page is going to look like before saving it so it’s hard to fix mistakes without publishing the content first.

Static Blocks

Static Blocks (or just Blocks) can be very useful since they let us make sections of a page editable, this way we can extract the complex parts of the content to the Magento template (HTML, CSS, JS, etc) and only focus about the editable parts of the elements.

CMS Block

This is convenient but it doesn’t solve all problems, you will probably need to keep some HTML in the block still and splitting editable areas into multiple blocks can become dozens or even hundreds of blocks that will need to be managed, and the admin interface doesn’t make this easy.

Widgets

Widgets are Magento’s answer to some of the problems mentioned before, they let us abstract the complexities of editable content (HTML, CSS, JS, etc) behind an “easy” to use interface.

They were our go-to solution for most content editing needs but it always felt like the lesser of two (or in this case three?) evils, you still need a lot of boilerplate code to even get the simplest widgets to work and out of the box they only provide a handful of field types you can use.

Our custom “multi field” widget

A lot of our clients like content-rich e-commerce sites that are easy for them to edit and we felt that we were already pushing the limits of what Magento offers out of the box.

What about Magento Commerce’s Page Builder?

Magento Commerce’s Page Builder is a Magento extension for creating content, in a way it’s better than the solutions mentioned before as some of its key features are:

  • Drag-and-drop functionality for content creation.
  • Live previews of how the content will look on the storefront.
  • Form editors for entering and customising the content.

However there are still quite a few downsides that we didn’t like:

  • Magento Commerce only with no certainty of ever coming to Magento Open Source.
  • Lots of boilerplate even more so than widgets.
  • Using the default Magento frontend stack who likes Knockout and uiComponents??
Magento Commerce Page Builder

Because of this we decided to start looking outwards, there are some good alternatives out there in the form of Magento Extensions or third party services if you prefer the Headless approach, but after careful consideration we decided to use Storyblok as our content management solution.

Why Storyblok?

Storyblok allows you to manage content through a CMS that is intuitive, powerful, and easy to use. It offers a unique combination of visual editing tools and highly customisable content blocks on top of a modern headless architecture that gives you the flexibility to build fast and reliable content experiences.

While working entirely through their API, Storyblok gives integrators and developers total flexibility with the benefit of a dedicated and stand-alone best in class CMS.

Storyblok Visual Editor

Storyblok provides features comparable to Magento’s Page Builder:

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

The more we used it the quicker we realised Storyblok was better than any other content management alternative we had used in the past, it’s extremely easy for regular users and store owners to edit their website’s content without any code involved.

So we decided to create our own extension to integrate Storyblok’s Visual Editor with Magento 2 in a way that’s also very easy for developers to create and customise even the most complex of layouts.

Storyblok Integration for Magento 2

Our Magento 2 integration allows developers and digital agencies to create content-rich pages that are easily editable using the Storyblok interface. It can be used as an alternative to Magento Commerce’s Page Builder as it provides all of its features and, combined with our integration module, it allows for a more pleasant developer experience when it comes to creating custom blocks.

We tried to keep the integration as seamless as possible by sticking to “the Magento way” so you won’t need to learn any new concepts or technologies. Let’s see this in action with a quick example.

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

Installation

Our Storyblock Integration module is available in the Magento Marketplace so we can install it the same way as any other Magento 2 module, in the project root run:

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.

Creating our first page

After we install and configure our module we 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.

Visual Editor Preview

Creating our first block

Now for the fun part! Let’s create our first block. We’ll use one of the default Luma banners as inspiration to make it reusable across our site.

Luma Banner

We’ll need to create a new Block in Storyblok as well as assign it a Schema which is a fancy name to describe a set of fields.

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

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

So after creating our Banner block it should look something like this:

Initial Banner Block

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

MediaLounge_Storyblok/templates/story/banner.phtml

This template works the same way as any other template that extends the Magento\Framework\View\Element\Template block class.

In here we 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().

You may have also noticed a couple special Helper methods:

$block->renderWysiwyg(array $arrContent)

When using “Richtext” fields this method will ensure that HTML elements are rendered.

In our example we 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 image’s size, format, quality amongst other things. This method provides a convenient way of interacting with it so we are able to modify images on the fly.

In our example we can use it to enforce our image is always at most 1280x460 pixels in size.

After adding some CSS styles we should be able to see a live preview of our new block in Storyblok’s Visual Editor preview.

Banner Block Preview

Nesting blocks

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

We can put this into practice by making the button in our banner a standalone block, let’s repeat the same process as before and create a new Button block with the following schema:

  1. Text: Text
  2. URL: Link

MediaLounge_Storyblok/templates/story/button.phtml

After adding some CSS we should be able to use our new button as a standalone block in the Storyblok Visual Editor.

Button Block

Now to use it on our banner block we need to edit its schema and include a new field with a type of Block, this will let us nest any kind of block inside our banner.

For our example let’s restrict this field a bit more, we can make it so only one components is allowed (the Button block) and also prevent multiple buttons from being added.

Button Block Field

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

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

Banner Block with Button

From here on it’s just a matter of repeating the same process for all custom blocks and by adding some CSS and JS we can create from simple to very complex layouts using the Storyblok interface!

Full Visual Editor Demo

Editable Sections

We don’t need to use Storyblok just to manage content for a whole page, we can also use it to make specific sections within our pages editable. This can be useful when we need elements like header menus, footer links, product-specific promotions, etc, where we would normally use Static Blocks or Widgets.

First, we need to create a new Entry in Storyblok but instead of using the “page” content type you should choose to create a new one that better matches the content that you’re trying to create.

After this Storyblok will open the content type in the preview window as a regular page, this is NOT what we want but let’s ignore it. For now, define the schema as you normally would.

Next we want to tell Storyblok what page should be displayed in the preview, you can change this in the sidebar by going to Config → Real Path. This depends on the kind of content that you want to manage, eg: to display the homepage use /, for the cart page use /checkout/cart and so on. Save the change and reload the page.

We should now see the Real Path in the preview screen but our new block is nowhere to be seen yet. We need to tell Magento where we want our block to be displayed and this is done using regular Layout XML directives:

As long as we use MediaLounge\Storyblok\Block\Container as the block class and pass the Storyblok slug as an argument we can display custom blocks anywhere we want, in this example we chose to display it inside the footer container.

Editable Footer Block

Finally we just repeat the same process as before:

  1. Create the PHTML template
  2. Style content
  3. Publish

SEO

We wanted to make sure that our Storyblok Integration didn’t impact SEO negatively so we made sure to enable the same SEO features that native CMS pages offer out of the box.

Sitemap Integration

Our Storyblok Integration will automatically include pages in the Magento built-in sitemap generator so they can be indexed by search engines.

By default only pages with the Content Type of “page” will be included in the sitemap.

Custom SEO field

The “meta-fields” custom field is an example of an extra block that can be used in a Storyblok Space and our Magento 2 module provides support for it out of the box.

We can add our SEO field type as part of our page’s schema, make sure to select “Plugin” under the Field Type and “meta-fields” as the Custom Type.

Now the page’s title and meta description will be editable from Storyblok.

SEO Meta Fields Block

Custom Fields

On the subject of custom fields, one of the most powerful Storyblok features is that it gives us the power to extend fields with custom code to provide almost unlimited functionality that the built in fields might not give us.

Custom fields are built entirely on Storyblok’s end so there’s nothing special in our Integration Module to get them to work, you can create them as a plugin following their documentation and then use a Helper or ViewModel in the Magento side to parse the data in any way you want.

For example, we can create a custom field that uses the Magento GraphQL API to query products so we are able to search, paginate and select products from Storyblok to display as part of a Featured Products Block.

Magento Product Finder Custom Field

With custom fields the possibilities are almost endless!

Performance

We wanted to keep the Storyblok Integration module as lean as possible so its performance footprint on Magento 2 stores is very minimal. Out of the box our module doesn’t include blocks, in fact we don’t even add any extra CSS or JS to your Magento 2 store! We give you the freedom of customising your content any way you want using the technology stack of your choice.

We also use Magento’s cache tags to individually cache Storyblok content to avoid making unnecessary HTTP requests, and when this content is updated we only clear the cache tags for the affected blocks.

Try it yourself!

There’s a lot more features available in Storyblok that can be easily implemented using our Magento 2 Integration, we hope that you find it as useful as we have and if you have any issues feel free to report them in our official GitHub repository.

As mentioned before, you can get the integration module from:

If you want to know more make sure to read the Documentation or if you prefer the video format you can check out our YouTube playlist.

Lead Developer at Media Lounge · 6x Magento Certified & Full Stack Developer · E-Commerce Specialist · Currently @ Bournemouth, UK