One of the important use-cases of the block-editor is the possibility to control the experience programmatically. Controlling the experience means allowing agencies and developers to configure or restrict the usage of the different features available in the editor. This has always been one of the priorities while adding features to Gutenberg and it will continue to be.
As of today (included in WordPress 5.3), the block editor comes with a number of API to achieve this:
Blocks
Blocks are the main extensibility API of the editor. Thus, developers have the possibility to register custom blocks but they can also restrict the list of available blocks. This can be done both server-side and client-side. Here’s one of the available techniques to do so:
function my_plugin_allowed_block_types( $allowed_block_types, $post ) {
if ( $post->post_type !== 'post' ) {
return $allowed_block_types;
}
return array( 'core/paragraph' );
}
add_filter( 'allowed_block_types', 'my_plugin_allowed_block_types', 10, 2 );
Refer to the documentation for more block types restriction techniques.
Block Style Variations
Several core blocks offer style variations. For instance, the Buttons block comes with two variations “Fill” and “Outline”. The editor provides APIs to register custom style variations and to remove existing ones:
// Registers a style variation for quotes.
register_block_style(
'core/quote',
array(
'name' => 'blue-quote',
'label' => __( 'Blue Quote' ),
'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }',
)
);
// Unregisters the style variation named "fancy-quote"
unregister_block_style( 'core/quote', 'fancy-quote' );
Locked Templates
Locked Templates offer a way to restrict the content of Posts, Pages, CPTs to a given format.
For example the following template can be used to restrict the content of a Books CPT to an image, a paragraph for the author and a description.
array(
array( 'core/image', array(
'align' => 'left',
) ),
array( 'core/heading', array(
'placeholder' => 'Add Author...',
) ),
array( 'core/paragraph', array(
'placeholder' => 'Add Description...',
) ),
)
Refer to the documentation more information about the Templates API.
Theme Supports
Colors
Several blocks offer color customization features. Developers can customize the default color palette to provide a consistent color scheme across the whole website.
add_theme_support( 'editor-color-palette', array(
array(
'name' => __( 'Strong magenta', 'themeLangDomain' ),
'slug' => 'strong-magenta',
'color' => '#a156b4',
),
array(
'name' => __( 'Light grayish magenta', 'themeLangDomain' ),
'slug' => 'light-grayish-magenta',
'color' => '#d0a5db',
),
) );
Users have the possibility to choose a custom color as well. This feature can also be disabled:
add_theme_support( 'disable-custom-colors' );
Additionally, it is possible to define an empty color palette to remove all color customization panels from the editor.
add_theme_support( 'editor-color-palette', array() );
Font sizes
Some blocks also allow the user to tweak the font size and developers have the possibility to define their own set of font sizes.
add_theme_support( 'editor-font-sizes', array(
array(
'name' => __( 'Small', 'themeLangDomain' ),
'size' => 12,
'slug' => 'small'
),
array(
'name' => __( 'Regular', 'themeLangDomain' ),
'size' => 16,
'slug' => 'regular'
)
)
Developers can choose to remove the ability to use a custom font size.
add_theme_support( 'disable-custom-font-sizes' );
Additionally, it is possible to define an empty font sizes set to remove all font size customization panels from the editor.
add_theme_support( 'editor-font-sizes', array() );
Gradients
Recently, the ability to use gradients was added to the editor (only available in the Gutenberg plugin). Similarly to colors, developers can define a custom gradients palette, disable custom gradients, or disable the gradients entirely.
// Define a custom palette.
add_theme_support(
'__experimental-editor-gradient-presets',
array(
array(
'name' => __( 'Vivid cyan blue to vivid purple', 'themeLangDomain' ),
'gradient' => 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
'slug' => 'vivid-cyan-blue-to-vivid-purple'
),
array(
'name' => __( 'Vivid green cyan to vivid cyan blue', 'themeLangDomain' ),
'gradient' => 'linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%)',
'slug' => 'vivid-green-cyan-to-vivid-cyan-blue',
),
)
);
// Disable custom gradients.
add_theme_support( '__experimental-disable-custom-gradients' );
// Disable gradients
add_theme_support( '__experimental-editor-gradient-presets', array() );
Third-party blocks
One of the strengths of the block editor is its block library. The community have built dozens of block plugins. But, while Core blocks do support the controlling APIs exposed above, a lot of third-party blocks don’t adapt properly to these options.
For more consistency between the different block libraries and the Core blocks, block authors are encouraged to support these options in their custom blocks.
The block primitives made available to block authors to build their blocks (e.g. the FontSizePicker component, the experimental useColors and useGradient hooks) do support these options by default, but if you’re using custom UIs, you’re encouraged to adapt to these options. You can access these settings by using the select( 'core/block-editor' ).getSettings()selector.
/*
* @property {Array} colors Palette colors
* @property {boolean} disableCustomColors Whether or not the custom colors are disabled
* @property {Array} gradients Gradient palette
* @property {boolean} disableCustomGradients Whether or not the custom gradients are disabled
* @property {Array} fontSizes Available font sizes
* @property {boolean} disableCustomFontSizes Whether or not the custom font sizes are disabled
* @property {boolean} __experimentalEnablePageTemplates Whether the user has enabled the Page Templates
*/
const settings = wp.data.select( 'core/block-editor' ).getSettings();
Going further
As shown above, the block editor already provides a big number of APIs to control the experience, but it’s fair to acknowledge a lack of consistency and a few missing APIs (for instance to disable drop caps in Paragraph blocks).
In order to address this, I’m proposing a new block_editor_features hook that looks like this:
// Non-exhaustive representation of the block-editor configuration options.
$block_editor_features = array(
'colors' => array(
"enabled" => true,
"colorPalette" => array(),
"allowCustomColors" => true,
"gradientPalette" => array(),
"allowCustomGradients" => true,
),
'typography' => array(
"enabled" => true,
"fontSizes" => array(),
"allowCustomFontSizes" => true,
"allowDropCap" => true,
),
);
apply_filters( 'block_editor_features', array $block_editor_features, WP_Post $post );
And these would be made available to block authors using a dedicated selector.
const features = wp.data.select( 'core/block-editor' ).getFeatures();
In addition to the PHP filter, this configuration can also be made available in the proposed theme.json file.
#block-editor, #core-editor, #gutenberg, #themes
