Craft 5: What It Means For Super Table Page Builders
Super Table has reached end-of-life. But don't worry – Craft 5 can help you migrate.
If you’re like us, you’ve likely built ‘page builder’ fields in Craft CMS using Matrix. But sometimes you need more than a block. We use Super Table to create ‘page sections’ that include some extra settings (like background color, controls for width, etc.). We can then nest a Matrix field to control page blocks within the Page Section (Super Table). This has worked well for us in the past but there's a new, simpler way to achieve this starting in Craft 5.
Upgrading a site from Craft 4 to Craft 5 can seem intimidating. Even more so when your site relies on complex content models like the one I described above. You might think, okay I'll upgrade to Craft 5 and then look into migrating to the newer method in the future. Well, now is the time. Verbb has announced that Super Table has reached end-of-life. While there is a Craft 5 compatible version available, it won't receive updates. That means now is the perfect time to migrate your Super Table fields to native Matrix fields.
Craft 5 makes the process easy by converting Matrix blocks to entry types automatically during the upgrade. This guide will walk you through the process. We'll cover preparation, the upgrades themselves, and steps to clean up afterward. As you’ll see below, the process is actually quite simple and nothing to stress over!
Preparing for the Upgrade
The first step in any upgrade is preparation. Start by backing up your site’s database. This ensures that you can restore your site to its previous state if anything goes wrong during the upgrade process. We use (and love) DDEV here at Viget, so this guide will be leveraging it. But you can easily adapt the commands if you are not. To create a database backup, run:
❯ ddev snapshot
Next, review the compatibility of your installed plugins. Check the Plugin Store or the author’s site to confirm that each plugin has a Craft 5 compatible version. Make a list of any plugins that need updating or replacing. Super Table will need to be updated to at least version 4.0.0.
It's also essential to familiarize yourself with the Craft 5 Upgrade Guide. This guide provides detailed information on the changes, new features, and potential breaking changes in Craft 5, helping you understand what to expect. It serves as a fantastic set of instructions to get your site upgraded.
The Upgrade Process
Once you're prepared, you can begin the upgrade process. Per the Craft Upgrade Guide, we will update Craft and plugins at the same time. Open your editor and modify your composer.json with the new versions of your plugins. The two for sure we will need to modify are:
"craftcms/cms": "^5.0.0",
"verbb/super-table": "^4.0.0",After you've checked all your versions and are ready to proceed, run:
❯ ddev composer update
This command will update Craft (and its dependencies) and all your plugins to the latest version compatible with Craft 5. After updating, you need to run the database migrations to complete the upgrade. This can be accomplished by running:
❯ ddev craft up
During this upgrade process, Craft 5 automatically converts all of your existing Matrix blocks to entry types. This conversion requires no interaction from you, streamlining one of the most complex aspects of the upgrade. After it’s finished, all of your non-reusable matrix blocks are now their own reusable entry type.
Updating Super Table Fields and Templates
With the Matrix blocks converted to entry types, you need to reconfigure any Super Table fields to be Matrix fields.
Update Super Table Fields:
- Browse to Settings > Fields and edit any Super Table fields
- Change the field type from Super Table to Matrix (there will be no content loss when switching from Super Table to Matrix)
- Select the entry type to use (Craft has already created one for you)
- Save the field
- That's it!
Review Your Templates: #
If you've been working with Super Table content as part of entry queried data, you may not need to make template changes at all
Search your templates for
craft.superTableto find any direct queries of Super Table blocks and replace them with entry queries
At this point, you have removed your dependency on Super Table and have a page builder entirely built with Matrix fields. What were previously Super Table blocks are now a custom Entry Type and what were Matrix blocks are now also Entry Types. This allows you to have nested Matrix within Matrix thanks to Craft’s Entrification plan.
Cleaning Up After the Upgrade
After updating your fields and templates, it's time to clean up. First, uninstall the Super Table plugin. Navigate to Settings > Plugins in the Control Panel to uninstall the plugin. Then remove it from your project by running:
❯ ddev composer remove verbb/super-table
Thoroughly test your site to ensure everything is functioning correctly. Pay close attention to the entry types where you used Super Table fields, confirming that authoring and your front-end work as expected.
Additionally, you can also take this opportunity to clean up your fields and entry types. Craft 5’s reusable fields and entry types give you ample opportunity to consolidate and Craft 5 provides new utilities to make this process as simple as possible.
- fields/auto-merge — Automatically discovers functionally identical fields and merges their uses together.
- fields/merge — Manually merge one field into another of the same type and update uses of the merged field.
- entry-types/merge — Merge one entry type into another and update uses of the merged entry type.
That’s it!
Upgrading from Craft 4 to Craft 5 and transitioning from Super Table is incredibly simple, thanks to Craft 5’s automatic conversion of Matrix blocks to entry types. Super Table will no longer be maintained moving forward, and it's better to switch to the native Craft solution for better long-term support. By following these steps, you can quickly tackle the change and take advantage of the new features and improvements in Craft 5. With careful planning, thorough testing, and a few commands, you’ll have your page builder working again in Craft 5 in no time. Happy upgrading!
