How to migrate from Panelizer to Layout Builder

We have been hard at work developing a migration path from Panelizer 4, which is the layout system used by Lightning, to core's Layout Builder. It's finally ready to be tested.

The important word there is "tested". The migration has automated test coverage, of course, but it hasn't really been tested in the wild yet. That means you, brave soul, are in somewhat uncharted territory -- and more importantly, it means there is a risk of data loss. This migration modifies both content and configuration of your site, so before running it, you should absolutely, positively, back up your database and configuration. And even if the migration appears to complete without errors, you should verify that your content continues to look and work the way you expect it to.

If something goes wrong (aren't you happy you made a backup first?), post an issue into the Panelizer issue queue, under the 8.x-5.x version, describing your problem in as much detail as you can manage.

Two more caveats:

  • This requires Drupal 8.8 and later. It will not work on an older version of Drupal core.
  • This migration path does not yet support translated content. Panelizer's support for translations is sketchy as it is -- and Layout Builder's is still a work in progress -- so migrating translated content from Panelizer to Layout Builder may have wildly unexpected results. If you do try it, whether it went well or poorly, let us know how it went.

Now, then, I've warned you enough. To run the migration:

  1. Explicitly require Panelizer 5 in your project, like so: composer require drupal/panelizer:^5.0. If you are using Lightning 4.1.0 (8.x-4.100) or later, you might want to run composer update first to get the latest version of Lightning Layout.
  2. Add the Core Context and Layout Builder Library modules as well: composer require drupal/core_context drupal/layout_library
  3. Ensure that Layout Builder is installed. ;)
  4. Visit the "Manage display" page of any panelized content type (or other entity types, if you are using Panelizer on them).
  5. You should see a button that says "Migrate to Layout Builder". Press it.
  6. Read the confirmation page carefully. (Spoiler: it will strongly recommend that you back up your database.)
  7. Press the "I understand the risks and have backed up my database. Proceed!" button.

Repeat the last four steps of this process as needed for every panelized entity type on your site until everything is using Layout Builder.

Before you ask: there is currently no way to automate this process. Because this migration is not proven yet, we purposefully want you to click through the UI and accept the warning. Every time. When the worst bugs have been ironed out, we can look into some form of automation. But now isn't the time.

That's pretty much everything you need to know about this for now. We wish you godspeed! See you, hopefully, in Layout Builder land. :)

Powered by Drupal Lightning