WordPress fullsite editing using blocktheme for developers

WordPress fullsite editing, or “Site Editing” as it’s now referred to, has been met with lots of resistance from developers, myself included. However, since revisiting it after avoiding it for months, I’ve really warmed up to it as a developer. Especially as more of a backend developer, the thought of not having to write much CSS or any at all really appeals to me. Don’t get me wrong, I appreciate that CSS is still crucial in web development, and as a developer, you still need to know how to write and understand it. However, it’s the one thing that slows me down with any project. The less I need to write, the quicker I can turn over a project.

I also understand the need to lower the barrier to entry for users, including designers. It opens up a whole new opportunity for users who might have never touched WordPress before, and that can’t be a bad thing, right?

Okay, let’s get to the point of this post about WordPress fullsite editing! I’ve created a basic “Block Theme,” which is what they are called if you want to explore the benefits of “Site Editing” in WordPress. I’ve done this for my own benefit because I wanted a default vanilla theme to start my own projects and submit to the theme repository. Additionally, I want to show other developers how I intend to use it. So, let’s get started!

You can find my vanilla theme called “blocktheme” on GitHub. Download or clone the blocktheme repository. Then, rename the folder and references from “blocktheme” to your chosen name. Make sure to name the folder the same as the references in the theme code. For the purpose of this example, I’ll be naming my folder “whatnew”.

Next, use VSCode (or any code editor of your choice) to globally search and replace in the theme folder for “blocktheme” and replace it with “whatsnew”. Once you’ve completed this step, you can start building your custom block theme.

Assuming you’re familiar with activating a theme, I won’t go into the details of that process. Once you have your new theme activated, I would recommend downloading and adding the theme unit test data from the WP Themes Team. You can find it at https://github.com/WPTT/theme-test-data. This XML file is filled with content that includes all core blocks, image uploads, users, pages, posts, categories, terms, tags, menus, and more. If you’re keen on developing for the theme repository, this test data is essential for developing and debugging. It contains every possible content component you’ll need when designing and developing your own custom themes.

However, please note that you should not use this test data on any live site where you already have existing content. It is meant for local development or on a new staging site specifically for creating a new block theme design. Unless you are confident and know what you are doing, I wouldn’t recommend using this on any live production sites. Importing the XML file in a production environment will replace all the content on your site.

To import the file, follow these steps:

From the WordPress Dashboard, navigate to “Tools” and click on “Import”.
If you haven’t already installed the WordPress Importer, you may need to install it. If it’s already installed, skip this step.
Once the WordPress Importer is installed, run the import process.
Click on the “Upload file and import” button.
Select the XML file you downloaded earlier and click “Upload file and import”.
Set the parameters according to your preferences.
Finally, click the “Submit” button to start the import process.

After completing these steps, you’ll have a site filled with content ready for developing the new block theme.

Note: Before you start building, it’s important to understand the objective of this process. You’ll be copying and pasting blocks from the site editor UI into your theme files. Therefore, refrain from saving any templates, parts, global settings, or styles in the site editor UI during this process. Saving any changes in the site editor UI can override the configurations and settings in the block theme you are building.

Build the header

To proceed, follow these steps:

With your new theme activated, go to the front end of your development site and click “Edit Site” from the admin bar.
In the site editor, click on “Template Parts” and select “Header”. Then, click on the pencil edit icon.
Now, you can start designing your header layout. However, remember not to save anything from this point onwards in the site editor. We are only using the site editor to visually layout the header.
Add a group, columns, and theme-specific blocks like “Site Logo,” “Site Title,” “Site Tag,” and a Navigation block set to “All Pages”. You can find the navigation block settings in the sidebar under “Menu”. The menus have already been defined by the XML theme data uploaded earlier.
Customize the layout according to your needs, aiming for a corporate business website header, for example.
Once you are satisfied with your layout, access the “List View” by clicking on the respective icon in the top menu of the site editor. This will display a list view of all the blocks in the template part.
Look for the uppermost, top-level block in the list. You will see three dots next to it. Click on the dots and select “Copy Block”.
Now, switch back to your chosen code editor (e.g., VSCode) and navigate to your theme files. Specifically, locate the “header.html” file in the “parts” subfolder of your theme.
Paste the copied block code from the site editor into the “header.html” file within your theme.
Optionally, clean up the code formatting to ensure readability and consistency.
Save the “header.html” file in your theme folder.
Return to your development website in the site editor and refresh the page.
You should now see a visual representation of your header, which is being rendered from the code in your theme’s “header.html” file.

By following these steps, you have successfully integrated the header design from the site editor into your theme files.

Build Footer

To continue, follow these steps to design the footer:

Repeat the process either by navigating back step by step in the left-hand side site editor navigation panel or by going back to the front end and clicking “Edit Site”.
In the site editor, click on “Template Parts” and select “Footer”. Then, click on the pencil edit icon.
Now, you can start designing your footer layout. However, remember not to save anything from this point onwards in the site editor. We are only using the site editor to visually layout the footer.
Add a group and a simple Paragraph block, I’ll just add the classic text “Proudly powered by WordPress”.

Again, ensure that you do not save any changes made in the site editor. We are only using it for the visual layout of the footer.

Build the Index

To continue, follow these steps to edit the Index template and incorporate the layout:

Navigate back to the main site editor. Instead of clicking “Template Parts,” click on “Templates” this time.
Select “Index” and click the pencil icon to edit the Index template. It’s worth noting that, similar to traditional WordPress themes, the index.php file is the main file that everything routes back to. This applies to Block Theme template files as well.
In the Index template, select the “Query Loop” block. You can start with a blank block or choose from variations of how you want the loop to look like. Select your preferred option.
This will set up a basic structure in your Index template. However, you can still edit the structure by adding featured images within the posts, moving the date, adjusting read more links and titles, and more. You can also modify the settings of the Query Loop block, such as setting it as a grid, list, or adjusting the number of posts. Remember not to save anything in the Site Editor.
Once you are satisfied with the layout, open the List View of all the blocks in the template. This time, you should see icons for the Header and Footer, with the Query Loop block nested within a Group block. Click on the three dots of the Query Loop block and select “Copy Block”.
Switch back to your theme files and navigate to the templates folder. Open the index.html file within this folder.
Paste the copied blocks between the opening and closing HTML elements tags of the “main” section in the index.html file. Save the file.
Return to your development website and refresh the page.
Now, you should see the layout rendered from the code in the theme file, specifically from the index.html file in the theme’s template folder.

As you can observe, there is a pattern emerging. Next, you will create new files in the theme’s template folder for all the other templates you’ll need.

By following these steps, you have successfully edited the Index template and incorporated the layout from the site editor into the index.html file of your theme.

Create and build a single post template

In your vanilla block theme repository, if you haven’t already created all the necessary template files, you will need to physically create them. For example, let’s create a single file for single posts:

Duplicate the index.html file.
Rename the duplicated file as “single.html”.
Open the “single.html” file in your code editor.
Delete all the block code between the opening and closing “main” HTML element tags that you pasted in the last step. You are going to recreate this structure for single posts.
Next open up the theme.json file as declare the following settings for “name” and “title” in the “customTemplates” section, there is another optional parameter for “postType” but for simplicy we’re only using name and title for now. This will define what is shown in the editor to the user with the exception of all the standard defualt templates used in a classic theme, eg: archive, comments, 404 etc. the section should look like the following:

    "customTemplates": [
        {
            "name": "index",
            "title": "Index"
        },
        {
            "name": "single",
            "title": "Single"
        }
    ],

Now, you can proceed to design and build the layout for single posts in the “single.html” file according to your requirements.

To continue building your block theme, follow these steps:

Go back to the Site Editor and navigate to Templates.
If you have correctly saved a file called “single.html” in your theme’s “templates” folder, you should now see a “Single” option.
Select “Single” and click the pencil icon to edit the Single template.
Add a “Post Title” block.
Below the Post Title block, add a “Post Content” block.
Add all the regular blocks you would typically need in a standard blog post, such as Post Author, Post Author Name, Post Author Biography, Comments, Post Comments Form, Previous post, Next post, etc.
Adjust the layout of the blocks to your preference by grouping them or placing them in columns. Be creative with your design, but remember not to save anything in the editor. Use the editor solely to visually layout the template design.
Once you are satisfied with the layout, open the List View of all the blocks in the template. You should see icons for the Header and Footer, with all the blocks nested within a Group block. Click on the three dots of the Group block and select “Copy Block”.
Switch back to your theme files and navigate to the templates folder. Open the single.html file.
Unlike the previous code pasted in the index.html file, this time replace all the comment code from the opening “<!– wp:group …–>” to the closing “<!– /wp:group …–>” with the copied Group block. This will ensure consistency in the structure of your theme and templates. Save the updated single.html file.
Return to your development website and refresh the page. You should now see the layout rendered from the code in the single.html file of your theme’s template folder.

Create and build a page template

Much the same as createing the single.html file, do the same for a page.html file.

Follow a similar process as before to create a page.html file.
Duplicate the single.html file and rename the duplicated file as “page.html”.
Open the “page.html” file in your code editor.
Delete all the block code between the opening and closing “main” HTML element tags. Make sure to maintain the group and main HTML tags for consistency in your theme. The structure should resemble: <!– wp:group…
<main class=”wp-block-group…
… down to
</main>
<!– /wp:group –>
Next, open the theme.json file and declare the following settings for “name” and “title” in the “customTemplates” section. This will define what is shown in the editor to the user. The section should look like this:

    "customTemplates": [
        {
            "name": "index",
            "title": "Index"
        },
        {
            "name": "single",
            "title": "Single"
        },
        {
            "name": "page",
            "title": "Page"
        }
    ],

Now, you can proceed to design and build the layout for the page in the “page.html” file according to your requirements.

At this point, WordPress fullsite editing should feel more comfortable so you can start creating all the templates you need for your theme. Go ahead and create the structured layout of your theme. In the next post, we’ll dive deeper into customizing your new theme by adjusting the theme.json file and adding your own custom colors, fonts, and styles globally and at the block level.

elliott richmond