From bff700760d6162e7f03e181f64acae077222ca76 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 2 Jan 2025 21:28:40 -0800 Subject: [PATCH 1/3] Add terms for block extension examples --- docs/glossary.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index e51f4cc78..31b9bf467 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -857,4 +857,15 @@ Vale [Vale](https://vale.sh/) is an open-source, command-line tool that helps maintain a consistent and on-brand voice in documentation. Plone Documentation uses it to check spelling, English grammar and syntax, and style guides. +schema enhancer + A schema enhancer uses the `schemaEnhancer` function, which can modify the schema used by the `InlineForm` component. + Any registered extension plugin can provide a `schemaEnhancer` function. + This function receives an object with `formData`, which is the block data; `schema`, which is the original schema to modify; and the injected `intl`, which aids with internationalization. + +variation + A variation is a common development pattern that provides versions of a given block. + You can use a variation to enhance the default behavior of a block without shadowing its stock components. + These enhancements can either be at the settings level via schema enhancers or, if the code of your block allows it, use alternative renderers showing the enhanced fields, modifying the block behavior or its look and feel. + Editors can select a variation on demand. + ``` From 05a3bd5e48406301df7f7715fdd34273b65c0c8e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 3 Jan 2025 14:59:21 -0800 Subject: [PATCH 2/3] Revise variation definition --- docs/glossary.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 31b9bf467..5959a8306 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -863,9 +863,12 @@ schema enhancer This function receives an object with `formData`, which is the block data; `schema`, which is the original schema to modify; and the injected `intl`, which aids with internationalization. variation - A variation is a common development pattern that provides versions of a given block. - You can use a variation to enhance the default behavior of a block without shadowing its stock components. - These enhancements can either be at the settings level via schema enhancers or, if the code of your block allows it, use alternative renderers showing the enhanced fields, modifying the block behavior or its look and feel. - Editors can select a variation on demand. + A variation is a common development pattern that provides alternative views for the same data. + For example, a teaser block can present data as `title + link`, `title + description + link`, or `title + image + link`. + + An advanced variation can enhance the block by adding data fields to the block. + For example, a listing block variation can show news items with `title + link`. + Extending this example, a developer can add a boolean field to the block that toggles the display of the link. + Thus an editor can select between `title + link` or just `title`. ``` From 836d0944772159859c9e26ada9af9b8b9e99d411 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 3 Jan 2025 15:06:32 -0800 Subject: [PATCH 3/3] Add higher-order component (HOC) definition --- docs/glossary.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index 5959a8306..4b326e6b6 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -871,4 +871,18 @@ variation Extending this example, a developer can add a boolean field to the block that toggles the display of the link. Thus an editor can select between `title + link` or just `title`. +HOC +Higher-Order Component + A higher-order component (HOC) is an advanced technique in React for reusing component logic. + HOCs are not part of the React API, per se. + They are a pattern that emerges from React's compositional nature. + Concretely, a higher-order component is a function that takes a component and returns a new component. + + ```{important} + Higher-order components are not commonly used in modern React code. + ``` + ```{seealso} + https://legacy.reactjs.org/docs/higher-order-components.html + ``` + ```