Title: A plan to ease transition to block-based themes Author: Ari Stathopoulos Published: February 19, 2020 --- [ ](https://profiles.wordpress.org/aristath/) [Ari Stathopoulos](https://profiles.wordpress.org/aristath/) 9:46 am _on_ February 19, 2020   # A plan to ease transition to block-based themes 2 weeks ago we had [our first meeting for the future of WordPress themes](https://make.wordpress.org/themes/2020/02/05/block-based-themes-chat-summary-5-feb-2020/), also known as blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.- based themes. In that meeting, we discussed how future themes will be structured and touched on the way they can be built. The future is bright, but there are thousands of themes that are not built as block- based themes. These will continue to function properly for years, WordPress has always been a platform that embraced backwards-compatibility and very rarely (if ever) deprecates functionality. It is inevitable that some existing themes will want to take advantage of the new structure and benefits that Full Site Editing has to offer. The problem is that it is a significantly different implementation to what we currently use, and there is no easy way to transition to that new structure. This is where this post comes in: Figuring out a plan to ease the transition to block-based themes in a way that makes sense. Start a discussion with theme-authors and find a way to move forward. Current WordPress themes use PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. [https://www.php.net/manual/en/index.php](https://www.php.net/manual/en/index.php) templates and a lot of settings in the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. to define colors, typography options, settings that change the markup of some areas etc. Future themes, however, will not have PHP templates. Instead, templates will be defined in `.html` files containing a “ preset” for how blocks will be arranged on the screen. Users will be able to override these “presets” and edit them in their editor. Most of the Customizer’s duties will be handled by the global-styles implementations currently being worked-on in GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/). So, how do we ease migrating from hardcoded PHP templates to a blocks structure? As a first idea, we have started experimenting with code that will allow authors to define an upgrade path. So if they have a simple headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. that has the following components: * Green background * White text * Site-logo on the left * Navigation on the right then that could be translated to the editor as a group block with green background and white text, containing 2 columns; In the 1st column we can have the site-logo block and on the 2nd column a navigation block. A theme author wanting to transition to a blocks-based structure would do something like this: ```notranslate /** * Return markup with blocks. * * Takes existing settings and migrates them to a blocks structure. * * @return string */ function mytheme_get_header_blocks_migration_markup() { // Open group block. $open_group = '
'; // Open columns block. $open_columns = '
'; // Build 1st column. $first_column = '
'; // Build 2nd column. $second_column = '
'; // Close columns & group. $closer = '
'; return $open_group . $open_columns . $first_column . $second_column . $closer; } // Migrate header template-part. new \WPTRT\Blocks_Migration( [ 'content' => mytheme_get_header_blocks_migration_markup(), 'slug' => 'header', ] ); ``` The above code is a simple and incomplete example, but it does show the basis of this idea: We created the structure we needed in the editor using coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks. Then we switch our editor from “Visual Editor” to “Code Editor”, and we have our blocks code there. We can take that code, put it in a function and replace the variables we need. In our case that meant using the header_background and header_text_color settings, retrieved using `get_theme_mod()`. In our example theme we can then remove these settings from the Customizer since they will now be controlled from the blocks. After the author creates the blocks-based markup, they can call the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. class. When this class runs in our example, it will do the following: 1. Check if there is a template-part with the slug we have defined. 2. If a template-part with that slug exists, then exit early, there’s nothing to do here since either the user has created their own header (in which case we don’t want to overwrite it), or the migration has already run. If a template-part with the defined slug does not exist, then move on to the next step. 3. Create a new template post (that is a post in the templates custom post-type that full-site editing will use), and add the contents in there. Once the migration script creates the `header` template-part post, that is going to override the “preset” `.html` template that we have in our theme. When a user first installs the theme (new installations), they will use the preset (which will contain the defaults and is a basis which users can then customize).When a user upgrades their installation to the blocks-based version, the theme will retrieve their Customizer settings, build the markup based on what the author has written and created the post which will override the “preset”. Most things that themes use already exist as blocks in core, or are getting added to make the Full-Site Editing easier. But there will be things that cannot be directly ported.One of these things is widgets. Since core widgets already exist as blocks, it is possible to translate them to that new structure. However 3rd-party widgets that don’t exist as blocks will not be easy to be auto-detected and translated. So far we are running some tests with simple structures and we can say that it is possible to build something to ease transitioning existing themes to block-based themes. But before we start building a proof of concept implementation that we can iterate on and experiment with, we need your assistance and feedback. **What are the things that you feel Full-Site editing would need to have in order for theme-authors to be able to build themes?** If you have ideas on how to ease the transition from widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user.-areas to blocks, we’d love to hear them. Other than non-core widgets, do you foresee issues with converting existing themes to block-based? ### Share this: * [ Threads ](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?share=threads) * [ Mastodon ](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?share=mastodon) * [ Bluesky ](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?share=bluesky) * [ Facebook ](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?share=facebook) * [ X ](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?share=x) * [ LinkedIn ](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?share=linkedin) * [Login to Reply](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fthemes%2F2020%2F02%2F19%2Fa-plan-to-ease-transition-to-block-based-themes%2F%23respond&locale=en_US) 1. ![](https://secure.gravatar.com/avatar/df6d683d02028cc7aba2c5a7e00eea1270a4c887caf63fd0e32090065ab94713? s=32&d=mm&r=g) 2. [Patryk Kachel](https://profiles.wordpress.org/limestreet/) 10:32 am _on_ February 19, 2020 3. The biggest question to me is why? Why do we need to migrate old themes? Why we can’t just start creating new blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based themes? 4. * ![](https://secure.gravatar.com/avatar/471c510b2590bce99d5e41cc9b817f0c0d420f08d0930e70b18299f993ffa965? s=32&d=mm&r=g) * [Ari Stathopoulos](https://profiles.wordpress.org/aristath/) 11:21 am _on_ February 19, 2020 * Of course you can start building new blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based themes, and there is no _need_ to migrate old themes. However, some people/businesses have invested years building their themes and their brand. These people will probably want to make the transition to block-based themes without losing their current user-base. There is no _need_ to transition to block-based themes. But there is (or rather will be since block-based themes are still a WIP and experimental) the **desire** from many theme-authors to do so, and it is our responsibility and privilege to help. * ![](https://secure.gravatar.com/avatar/e35e5f7ab928a5cbac804de6f32e936d6f49ed1c42464ea1d1842ef5e3960577? s=32&d=mm&r=g) * [Nick Cernis](https://profiles.wordpress.org/modernnerd/) 1:10 pm _on_ February 19, 2020 * It’s great to see work on a migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. process. Thanks for sharing these ideas, for the proposed migration APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., and for reaching out for feedback. It’s great that this is being developed in the open. * **New themes vs upgrades** I’m from the Genesis team, and — even though it’s early days and we’re still making plans for full site editing — our current migration path centered around installing new blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-based themes with full site editing support, rather than upgrading existing themes. * It’s not realistic for theme developers to promise users that we’ll be able to map existing theme sections and hard-coded PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. [https://www.php.net/manual/en/index.php](https://www.php.net/manual/en/index.php) templates to blocks in the way this post proposes. * We cannot say, “we’ll migrate your templates automatically” because users edit their themes directly (by editing the source) and indirectly (via parent themes, plugins, the Additional CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. section, and more). * At best, theme developers can only hope to map the original theme structure to blocks. We can’t guess how that content may have been edited or modified externally, so any migration callbacks may not be true to the current state of the site. * **What if users could be guided through the migration instead?** Is there a genuine need for an upgrade and migration path at the theme level where theme developers attempt to auto map content to blocks? Or could the migration path look more like: - Theme authors create new themes with `full-site-editing` theme support. - Users switch to that theme. - A “Welcome to Full Site Editing” page educates the user about what’s new and how they now edit parts of their site. This could display a list of widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. areas from their old theme and explain how to migrate them to block areas. - We provide tooling to import widgets into block areas where possible, and prompt users to do this from the “Welcome” page, and when they first edit a block template or template part. * This has several benefits: - It gives control to users. - It teaches users how full site editing works at a time when they care to have that info (“I’ve just switched theme; how do I edit parts of my site now?”). - It reduces the burden on theme developers to provide a magical migration path and to support automated migrations that go badly. - It gives the WordPress community a consistent migration story: “to get started with full site editing, switch to a theme with full site editing support and follow the guide at Dashboard → Full Site Editing”. - Theme authors don’t have to maintain a single codebase with support for “ classic” sites and full site editing. (There are several challenges with this, like providing documentation for both user types, and for trying to develop and maintain approximate feature parity between the two models that now live as one mutant theme.) * It has some downsides too: - The user may have to do more work and be willing to learn. (At least by making this a theme switch instead of a theme upgrade, they may be more educated about the differences. They won’t upgrade a WP.org theme as part of general maintenance and suddenly learn that everything has changed and they no longer know how to edit their site.) - The site may not display as it originally did while the user is migrating widgets and other areas. - Can a WP.org theme dev with a non-block based theme create a new block-based one while maintaining the old one, but keep the theme name if they choose to? (Or would they be forced to create a new name and slug for their block- based theme?) * Overall, though, users know better than theme developers how they want their website to look and function. If the purpose of full site editing is to give users full control over their sites, let users have full control of their sites, starting with the migration process. - ![](https://secure.gravatar.com/avatar/471c510b2590bce99d5e41cc9b817f0c0d420f08d0930e70b18299f993ffa965? s=32&d=mm&r=g) - [Ari Stathopoulos](https://profiles.wordpress.org/aristath/) 3:52 pm _on_ February 19, 2020 - Guiding users through the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. process does make a lot of sense. Thank you for sharing your insights 🙂 5. ![](https://secure.gravatar.com/avatar/68fdf8f2bf1291b0613bd23171116349078aed3bc1d8a1843b16f263d2b5d4ca? s=32&d=mm&r=g) 6. [epiqueras](https://profiles.wordpress.org/epiqueras/) 3:23 pm _on_ February 19, 2020 7. This is a good idea, but I’d be careful with stabilizing an APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. like this until we have a much better understanding of theme needs in the wild. 8. Non-supported widgets can use the Legacy WidgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.. 9. * ![](https://secure.gravatar.com/avatar/471c510b2590bce99d5e41cc9b817f0c0d420f08d0930e70b18299f993ffa965? s=32&d=mm&r=g) * [Ari Stathopoulos](https://profiles.wordpress.org/aristath/) 3:50 pm _on_ February 19, 2020 * > This is a good idea, but I’d be careful with stabilizing an APIAPI An API > or Application Programming Interface is a software intermediary that allows > programs to interact with each other and share data in limited, clearly defined > ways. like this until we have a much better understanding of theme needs > in the wild. * So far it’s just an idea, we wanted to get feedback from the community before we commit to something like this. It’s not so much an API… more like a simple class that will do the following: - Check if a post in the defined post-type exists with the slug we want to create - Add a new post in the templates post-type if it doesn’t already exist, with the content that authors define. * That’s all… The theme-authors will be responsible for actually writing the contents of the migrated templates, and that will be the same no matter what happens. I mean in 90% of themes the “copyright-area” in the footer can be interpreted as a group blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. with a background-color and a paragraph block inside that, usually with text coming from a customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. option. * Of course it’s too soon to tackle headers etc, things are still very fluid. But we can start thinking of ways to implement things and be prepared 🙂 * > Non-supported widgets can use the Legacy WidgetWidget A WordPress Widget > is a small block that performs a specific function. You can add these widgets > in sidebars also known as widget-ready areas on your web page. WordPress > widgets were originally created to provide a simple and easy-to-use way of > giving design and structure control of the WordPress theme to the user. block. * I must have missed that one, I didn’t even know it existed. That’s perfect! 10. ![](https://secure.gravatar.com/avatar/e960359a54d96235c26ea46d311b20fc47c77c5a15050e9d6a7d742e075fa9dc? s=32&d=mm&r=g) 11. [Dovy Paukstys](https://profiles.wordpress.org/dovyp/) 4:35 pm _on_ February 19, 2020 12. This needs to live in text files based in the theme. Encoding the string inside the PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely- used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. [https://www.php.net/manual/en/index.php](https://www.php.net/manual/en/index.php) will get real messy fast. If there were also a built-in way to update these blocks via GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/), then devs/designers could test and save the blocks out. 13. Without this, it will become just as riddled with pain as the current template process. 14. * ![](https://secure.gravatar.com/avatar/471c510b2590bce99d5e41cc9b817f0c0d420f08d0930e70b18299f993ffa965? s=32&d=mm&r=g) * [Ari Stathopoulos](https://profiles.wordpress.org/aristath/) 5:36 pm _on_ February 19, 2020 * Oh definitely… In most cases it’s likely it will simply use the `.html` templates that themes will have anyway. The snippet posted was simply an example to convey the logic, not an actual implementation. 🙂 ### Leave a Reply 󠀁[Cancel reply](https://make.wordpress.org/themes/2020/02/19/a-plan-to-ease-transition-to-block-based-themes/?output_format=md#respond)󠁿 You must be [logged in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fthemes%2F2020%2F02%2F19%2Fa-plan-to-ease-transition-to-block-based-themes%2F&locale=en_US) to post a comment. This site uses Akismet to reduce spam. [Learn how your comment data is processed.](https://akismet.com/privacy/) # Post navigation [← Block-based Themes Meeting Agenda for February 19](https://make.wordpress.org/themes/2020/02/17/block-based-themes-meeting-agenda-for-february-17/) [Block-Based Themes chat summary: 19 Feb 2020 →](https://make.wordpress.org/themes/2020/02/20/block-based-themes-chat-summary-19-feb-2020/)