From f14265900d7e64a6cb7c673aa493a91bb045e457 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Tue, 12 Jul 2022 11:03:04 +0200 Subject: [PATCH 1/3] Documentation: Consolidate editor filters and actions --- docs/manifest.json | 6 +-- docs/reference-guides/README.md | 9 +++-- .../actions/editor-actions.md | 24 ------------ docs/reference-guides/filters/README.md | 2 +- .../reference-guides/filters/block-filters.md | 16 +++----- .../filters/editor-filters.md | 37 ++++++++++++++++--- 6 files changed, 47 insertions(+), 47 deletions(-) delete mode 100644 docs/reference-guides/actions/editor-actions.md diff --git a/docs/manifest.json b/docs/manifest.json index 8ef3fe89ee2fc0..dca4d7d955b5b2 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -462,19 +462,19 @@ "parent": "reference-guides" }, { - "title": "Filter Reference", + "title": "Hooks Reference", "slug": "filters", "markdown_source": "../docs/reference-guides/filters/README.md", "parent": "reference-guides" }, { - "title": "Block Filters", + "title": "Block Hooks", "slug": "block-filters", "markdown_source": "../docs/reference-guides/filters/block-filters.md", "parent": "filters" }, { - "title": "Editor Filters", + "title": "Editor Hooks", "slug": "editor-filters", "markdown_source": "../docs/reference-guides/filters/editor-filters.md", "parent": "filters" diff --git a/docs/reference-guides/README.md b/docs/reference-guides/README.md index a13978610518cf..c641d215835da5 100644 --- a/docs/reference-guides/README.md +++ b/docs/reference-guides/README.md @@ -16,11 +16,12 @@ - [Metadata](/docs/reference-guides/block-api/block-metadata.md) - [Variations](/docs/reference-guides/block-api/block-variations.md) -## [Filter Reference](/docs/reference-guides/filters/README.md) +## [Hooks Reference](/docs/reference-guides/filters/README.md) -- [Block Filters](/docs/reference-guides/filters/block-filters.md) -- [Editor Filters (Experimental)](/docs/reference-guides/filters/editor-filters.md) -- [Parser Filters](/docs/reference-guides/filters/parser-filters.md) +- [Block Hooks](/docs/reference-guides/filters/block-filters.md) +- [Editor Hooks](/docs/reference-guides/filters/editor-filters.md) +- [i18n Hooks](/docs/reference-guides/filters/i18n-filters.md) +- [Parser Hooks](/docs/reference-guides/filters/parser-filters.md) - [Autocomplete](/docs/reference-guides/filters/autocomplete-filters.md) ## [SlotFills Reference](/docs/reference-guides/slotfills/README.md) diff --git a/docs/reference-guides/actions/editor-actions.md b/docs/reference-guides/actions/editor-actions.md deleted file mode 100644 index d5e37744036ee2..00000000000000 --- a/docs/reference-guides/actions/editor-actions.md +++ /dev/null @@ -1,24 +0,0 @@ -# Editor Actions - -To help you hook into the editor lifecycle and extend it, the following Actions are exposed: - -### Error Boundaries - -#### `editor.ErrorBoundary.errorLogged` - -Allows you to hook into the editor Error Boundaries' `componentDidCatch` and gives you access to the error object. - -You can use if you want to get hold of the error object that's handled by the boundaries, i.e to send them to an external error tracking tool. - -_Example_: - -```js -addAction( - 'editor.ErrorBoundary.errorLogged', - 'mu-plugin/error-capture-setup', - ( error ) => { - // error is the exception's error object - ErrorCaptureTool.captureError( error ); - } -); -``` diff --git a/docs/reference-guides/filters/README.md b/docs/reference-guides/filters/README.md index 9f4e98bdbff170..66cac472ecaa79 100644 --- a/docs/reference-guides/filters/README.md +++ b/docs/reference-guides/filters/README.md @@ -1,4 +1,4 @@ -# Filter Reference +# Hooks Reference [Hooks](https://developer.wordpress.org/plugins/hooks/) are a way for one piece of code to interact/modify another piece of code. They provide one way for plugins and themes to interact with the editor, but they’re also used extensively by WordPress Core itself. diff --git a/docs/reference-guides/filters/block-filters.md b/docs/reference-guides/filters/block-filters.md index 658f2915e0be05..823248bb451bdd 100644 --- a/docs/reference-guides/filters/block-filters.md +++ b/docs/reference-guides/filters/block-filters.md @@ -1,6 +1,6 @@ -# Block Filters +# Block Hooks -To modify the behavior of existing blocks, WordPress exposes several APIs: +To modify the behavior of existing blocks, WordPress exposes several APIs. ## Registration @@ -92,23 +92,19 @@ _Example:_ Wraps a cover block into an outer container. ```js -function wrapCoverBlockInContainer(element, blockType, attributes) { +function wrapCoverBlockInContainer( element, blockType, attributes ) { // skip if element is undefined - if (!element) { + if ( ! element ) { return; } // only apply to cover blocks - if ( (blockType.name !== 'core/cover') ) { + if ( blockType.name !== 'core/cover' ) { return element; } // return the element wrapped in a div - return ( -
- { element } -
- ); + return
{ element }
; } wp.hooks.addFilter( diff --git a/docs/reference-guides/filters/editor-filters.md b/docs/reference-guides/filters/editor-filters.md index 28d03bd4ab56d2..d8c2ada68f37f1 100644 --- a/docs/reference-guides/filters/editor-filters.md +++ b/docs/reference-guides/filters/editor-filters.md @@ -1,6 +1,10 @@ -# Editor Filters +# Editor Hooks -To modify the behavior of the editor experience, the following Filters are exposed: +To modify the behavior of the editor experience, WordPress exposes several APIs. + +## Editor features + +The following filters are available to extend the editor features. ### `editor.PostFeaturedImage.imageSize` @@ -124,7 +128,30 @@ Default `true`. Indicates whether the user can access the code editor **in addit If 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. -### Block Directory +## Logging errors + +A JavaScript error in a part of the UI shouldn’t break the whole app. To solve this problem for users, React library uses a concept of an [“error boundary”](https://reactjs.org/docs/error-boundaries.html). Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, and display a fallback UI instead of the component tree that crashed. + +### `editor.ErrorBoundary.errorLogged` + +Allows you to hook into the [Error Boundaries](https://reactjs.org/docs/error-boundaries.html) and gives you access to the error object. + +You can use this action if you want to get hold of the error object that's handled by the boundaries, i.e to send them to an external error tracking tool. + +_Example_: + +```js +addAction( + 'editor.ErrorBoundary.errorLogged', + 'mu-plugin/error-capture-setup', + ( error ) => { + // error is the exception's error object + ErrorCaptureTool.captureError( error ); + } +); +``` + +## Block Directory The Block Directory enables installing new block plugins from [WordPress.org.](https://wordpress.org/plugins/browse/block/) It can be disabled by removing the actions that enqueue it. In WordPress core, the function is `wp_enqueue_editor_block_directory_assets`. To remove the feature, use [`remove_action`,](https://developer.wordpress.org/reference/functions/remove_action/) like this: @@ -135,9 +162,9 @@ The Block Directory enables installing new block plugins from [WordPress.org.](h remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_editor_block_directory_assets' ); ``` -### Block Patterns +## Block Patterns -#### `should_load_remote_block_patterns` +### `should_load_remote_block_patterns` Default `true`. The filter is checked when registering remote block patterns, set to false to disable. From 0aaa2ae9d4c13d0f22f299867d8cf834fa4f81ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Mon, 18 Jul 2022 11:27:09 +0200 Subject: [PATCH 2/3] Update docs/reference-guides/filters/editor-filters.md --- docs/reference-guides/filters/editor-filters.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference-guides/filters/editor-filters.md b/docs/reference-guides/filters/editor-filters.md index d8c2ada68f37f1..2198a8677e199e 100644 --- a/docs/reference-guides/filters/editor-filters.md +++ b/docs/reference-guides/filters/editor-filters.md @@ -130,6 +130,8 @@ If set to false the user will not be able to switch between visual and code edit ## Logging errors +_Since WordPress 6.1._ + A JavaScript error in a part of the UI shouldn’t break the whole app. To solve this problem for users, React library uses a concept of an [“error boundary”](https://reactjs.org/docs/error-boundaries.html). Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, and display a fallback UI instead of the component tree that crashed. ### `editor.ErrorBoundary.errorLogged` From e8dc5d4b0974db96138997f9611bc9a4fbc74a19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Mon, 18 Jul 2022 11:28:13 +0200 Subject: [PATCH 3/3] Update docs/reference-guides/filters/editor-filters.md --- docs/reference-guides/filters/editor-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/filters/editor-filters.md b/docs/reference-guides/filters/editor-filters.md index 2198a8677e199e..fd5cccb5fe45a0 100644 --- a/docs/reference-guides/filters/editor-filters.md +++ b/docs/reference-guides/filters/editor-filters.md @@ -130,7 +130,7 @@ If set to false the user will not be able to switch between visual and code edit ## Logging errors -_Since WordPress 6.1._ +_**Note:** Since WordPress 6.1._ A JavaScript error in a part of the UI shouldn’t break the whole app. To solve this problem for users, React library uses a concept of an [“error boundary”](https://reactjs.org/docs/error-boundaries.html). Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, and display a fallback UI instead of the component tree that crashed.