In some of our previous articles we discussed preparation of websites for Gutenberg by testing existing content before even version 5.0 of WordPress was officially released. WordPress 5.1 is now here.
Since many of our customers contacted us to get help information about their transition to Gutenberg, we decided to describe the process we underwent on our blog step by step. Yes, we are big fans of WordPress and we use the CMS for developing our blog and our help page.
Our blog is used only for posting purposes and does not have any additional complex features or content variations. This makes preparation for the Block Editor easier than with a website having unconventional features or various types of content presented in different ways.
For more complex WordPress websites, the preparation for Gutenberg may require inspecting all other additional features of the Classic Editor, added by the theme and/or plugins. Additional features of the WordPress Classic Editor are more likely to be affected by the new Block Editor.
Step by step preparation of our blog
At the beginning, preparing our website for the transition to WordPress 5+ and Gutenberg seemed like a difficult and very challenging task. But it was not so scary after all, as we performed everything step by step:
- Preparation for testing Gutenberg
- Creating a staging copy of the blog
- Preparation of the staging copy
- Updating the CMS and plugins to the latest versions
- Activating a newer PHP version
- Creating a child theme
- Installing additional plugins
- Checking the existing content and CSS
- Checking the plugins and the theme
- Checking an existing article
- Checking meta data of the article
- Bugfixing on the blog
- Recreating the previously used custom field
- Adding the theme CSS to Gutenberg
- Updating some CSS
- Updating the guide for using CSS
System parameters while testing Gutenberg
We began testing the Block Editor on our blog from version 4.9.8 of WordPress when Gutenberg was still a plugin. Test results back then showed that the Block Editor was still not ready to be applied to our blog. However, the most recent tests we performed with WordPress 5.1 were successful and all issues we had previously detected with the Block Editor were resolved.
Here are the final system parameters during our most recent tests:
- WordPress 5.1 + Gutenberg (the built-in Block Editor)
- Activated Classic Editor v.1.4plugin
- Activated Advanced Custom Fields v.5.7.12plugin
- Activated PHP v. 7.2
- We avoided using page-builder plugins and themes providing additional features to the Classic Editor such as shortcodes.
- We used CSS, in the form of CCS classes.
1. Preparation for testing Gutenberg
Creating a staging copy of the blog
We prepared for testing by using a staging copy of the blog to avoid limiting the access for our readers.
The very first step was creating a staging copy of the website. This copy enabled us to freely perform all types of tests and checks without affecting the real blog in any way.
Creating a staging copy of our blog required having a suitable subdomain. The copy itself we created with just two clicks through cPanel » Staging.
Preparation of the staging copy
A staging copy is completely identical with the real blog with the slight difference that it is located on another domain.
Normally, the different domains would not prevent the proper functioning of the copy except for cases when it is used only for running a plugin. In our case only the WPML plugin used the website’s domain to provide updates. For this reason we registered the second domain in WPML so as to be able to update the plugin in the staging copy.
Also, we removed some unnecessary data from the staging copy database so that to avoid embarrassing situations. For example, we would not like to send an email notification to the subscribers to our blog in case we published an article while running the tests. So we removed subscribers’ data from the database of the staging copy.
1️⃣ Updating the CMS and plugins to the latest versions
We installed the latest WordPress v. 5.1 on the staging copy. Then updated all plugins to their latest versions. And removed all unnecessary data from the staging copy’s database.
2️⃣ Activating a newer PHP version
Preparing for Gutenberg is a convenient moment to also test a newer PHP version for your website. We enabled PHP 7.2 for the staging copy.
3️⃣ Creating a child theme
First we created a child theme and then we performed changes to its source code.
4️⃣ Installing additional plugins
We installed a few additional plugins on the staging copy:
- The Classic Editor so that we could try switching between the Classic Editor and the Block Editor.
- The Health Check & Troubleshooting plugin. This plugin checks the technical parameters of the website and provides information for the system, the plugins and the theme. In case of a problem with the theme or a plugin, the troubleshooting information from this plugin can be used for resolving the problem.
2. Checking the existing content and CSS
After the staging copy had been prepared we could dive into testing and checking.
Actually this article ended up as a test for the Block Editor since it contained 120 blocks and more than 80 paragraphs 🤓.
Checking plugins and the theme
By default each theme or plugin that does not add a feature to the Classic Editor is not affected by Gutenberg and is supposed to function as usual.
Our blog does not have plugins or themes which add features to the Classic Editor. For this reason the website’s proper operation and its design were not affected in any way by the Block Editor.
We activated a new PHP version for the staging copy so we performed a more detailed and thorough check of all plugins.
This included checking their settings, features and the website’s operation on the front-end. We also examined in details the plugins whose features were not displayed on the website such as the ones related to sending mails, redirections, inspecting for broken links and others.
After checking all plugins and the theme we did not observe any issues in their normal functioning, neither with the blog. Emails were sent, redirections worked smoothly. With the new PHP version 7.2 everything on the blog worked correctly.
Checking an existing article and the CSS
Real testing of the new Block Editor was performed by checking the already existing content on the website.
This is how we converted and transferred an already existing article to the new Block Editor:
- We opened the article in the Block Editor.
- Then converted its content into blocks.
- Next we saved it and previewed it on the front-end.
- We checked every block of the article in the Block Editor and documented each difference in the layout.
The already existing article, edited and saved into the Block Editor, was shown just like before on the blog’s front-end.
Upon editing the article we noticed that the style in the Block Editor was different than the one visible on the front-end. This was due to the fact that the theme used had not been configured to using Gutenberg.
So to reach “what you see is what you get” we needed to add the theme’s CSS to the Block Editor: ⚒ Fixing a problem on the blog: Adding the theme CSS to the Block Editor
Some CSS on the blog is used when combined with a style class and additional code to a specific HTML tag. Since we will not use code in the Block Editor in the future, we modified some of the theme CSS: ⚒ Fixing a problem on the blog: Updating CSS
If upon converting existing content into blocks there is a set CSS class such as p, a, li for a given HTML tag, Gutenberg will transfer it into the Additional CSS class option of the block. For this very reason we did not have to transfer the styles manually by copying and pasting into this option. For the new articles authors will place the style into the Additional CSS class option by using only its name instead of a whole piece of code like before.
For example, if until now the following code has been used: <p class=”stylename”>word</p>, from now on you will only place the style name into Additional CSS class. This required describing the CSS so as only its names and classes could be viewed. ⚒ Fixing a problem on the blog: Updating the guide for using CSS in articles
Checking meta data of the article
Upon checking meta data of the article which is placed in meta boxes below the content itself, we found out at an early stage from our tests that only custom fields were missing. Later we understood that this was due to the activated ACF plugin.
In a fresh WordPress installation the custom fields should be visible in the Block Editor after you activate the option under Settings » Advanced Panels » Custom Fields.
When publishing a new article, we needed to recreate one custom field as it had been used until that moment in the Classic Editor. Since the ACF plugin was already installed on our blog, we would use it to add the missing custom field to the Block Editor: ⚒ Fixing a problem on the blog: Creating а Custom Field
All other additional data from the article can be displayed, e.g. settings of All in One SEO, WPML and others.
3. Fixing problems on the blog
After all performed tests we needed to fix four main issues
- ⚒ Creating а Custom Field
- ⚒ Adding the theme CSS to the Block Editor
- ⚒ Updating CSS
- ⚒ Updating the guide for using CSS
⚒ Creating а Custom Field
In our blog we use only a single custom field to save image data when sharing the article on Facebook.
This field’s content is retrieved by the theme and is added to the HTML code of the page. The theme saves the field name as “fbImage” and looks for it in the database upon generating the final HTML code of the article.
Until then this field was used in the Classic Editor under the Custom Fields box below the article’s content.
This box was missing while we were testing the Block Editor, although we enabled the option in the editor settings. If the ACF plugin is enabled, the Custom Fields Box is not displayed in the Block Editor.
We could not deactivate this plugin since it is actively used on our blog. Instead, we are going to use it to recreate the missing custom field.
Upon creating the field in ACF we specified the name of the initial field which is stored in the database (wp_postmeta – meta_key). This way previously saved data will be displayed in the Block Editor and the new data in the database will contain the correct metakey.
After we created the field, it was displayed in the Block Editor in a box below the article’s content.
back to this section’s beginning 🔼
⚒ Adding the theme CSS to the Block Editor
For the article to have the same appearance as on the front-end of the website, while editing it in the Block Editor, we needed to add the theme’s CSS to the Block Editor. To add the CSS we needed to perform a slight modification of the theme’s source code.
It is highly recommended all the modifications and changes to be performed by a developer. If a change is required, we always recommend sending a request to the theme’s support team. If no other options are left, changes of the theme’s source code should be only performed on a child theme. You can create a child theme by using a plugin such as Child Theme Generator.
The option for changing the editor’s CSS is a special feature which is provided by the website’s theme. This option became available upon the release of WordPress 3.0. To use a specific CSS for the editor, we should specify the CSS file for the editor in the theme’s functions (functions.php), for example:
add_editor_style( 'style-editor.css' )For our blog’s theme we activated the CSS and the CSS file for the Block Editor by adding the following code to functions.php:
function mytheme_setup() {
add_theme_support( 'editor-styles' );
add_editor_style( 'style-editor.css' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );By using the add_theme_support option we enabled the feature for changing the Block Editor CSS and with add_editor_style we specified the file to be used in the CSS.
If up to now there was no CSS file for the editor, it should be created. The next step is placing some of the theme’s styles into style-editor.css.
We did not need to copy the whole content of the theme’s style file into the Block Editor’s CSS file. Upon testing content in the Block Editor you can easily view which style needs to be added.
In the editor’s CSS can be set and changed in the same way just like for the theme, for the front-end, only with slight differences. For example, the article’s heading can be also styled up in the Block Editor.
To change the font and size of the article’s heading in the Block Editor, in the file style-editor.css we used the following style class: “.editor-post-title__block .editor-post-title__input” instead “.single .post-content h1” that is used by the theme.
Changes and settings of the Block Editor’s CSS were performed by us as we used the official help documentation for Gutenberg: Theme Support.
The Block Editor loads the default CSS for the main blocks. For some of them there might not be a change required, but for others you might need to fine tune so as to match the theme’s CSS. E.g. heading font, size, color (h1,h2,h3…), maximum block width, quotes, horizontal line, paragraphs (p), lists (li), images (img), buttons, hyperlinks and all the other blocks for which the theme sets a specific CSS
Activating the editor’s CSS does not make the theme Gutenberg compatible, but only enables the Block Editor’s style to come closer to the front-end’s style. Themes that are fully compatible with the Block Editor use further options when creating content – additional block types, custom block settings, visual elements and layout.
Without fine tuning of the Block Editor styles, it is very likely to get a “what you see is what you get” on the front-end.
The Block Editor has its own style for the main blocks, for example, there is default spacing for paragraphs. This leads to a visible difference between the back-end and front-end layout of the article. With a little more fine tuning of the Block Editor CSS, however, you can make the article look exactly like before.
back to this section’s beginning 🔼
⚒ Updating CSS
Our blog has additional types of CSS which are applied through CSS classes. Up to that moment these styles were applied to the content through placing their code in the text mode.
To be able to keep using them, instead into the code, the style needs to be placed into the block (Additional CSS classes). This is actually a much easier way to set a style than messing up the article’s code like before.
Some CSS is used together with an additional style to HTML tags which makes it incompatible with the Block Editor. For this reason we needed to update and modify them in a suitable way.
E.g. the style for the tipsupport box contains a different font in italics.
This box can be added to the Classic Editor by placing the following code:
<div class="tipsupport">
<em style="color:#666666;font-family:'Trebuchet MS',Verdana,sans-serif;font-size:16px;"><strong>Tip:</strong></em>
To continue...
</div>Which looks in the following way in the Text Editor:
To avoid manually adding code into the tag, we added the following code to the style:
.tipsupport em {
color:#666666;
font-family:'Trebuchet MS',Verdana,sans-serif;
font-size:16px;
}This way placing CSS code to the HTML tag em is avoided in editing mode of the Block Editor.
When you perform changes in the theme’s CSS you have to make the same changes in the CSS file of the Block Editor.
back to this section’s beginning 🔼
⚒ Updating the guide for using CSS
To make choosing a style for the article while it is being edited more easily, you can create a draft which contains all possible CSS styles.
This way authors will choose the most suitable style after previewing it in the draft of the article. We also worked with a draft.
We also created a draft for the CSS styles in the Block Editor as we could preview the styles and their classes.
You can create a special draft for previewing the CSS styles if there is no previously created. In this draft you can add all available blocks and set up the necessary styles of the theme. For example headings h1, h2, h3, etc., lists, quotes, buttons and all the design components which are used on the theme’s front-end.
back to this section’s beginning 🔼
Increased security and faster loading speed
After the preparation for Gutenberg was successfully completed and the new Block Editor has been already integrated into our blog, now we can update WordPress to the latest version. This will also enable us to use newer PHP versions and our blog will become faster and more secure.
By transitioning to the Block Editor we made a strategic step towards increasing the security and loading time of our blog.
And one more important thing – by using the Block Editor on our blog we can already benefit from a simplified process for creating content which does not take away our creative energy and helps us focus better. This happens thanks to the easier way to achieve the desired layout with no need for the authors to stop and consider how and where to use HTML/CSS code.
Phase 2 from the development of Gutenberg has already started and is being currently in progress. Up to this moment most of the WordPress widgets have been migrated to blocks. Probably the next step will be migrating the navigation menus into blocks. We do not think that preparation for Gutenberg is close to its end by adding CSS of the theme. We will keep following each completed step from phase 2 of the Block Editor.
In case you also would like to follow the hottest updates for WordPress and the Block Editor, check often blog.
