diff --git a/docs/reference-guides/filters/editor-filters.md b/docs/reference-guides/filters/editor-filters.md index 943e161a1df49..f1d55b82b56b2 100644 --- a/docs/reference-guides/filters/editor-filters.md +++ b/docs/reference-guides/filters/editor-filters.md @@ -1,23 +1,166 @@ # Editor Hooks -To modify the behavior of the editor experience, WordPress exposes several APIs. +WordPress exposes several APIs that allow you to modify the editor experience. + +## Editor settings + +One of the most common ways to modify the Editor is through [`block_editor_settings_all`](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/) PHP filter, which is applied before settings are sent to the initialized Editor. This filter allows plugin and theme authors extensive control over how the Editor behaves. + +
+ Before WordPress 5.8, this hook was known as block_editor_settings, which is now deprecated. If you need to support older versions of WordPress, you might need a way to detect which filter should be used. The recommended way to proceed is to check if the WP_Block_Editor_Context class exists. +
+ +The `block_editor_settings_all` hook passes two parameters to the callback function: + +- `$settings` – An array of configurable settings for the Editor. +- `$context` – An instance of [`WP_Block_Editor_Context`](https://developer.wordpress.org/reference/classes/wp_block_editor_context/), an object that contains information about the current Editor. + +The following example modifies the maximum upload file size. Add this to a plugin or your theme's `functions.php` file to test it. + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_filter_block_editor_settings_when_post_provided', 10, 2 ); + +function pluginslug_filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) { + if ( ! empty( $editor_context->post ) ) { + $editor_settings['maxUploadFileSize'] = 12345; + } + return $editor_settings; +} +``` + +There are dozens of editor settings, too many to list in this documentation article, but here are a few examples of what you can do with the `block_editor_settings_all` filter. + +
+ To view all available settings, open the Editor and then open the console in your browser's Developer Tools. Enter the command wp.data.select( 'core/block-editor' ).getSettings() to display the current values for all Editor settings. +
+ +### Restrict code editor access + +The `codeEditingEnabled`, which defaults to `true`, controls whether the user can access the code editor **in addition** to the visual editor. There may be instances where you don't want certain users to be able to access this view. + +If this setting is set to `false`, the user will not be able to switch between visual and code editor. The option in the settings menu will not be available, and the keyboard shortcut for switching editor types will not fire. Here's an example: + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_restrict_code_editor' ); + +function pluginslug_restrict_code_editor( $settings ) { + $can_active_plugins = current_user_can( 'activate_plugins' ); + + // Disable the Code Editor for users that cannot activate plugins (Administrators). + if ( ! $can_active_plugins ) { + $settings[ 'codeEditingEnabled' ] = false; + } + + return $settings; +} +``` + +### Restrict visual editor access + +Similar to the `codeEditingEnabled` setting, `richEditingEnabled` allows you to control who can access the visual editor. If `true`, the user can edit the content using the visual editor. + +The setting defaults to the returned value of the [`user_can_richedit`](https://developer.wordpress.org/reference/functions/user_can_richedit/) function. It checks whether the user can access the visual editor and whether the user's browser supports it. + +### Set a default image size + +Images are set to the `large` image size by default in the Editor. You can modify this using the `imageDefaultSize` setting, which is especially useful if you have configured your own custom image sizes. The following example changes the default image size to `medium`. + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_set_default_image_size' ); + +function pluginslug_set_default_image_size( $settings ) { + $settings['imageDefaultSize'] = 'medium'; + return $settings; +} +``` + +### Disable Openverse + +The [Openverse](https://openverse.org/) integration is enabled for all WordPress sites by default and is controlled by the `enableOpenverseMediaCategory` setting. To disable Openverse, apply the following filter: + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_disable_openverse' ); + +function pluginslug_disable_openverse( $settings ) { + $settings['enableOpenverseMediaCategory'] = false; + return $settings; +} +``` + +### Disable the Font Library + +The Font Library allows users to install new fonts on their site, which is enabled by default and is controlled by the `fontLibraryEnabled` setting. To disable the Font Library, apply the following filter: + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_disable_font_library' ); + +function pluginslug_disable_font_library( $settings ) { + $settings['fontLibraryEnabled'] = false; + return $settings; +} +``` + +### Disable block inspector tabs + +Most blocks display [two tabs](https://make.wordpress.org/core/2023/03/07/introduction-of-block-inspector-tabs/) in the Inspector, one for Settings and another for Styles. You can disable these tabs using the `blockInspectorTabs` setting. + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_disable_inspector_tabs_by_default' ); + +function pluginslug_disable_inspector_tabs_by_default( $settings ) { + $settings['blockInspectorTabs'] = array( 'default' => false ); + return $settings; +} +``` + +You can also modify which blocks have inspector tabs. Here's an example that disables tabs for a specific block. + +```php +add_filter( 'block_editor_settings_all', 'pluginslug_disable_tabs_for_my_custom_block' ); + +function pluginslug_disable_tabs_for_my_custom_block( $settings ) { + $current_tab_settings = _wp_array_get( $settings, array( 'blockInspectorTabs' ), array() ); + $settings['blockInspectorTabs'] = array_merge( + $current_tab_settings, + array( 'my-plugin/my-custom-block' => false ) + ); + + return $settings; +} +``` + +## Block Directory + +The Block Directory allows users to install new block plugins directly in the Editor from the WordPress.org [Plugin Directory](https://wordpress.org/plugins/browse/block/). You can disable this functionality by removing the action that enqueues it, which is `wp_enqueue_editor_block_directory_assets`. To do so, use [`remove_action`](https://developer.wordpress.org/reference/functions/remove_action/) like this: + +```php +remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_editor_block_directory_assets' ); +``` + +## Block patterns + +Remote patterns, such as those from the WordPress.org [Pattern Directory](https://wordpress.org/patterns/), are available to users by default in the Editor. This functionality is controlled by `should_load_remote_block_patterns`, which defaults to `true`. You can disable remote patterns by setting the filter to false (`__return_false`). + +```php +add_filter( 'should_load_remote_block_patterns', '__return_false' ); +``` ## Editor features -The following filters are available to extend the editor features. +The following filters are available to extend features in the Editor. ### `editor.PostFeaturedImage.imageSize` -Used to modify the image size displayed in the Post Featured Image component. It defaults to `'post-thumbnail'`, and will fail back to the `full` image size when the specified image size doesn't exist in the media object. It's modeled after the `admin_post_thumbnail_size` filter in the classic editor. - -_Example:_ +You can use this filter to modify the image size displayed in the Post Featured Image component. It defaults to `'post-thumbnail'` and will fail back to the `full` image size when the specified image size doesn't exist in the media object. It's modeled after the `admin_post_thumbnail_size` filter in the Classic Editor. ```js -var withImageSize = function ( size, mediaId, postId ) { +import { addFilter } from '@wordpress/hooks'; + +const withImageSize = function ( size, mediaId, postId ) { return 'large'; }; -wp.hooks.addFilter( +addFilter( 'editor.PostFeaturedImage.imageSize', 'my-plugin/with-image-size', withImageSize @@ -26,16 +169,16 @@ wp.hooks.addFilter( ### `editor.PostPreview.interstitialMarkup` -Filters the interstitial message shown when generating previews. - -_Example:_ +You can also filter the interstitial message shown when generating previews. Here's an example: ```js -var customPreviewMessage = function () { +import { addFilter } from '@wordpress/hooks'; + +const customPreviewMessage = function () { return 'Post preview is being generated!'; }; -wp.hooks.addFilter( +addFilter( 'editor.PostPreview.interstitialMarkup', 'my-plugin/custom-preview-message', customPreviewMessage @@ -44,13 +187,13 @@ wp.hooks.addFilter( ### `media.crossOrigin` -Used to set or modify the `crossOrigin` attribute for foreign-origin media elements (i.e `