As WordPress continues to develop, there are many concepts around blocks and the new full site editor that we haven't yet explored. This theme attempts to both add some agency-specific documentation around some of these concepts as well as provide a demo theme so these concepts can be explored on a live site.
This theme benefits greatly from the Jace theme, with lots of learnings and code taken from there.
Originally introduced in WordPress 5.8, theme.json is a JSON file that lives in the root of a WordPress theme and provides global configuration options for the WordPress Block Editor along with the ability to configure specific options for specific blocks.
In the context of this theme, we use theme.json to set the color pallete for the site as a whole, which controls which colors appear in the color pickers inside the Block Editor.
Per Rich Tabor's suggestion, the keys we use to define colors are standardized and can be used in our CSS by referencing them with variables. For example:
background-color: var(--wp--preset--color--secondary);
This is very useful because it gives us a standard that we can use when defining Block Styles and some of the other styles around our theme. It also allows us to change color schemes quickly and globally, as is often required when a client is rebranding.
Block Styles allow theme developers to provide style customization options without having to force content creators to add CSS classes manually or configure a ton of block options.
In this theme, we register two block styles as part of the core/heading block: "With Border" and "With Bubble". Once registered, these styles will show up when the block they are registered to is selected.
When one of these styles is selected, the only change to the actual markup that happens is that a CSS class gets applied. In the case of our "With Bubble" style, the CSS class is-style-fsedemo-bubble-heading is applied. However, for the style to have any frontend difference from the default block appearance, CSS has to be written for each of these classes. Once this CSS is in place, the frontend output will changed based on which Block Style is selected in the editor.
One drawback of Block Styles is that, depending on which CSS properties are affected by the style, certain Block Editor controls can conflict with the styling provided by the theme author. For example, if your Block Style dictates a background color, this will conflict with the background color control in the editor. If you are looking to control block editor attributes that already have editor controls, one of the other block paradigms, such as Block Variations, might be a better fit for your use case.
Block Variations are particularly useful for when you need different functionality or layout than an existing block, but not so much that creating an entirely new block would make sense. In addition, Block Variations can be used when you want to offer the user a block with a different style, but by having those styles still configurable in the editor instead of hardcoded with CSS like we discussed in the Block Styles section above.
In this theme, we define a variation on the Media & Text block. Block variations are defined in Javascript, with the various configuration options and attributes passed in as an object to the registerBlockVariation function.
We are often asked to build 50/50 layouts for our clients where there is an image on one side and a container of text consisting of a heading, paragraph and a call-to-action button on the other. This can be created manually with the media and text block by assembling all the inner blocks. However, with a block variation (that we are calling the AP 50/50 block) all of those inner blocks, along with a pre-defined background color and text colors, are already configured and are inserted as-is when the block variation is inserted.
Block variations appear in the block inserter and differ from block styles in that, while attributes can be pre-configured, they can still be changed by the user once inserted. For example, in our block variation, we define the image to have 50% width and the container of text to have the other 50% of the width of the block.
However, once the user inserted our variation, if they wanted to change the image width to 75% and have the text take up just 25% of the width, they could do that without affecting any other blocks on the site. This is what makes block variations so powerful for quickly assembling layouts without restricting the ability to customize them.
Some concepts to explore here:
- Block patterns
- Block editor template parts
- Simple custom block without ACF
- Is there good core support for repeaters without ACF yet?
- Create Block Theme plugin