An experimental block based theme, which supports full site editing. Learn more about building Block Based Themes for WordPress.
Note: the following features are still experimental, and should not be used in a production environment.
- The Gutenberg Plugin must be installed and activated.
- Enable "Full Site Editing" under "Experiments":
Clone this repo into /wp-content/themes
:
git clone [email protected]:WebDevStudios/wds-block-based-theme.git
Activate the theme:
Structure - Block based themes follow this structure:
theme
|__ style.css
|__ functions.php
|__ index.php
|__ experimental-theme.json
|__ block-templates
|__ index.html
|__ single.html
|__ archive.html
|__ ...
|__ block-template-parts
|__ header.html
|__ footer.html
|__ sidebar.html
|__ ...
Block & Block Grammar - An HTML comment containing information about a Block or Template Part. The following grammar creates a centered <p>
tag in the block editor:
<!-- wp:paragraph {"align":"center"} -->
<p>I am a centered paragraph tag</p>
<!-- /wp:paragraph -->
Template Parts - An HTML container for block grammar, which is displayed in Templates. To call a Template Part in a template, use this block grammar:
<!-- wp:template-part {"slug":"header","theme":"yourtheme"} /-->
Templates - An HTML container that displays Template Parts and Block Grammar. They follow the WordPress template hierarchy:
<!-- wp:template-part {"slug":"header","theme":"yourtheme"} /-->
<!-- wp:paragraph {"align":"center"} -->
<p>I am a centered paragraph tag</p>
<!-- /wp:paragraph -->
<!-- wp:template-part {"slug":"footer","theme":"yourtheme"} /-->
Use the Site Editor to build your site:
As you build, your Templates and Template Part block grammar are saved to the database, which can be accessed under the Appearance menu:
You can even edit Templates and Template Parts individually from the Appearance menu:
When you're finished building your site, you can export the your changes from the "Tools" menu:
This action will export all of the Block Grammar into their respective Template and Template Part files. This feature is similar to ACF's Local JSON.
Place the exported Templates and Template Parts files into your theme:
Everything you built in the Site Editor, is now available as code in your theme, which could be checked into version control or shipped to a client.
If you look close, you'll see an additional postID
paramenter in the Template Part grammar:
<!-- wp:template-part {"postID":94,"slug":"header","theme":"yourtheme"} /-->
This informs WordPress that the Header is also saved in the database, under postID: 94
.
Block based themes support an experimental-theme.json
file. WordPress parses this file and makes these CSS variables available, without any need to write CSS. This feature feels similar to Theme UI.
The experimental-theme.json
file:
- Creates CSS variables (also called CSS custom properties) that can be used to style blocks both on the front and in the editor.
- Sets global styles.
- Sets styles for individual block types.
The following example would set a global CSS variable for all <h2>
Blocks:
{
"global": {
"presets": {
"color": [
{
"slug": "strong-magenta",
"value": "#a156b4"
}
]
}
},
"core/heading/h2": {
"styles": {
"color": {
"text": "var( --wp--preset--color--strong-magenta )"
}
}
}
}
Learn more about Theme JSON.
Block based themes will continue to leverage add_theme_support()
as an "opt-in" way to extend and customize Core WordPress features.
The following features are:
align-wide
block-nav-menus
custom-line-height
custom-units
dark-editor-style
editor-color-palette
editor-gradient-presets
editor-font-sizes
experimental-custom-spacing
experimental-link-color
responsive-embeds
wp-block-styles
This example uses editor-color-palette
to set default colors in the Block Editor:
function yourtheme_setup_theme_supported_features() {
add_theme_support( 'editor-color-palette', array(
array(
'name' => __( 'strong magenta', 'yourtheme' ),
'slug' => 'strong-magenta',
'color' => '#a156b4',
),
array(
'name' => __( 'very light gray', 'yourtheme' ),
'slug' => 'very-light-gray',
'color' => '#f1f1f1',
),
) );
}
add_action( 'after_setup_theme', 'yourtheme_setup_theme_supported_features' );
This would be helpful if you needed to set your client's branding colors as defaults in the Block Editor:
Learn more about available Theme Support options.
Learn more https://developer.wordpress.org/block-editor/tutorials/block-based-themes/