Controlling the Block Editor

One of the important use-cases of the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-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 GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ and it will continue to be.

As of today (included in WordPress 5.3), the block editor comes with a number of APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party). 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 hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.) 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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., this configuration can also be made available in the proposed theme.json file.

#block-editor, #core-editor, #gutenberg, #themes