From dccee83b02edb57b7e3f38c20323dc72769d5ae3 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:15:57 +0100 Subject: [PATCH 01/52] the name of the property is blockSchema not schema --- docs/source/blocks/anatomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/anatomy.md b/docs/source/blocks/anatomy.md index 4c17b89ce9..4ac83fa9d9 100644 --- a/docs/source/blocks/anatomy.md +++ b/docs/source/blocks/anatomy.md @@ -82,7 +82,7 @@ You can use all these props to render your edit block and model its behavior. Volto later then 16.0.0 ships with a set of default Edit and View components. The view component is mostly a placeholder, with an auto-generated listing of the block fields, while the default Edit component is the most interesting, as -it can use the `schema` that you can specify in the block configuration to +it can use the `blockSchema` that you can specify in the block configuration to automatically render a form for the Block settings, in the Volto Sidebar. In the main editing area, it will render the view component, so for many blocks you can just develop a schema and the View component. From bea33fd55ff19e300e366ac29b69b7cd824c1d42 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:20:50 +0100 Subject: [PATCH 02/52] document the option --- docs/source/blocks/settings.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/blocks/settings.md b/docs/source/blocks/settings.md index 0dcb406c45..ed173964b0 100644 --- a/docs/source/blocks/settings.md +++ b/docs/source/blocks/settings.md @@ -48,6 +48,10 @@ const customBlocks = { // Required for alternate default block types implementations. // See also [Settings reference](/configuration/settings-reference) }, + // A block can have a function that returns the schema or directly the schema + // of the block that will be automatically rendered in the sidebar editor + // in case that the `edit` setting of the block is set to `null` + blockSchema: CustomSchema, // A block can have an schema enhancer function with the signature: (schema) => schema // It can be either be at block level (it's applied always), at a variation level // or both. It's up to the developer to make them work nicely (not conflict) between them From 8cd8e6f9f5abe235d14298f00456149151e96c88 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:21:08 +0100 Subject: [PATCH 03/52] we use the term not --- docs/source/blocks/editcomponent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/editcomponent.md b/docs/source/blocks/editcomponent.md index d1f0191711..07777b897a 100644 --- a/docs/source/blocks/editcomponent.md +++ b/docs/source/blocks/editcomponent.md @@ -11,7 +11,7 @@ myst: The edit component part of a block anatomy is specially different to the view component because they have to support the UX for editing the block. This UX can be very complex depending on the kind of block and the feature that it is trying to provide. -The project requirements will tell how far you should go with the UX story of each tile, and how complex it will become. +The project requirements will tell how far you should go with the UX story of each block, and how complex it will become. You can use all the props that the edit component is receiving to model the UX for the block and how it will render. See the complete list of {ref}`block-edit-component-props-label`. From bfe8c56c9c8e91fe3db4ae6db939637d98808682 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:24:22 +0100 Subject: [PATCH 04/52] document the SidebarPortal and SidebarPopup components as functional components --- docs/source/blocks/editcomponent.md | 31 ++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/source/blocks/editcomponent.md b/docs/source/blocks/editcomponent.md index 07777b897a..873925ab41 100644 --- a/docs/source/blocks/editcomponent.md +++ b/docs/source/blocks/editcomponent.md @@ -28,11 +28,19 @@ You need to instantiate it this way: ```jsx import { SidebarPortal } from '@plone/volto/components'; -[...] +const Edit = (props) => { + const { selected } = props; + return ( + + [...] + + + // ... + + ) + +} - - // ... - ``` Everything that's inside the `SidebarPortal` component will be rendered in the sidebar. If you need an extra layer of configuration within `SidebarPortal`, you can use `SidebarPopup`. @@ -41,9 +49,18 @@ Everything that's inside the `SidebarPortal` component will be rendered in the s import { SidebarPopup } from '@plone/volto/components'; - - ... - +const Edit = (props) => { + const { sidebarOpen } = props; + + return ( + [...] + + + ... + + ) +} + ``` ## Schema driven automated block settings forms From 485a42c175343a63547cfcdb0376d59b640e4a7c Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:25:57 +0100 Subject: [PATCH 05/52] document the SidebarPortal and SidebarPopup components as functional components --- docs/source/blocks/editcomponent.md | 43 +++++++++++++++++------------ 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/source/blocks/editcomponent.md b/docs/source/blocks/editcomponent.md index 873925ab41..f47d405586 100644 --- a/docs/source/blocks/editcomponent.md +++ b/docs/source/blocks/editcomponent.md @@ -124,24 +124,31 @@ import schema from './schema'; import BlockDataForm from '@plone/volto/components/manage/Form/BlockDataForm'; import { Icon } from '@plone/volto/components'; - - } - schema={schema} - title={schema.title} - headerActions={} - footer={
I am footer
} - onChangeField={(id, value) => { - this.props.onChangeBlock(this.props.block, { - ...this.props.data, - [id]: value, - }); - }} - onChangeBlock={onChangeBlock} - formData={this.props.data} - block={block} - /> -; +const Edit = (props) => { + const {selected, block, data, onChangeBlock} = props; + + return ( + + } + schema={schema} + title={schema.title} + headerActions={} + footer={
I am footer
} + onChangeField={(id, value) => { + onChangeBlock(block, { + ...data, + [id]: value, + }); + }} + onChangeBlock={onChangeBlock} + formData={data} + block={block} + /> + ; + ) +} + ``` ## Object Browser From 992d234b85fa9927d8717f613bffb8cce01cd136 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:48:33 +0100 Subject: [PATCH 06/52] add first example of a block --- .../blocks/examples/customschemaandview.md | 162 ++++++++++++++++++ docs/source/blocks/examples/index.md | 20 +++ docs/source/blocks/index.md | 1 + 3 files changed, 183 insertions(+) create mode 100644 docs/source/blocks/examples/customschemaandview.md create mode 100644 docs/source/blocks/examples/index.md diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md new file mode 100644 index 0000000000..7b7b62872e --- /dev/null +++ b/docs/source/blocks/examples/customschemaandview.md @@ -0,0 +1,162 @@ +--- +myst: + html_meta: + "description": "Volto block with custom schema and view components" + "property=og:description": "Volto block with custom schema and view components" + "property=og:title": "Volto block with custom schema" + "keywords": "Volto, React, blocks, grid, container, Plone" +--- + +(custom-schema-and-view)= + +# Block with a custom schema + +We can create a block with several settings defined using a schema, and let Volto render the edit form by itself. + +What we need to do is to define the schema, the view component, and configure the block settings. + +## Preparation + +In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. + +Name this folder as {file}`ExampleBlock`. + +## Schema + +Create a {file}`schema.js` inside the {file}`ExampleBlock` folder, with the following contents: + +```js +import messages from './messages'; + +const Schema = ({ intl }) => { + return { + title: intl.formatMessage(messages.block02), + block: 'block02', + fieldsets: [ + { + id: 'default', + title: intl.formatMessage(messages.default), + fields: ['url', 'title'], + }, + ], + + properties: { + url: { + title: intl.formatMessage(messages.URL), + widget: 'url', + }, + title: { + title: intl.formatMessage(messages.title), + }, + }, + required: [], + }; +}; + +export default Schema; +``` + +## Messages + +As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. + +So we need a file {file}`messages.js` in the same {file}`ExampleBlock` folder with the following contents: + +```js +import { defineMessages } from 'react-intl'; + +const messages = defineMessages({ + block02: { + id: 'block02', + defaultMessage: 'Block 02', + }, + default: { + id: 'default', + defaultMessage: 'Default', + }, + URL: { + id: 'URL', + defaultMessage: 'URL', + }, + title: { + id: 'title', + defaultMessage: 'Title', + }, +}); + +export default messages; +``` + +## View component + +The view component will have all the required logic to show the information saved on the block. + +In our case will be a samll HTML fragment. + +Create a file {file}`View.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import cx from 'classnames'; +import React from 'react'; + +const View = (props) => { + // data holds the values entered in the block edit form + // className holds the CSS class names injected to this block by other Volto features + // style holds the CSS properties injected to this block by other Volto featured + const { data, className, style } = props; + return ( +
+ I am the Block view component! +
    +
  • Title: {data.title}
    • +
  • URL: {data.url}
    • +
+
+ ); +}; + +export default View; +``` + +## Block configuration + +With all the block components ready, you need to register the block into Volto. + +To do so, open your addon's {file}`index.js` file, that will have the following contents: + +```js +const applyConfig = (config) => { + config.settings.isMultilingual = false; + config.settings.supportedLanguages = ['en']; + config.settings.defaultLanguage = 'en'; + + + return config; +} + +export default applyConfig; +``` + +And before the last `return config;` statement, write the following configuration: + +```js +config.blocks.blocksConfig.block02 = { + id: 'block02', + title: 'Block 02', + view: View02, + // edit: null; + blockSchema: Schema02, + icon: imagesSVG, + sidebarTab: 1, + }; +``` + +On the top of the file you will need to import the relevant components, as follows: + +```js +import View02 from './components/ExampleBlock/View'; +import Schema02 from './components/ExampleBlock/Schema'; + + + +``` diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md new file mode 100644 index 0000000000..358aa7b634 --- /dev/null +++ b/docs/source/blocks/examples/index.md @@ -0,0 +1,20 @@ +--- +myst: + html_meta: + "description": "Volto block examples." + "property=og:description": "Volto block examples." + "property=og:title": "Block examples" + "keywords": "Volto, React, blocks, example, edit, view, Plone" +--- + +# Volto Block examples + +This part of the documentation shows some examples of custom blocks that you can use as a base to develop your own blocks. + +```{toctree} +:maxdepth: 1 + +customschemaandview +customviewandvariations +customviewvariationsandschemaenhancer +``` diff --git a/docs/source/blocks/index.md b/docs/source/blocks/index.md index 2a8e485349..62b72c5815 100644 --- a/docs/source/blocks/index.md +++ b/docs/source/blocks/index.md @@ -20,4 +20,5 @@ block-style-wrapper extensions ssr core/index +examples ``` From 8228d2d1cd61147516ee9988350e56a2d6bce77f Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 16:56:32 +0100 Subject: [PATCH 07/52] docs --- .../blocks/examples/customschemaandview.md | 16 +++++++++++----- docs/source/blocks/index.md | 2 +- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md index 7b7b62872e..789ef835da 100644 --- a/docs/source/blocks/examples/customschemaandview.md +++ b/docs/source/blocks/examples/customschemaandview.md @@ -15,7 +15,7 @@ We can create a block with several settings defined using a schema, and let Volt What we need to do is to define the schema, the view component, and configure the block settings. -## Preparation +## Preparations In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. @@ -23,7 +23,7 @@ Name this folder as {file}`ExampleBlock`. ## Schema -Create a {file}`schema.js` inside the {file}`ExampleBlock` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock` folder, with the following contents: ```js import messages from './messages'; @@ -101,8 +101,8 @@ import React from 'react'; const View = (props) => { // data holds the values entered in the block edit form - // className holds the CSS class names injected to this block by other Volto features - // style holds the CSS properties injected to this block by other Volto featured + // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` + // style holds the CSS properties injected to this block by Volto's `Block Sytle Wrapper` const { data, className, style } = props; return (
@@ -157,6 +157,12 @@ On the top of the file you will need to import the relevant components, as follo import View02 from './components/ExampleBlock/View'; import Schema02 from './components/ExampleBlock/Schema'; +// This is the icon we use for the example, use a meaningful one or provide your own image. +import imagesSVG from '@plone/volto/icons/images.svg'; +``` +## See it in action -``` +Your block is ready to be used in your site. + +Restart your Volto site and you will be able to add it using the block add form. diff --git a/docs/source/blocks/index.md b/docs/source/blocks/index.md index 62b72c5815..5283c494c9 100644 --- a/docs/source/blocks/index.md +++ b/docs/source/blocks/index.md @@ -20,5 +20,5 @@ block-style-wrapper extensions ssr core/index -examples +examples/index ``` From 1ecbe10047db3f6e8f7fe79b7d64acba5c858fdc Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 17:00:26 +0100 Subject: [PATCH 08/52] more docs --- docs/source/blocks/examples/customschemaandview.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md index 789ef835da..dc68451f30 100644 --- a/docs/source/blocks/examples/customschemaandview.md +++ b/docs/source/blocks/examples/customschemaandview.md @@ -141,13 +141,13 @@ And before the last `return config;` statement, write the following configuratio ```js config.blocks.blocksConfig.block02 = { - id: 'block02', - title: 'Block 02', - view: View02, + id: 'block02', // this is the block id, it must match the id on the previous line + title: 'Block 02', // this is the block title + view: View02, // this is the block's view component // edit: null; - blockSchema: Schema02, - icon: imagesSVG, - sidebarTab: 1, + blockSchema: Schema02, // this is the schema that will be used to render the edit form + icon: imagesSVG, // this is the image that will be shown in the block selector + sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block }; ``` From 12efde16e5dd7d992aa90e9802aab5ca023ac575 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 17:25:56 +0100 Subject: [PATCH 09/52] add the docs of custom schema and variations --- .../examples/customviewandvariations.md | 248 ++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 docs/source/blocks/examples/customviewandvariations.md diff --git a/docs/source/blocks/examples/customviewandvariations.md b/docs/source/blocks/examples/customviewandvariations.md new file mode 100644 index 0000000000..d82aacbf79 --- /dev/null +++ b/docs/source/blocks/examples/customviewandvariations.md @@ -0,0 +1,248 @@ +--- +myst: + html_meta: + "description": "Volto block with custom schema and view components using variations" + "property=og:description": "Volto block with custom schema and view components using variations" + "property=og:title": "Volto block with custom schema and variations" + "keywords": "Volto, React, blocks, grid, container, Plone" +--- + +(custom-schema-view-and-variations)= + +# Block with a custom schema and variations + +We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. This variation is shown as an additional option in the schema editor and lets the webmaster to change how this block is viewed. Think of it as a different view of the same block + +What we need to do is to define the schema, the view component, the variations and configure the block settings. + +## Preparations + +In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. + +Name this folder as {file}`ExampleBlock`. + +## Schema + +Create a {file}`Schema.js` file inside the {file}`ExampleBlock` folder, with the following contents: + +```js +import messages from './messages'; + +const Schema = ({ intl }) => { + return { + title: intl.formatMessage(messages.block02), + block: 'block05', + fieldsets: [ + { + id: 'default', + title: intl.formatMessage(messages.default), + fields: ['url', 'title'], + }, + ], + + properties: { + url: { + title: intl.formatMessage(messages.URL), + widget: 'url', + }, + title: { + title: intl.formatMessage(messages.title), + }, + }, + required: [], + }; +}; + +export default Schema; +``` + +## Messages + +As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. + +So we need a file {file}`messages.js` in the same {file}`ExampleBlock` folder with the following contents: + +```js +import { defineMessages } from 'react-intl'; + +const messages = defineMessages({ + block05: { + id: 'block05', + defaultMessage: 'Block 05', + }, + default: { + id: 'default', + defaultMessage: 'Default', + }, + URL: { + id: 'URL', + defaultMessage: 'URL', + }, + title: { + id: 'title', + defaultMessage: 'Title', + }, +}); + +export default messages; +``` + +## View component + +In this case, as we are using variations, the view component needs to use the variation template to render the contents of the block. + +This is easily achieved using the `variation` coming on the `props` of the block. + +Create a file {file}`View.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; +import cx from 'classnames'; +import React from 'react'; + +const View = (props) => { + // data holds the values entered in the block edit form + // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` + // style holds the CSS properties injected to this block by Volto's `Block Sytle Wrapper` + // variation holds the variation selected in the block editor, and it is an object as defined in the block configuration + const { data, className, style, variation } = props; + + const BodyTemplate = variation?.template; + + return ( +
+ +
+ ); +}; + +// the `withBlockExtensions` HOC, makes the variation selector available in the block edit form +// and provides the `variation` property in the props. +export default withBlockExtensions(View); +``` + +## Variations + +Now we need to create one or more variations that will be available for this block. + +Create a file {file}`Variation01.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import React from 'react'; + +const View = (props) => { + const { data } = props; + return ( + <> +

Variation View 01

+
+
    +
  • Title: {data.title}
    • +
  • URL: {data.url}
    • +
+
+ + ); +}; + +export default View; +``` +Create a file {file}`Variation02.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import React from 'react'; + +const View = (props) => { + const { data } = props; + return ( + <> +

Variation View 02

+
+
    +
  • Title: {data.title}
    • +
  • URL: {data.url}
    • +
+
+ + ); +}; + +export default View; +``` + +As you can see, in this case the variations are pretty much the same, the only difference is the text that is rendered in the `

` tag. But it can be anything. + +## Block configuration + +With all the block components ready, you need to register the block into Volto. + +To do so, open your addon's {file}`index.js` file, that will have the following contents: + +```js +const applyConfig = (config) => { + config.settings.isMultilingual = false; + config.settings.supportedLanguages = ['en']; + config.settings.defaultLanguage = 'en'; + + + return config; +} + +export default applyConfig; +``` + +And before the last `return config;` statement, write the following configuration: + +```js + config.blocks.blocksConfig.block05 = { + id: 'block05', // this is the block id, it must match the id on the previous line + title: 'Block 05', // this is the block title + view: View05, // this is the block's view component + //edit: Edit05, + blockSchema: Schema05, // this is the schema that will be used to render the edit form + icon: imagesSVG, // this is the image that will be shown in the block selector + sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block + // these are the variations available for this block + variations: [ + { + id: 'variation01', // this is the id of the variation + title: 'Variation 01', // this is the title of the variation + isDefault: true, // this signals if this is the default variation for this block + template: VariationView0501, // this is the component that will render the variation + }, + { + id: 'variation02', + title: 'Variation 02', + isDefault: false, + template: VariationView0502, + }, + ], + }; + +``` + +On the top of the file you will need to import the relevant components, as follows: + +```js +import View05 from './components/ExampleBlock/View'; +import Schema05 from './components/ExampleBlock/Schema'; +import VariationView0501 from './components/ExampleBlock/VariationView01'; +import VariationView0502 from './components/ExampleBlock/VariationView02'; + +// This is the icon we use for the example, use a meaningful one or provide your own image. +import imagesSVG from '@plone/volto/icons/images.svg'; +``` + +## See it in action + +Your block is ready to be used in your site. + +Restart your Volto site and you will be able to add it using the block add form. From d54d289f5b3e6408bc74d71f9fd1703d5c5309fb Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 17:50:46 +0100 Subject: [PATCH 10/52] provide an example with variations and schema enhancer --- .../examples/customviewandvariations.md | 6 +- .../customviewvariationsandschemaenhancer.md | 274 ++++++++++++++++++ 2 files changed, 277 insertions(+), 3 deletions(-) create mode 100644 docs/source/blocks/examples/customviewvariationsandschemaenhancer.md diff --git a/docs/source/blocks/examples/customviewandvariations.md b/docs/source/blocks/examples/customviewandvariations.md index d82aacbf79..4663d6793e 100644 --- a/docs/source/blocks/examples/customviewandvariations.md +++ b/docs/source/blocks/examples/customviewandvariations.md @@ -30,7 +30,7 @@ import messages from './messages'; const Schema = ({ intl }) => { return { - title: intl.formatMessage(messages.block02), + title: intl.formatMessage(messages.block05), block: 'block05', fieldsets: [ { @@ -133,7 +133,7 @@ export default withBlockExtensions(View); Now we need to create one or more variations that will be available for this block. -Create a file {file}`Variation01.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock` folder with the following contents: ```jsx import React from 'react'; @@ -155,7 +155,7 @@ const View = (props) => { export default View; ``` -Create a file {file}`Variation02.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock` folder with the following contents: ```jsx import React from 'react'; diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md new file mode 100644 index 0000000000..27dca2925a --- /dev/null +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -0,0 +1,274 @@ +--- +myst: + html_meta: + "description": "Volto block with custom schema and view components using variations and a schema enhancer in one of the variations" + "property=og:description": "Volto block with custom schema and view components using variations and a schema enhancer in one of the variations" + "property=og:title": "Volto block with custom schema, variations and schema enhancer" + "keywords": "Volto, React, blocks, grid, container, Plone" +--- + +(custom-schema-view-variations-schema-enhancer)= + +# Block with a custom schema, variations and a schema enhancer in a variation. + +We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. This variation is shown as an additional option in the schema editor and lets the webmaster to change how this block is viewed. Think of it as a different view of the same block. + +A schema enhancer is an option of a variation. Using this schema enhancer, the block schema can be extended to have additional fields. + +What we need to do is to define the schema, the view component, the variations, the schema enhancer and configure the block settings. + +## Preparations + +In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. + +Name this folder as {file}`ExampleBlock`. + +## Schema + +Create a {file}`Schema.js` file inside the {file}`ExampleBlock` folder, with the following contents: + +```js +import messages from './messages'; + +const Schema = ({ intl }) => { + return { + title: intl.formatMessage(messages.block06), + block: 'block06', + fieldsets: [ + { + id: 'default', + title: intl.formatMessage(messages.default), + fields: ['url', 'title'], + }, + ], + + properties: { + url: { + title: intl.formatMessage(messages.URL), + widget: 'url', + }, + title: { + title: intl.formatMessage(messages.title), + }, + }, + required: [], + }; +}; + +export default Schema; +``` + +## Messages + +As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. + +So we need a file {file}`messages.js` in the same {file}`ExampleBlock` folder with the following contents: + +```js +import { defineMessages } from 'react-intl'; + +const messages = defineMessages({ + block06: { + id: 'block06', + defaultMessage: 'Block 06', + }, + default: { + id: 'default', + defaultMessage: 'Default', + }, + URL: { + id: 'URL', + defaultMessage: 'URL', + }, + title: { + id: 'title', + defaultMessage: 'Title', + }, +}); + +export default messages; +``` + +## View component + +In this case, as we are using variations, the view component needs to use the variation template to render the contents of the block. + +This is easily achieved using the `variation` coming on the `props` of the block. + +Create a file {file}`View.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; +import cx from 'classnames'; +import React from 'react'; + +const View = (props) => { + // data holds the values entered in the block edit form + // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` + // style holds the CSS properties injected to this block by Volto's `Block Sytle Wrapper` + // variation holds the variation selected in the block editor, and it is an object as defined in the block configuration + const { data, className, style, variation } = props; + + const BodyTemplate = variation?.template; + + return ( +
+ +
+ ); +}; + +// the `withBlockExtensions` HOC, makes the variation selector available in the block edit form +// and provides the `variation` property in the props. +export default withBlockExtensions(View); +``` + +## Schema enhancer + +We need to configure the schema enhancer function. In this case we will be adding a new field named `color` when using the Variation 2. + +Create a file {file}`enhancers.js` in the {file}`BlockSchema` folder with the following content: + +```js +const schemaEnhancerVariation02 = ({ formData, schema, intl }) => { + // schema holds the original schema (see the Schema.js file) + // so we need to define the new property under `schema.properties` + // and push its name to the relevant fieldset, in our case the first one (note the `fieldsets[0]`) + schema.properties.color = { + title: 'Color', + }; + schema.fieldsets[0].fields.push('color'); + return schema; +}; + +export default schemaEnhancerVariation02; + +``` + +## Variations + +Now we need to create one or more variations that will be available for this block. + +Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import React from 'react'; + +const View = (props) => { + const { data } = props; + return ( + <> +

Variation View 01

+
+
    +
  • Title: {data.title}
    • +
  • URL: {data.url}
    • +
+
+ + ); +}; + +export default View; +``` +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock` folder with the following contents: + +```jsx +import React from 'react'; + +const View = (props) => { + const { data } = props; + return ( + <> +

Variation View 02

+
+
    +
  • Title: {data.title}
    • +
  • URL: {data.url}
    • +
+
+ + ); +}; + +export default View; +``` + +As you can see, in this case the variations are pretty much the same, the only difference is the text that is rendered in the `

` tag. But it can be anything. + +## Block configuration + +With all the block components ready, you need to register the block into Volto. + +To do so, open your addon's {file}`index.js` file, that will have the following contents: + +```js +const applyConfig = (config) => { + config.settings.isMultilingual = false; + config.settings.supportedLanguages = ['en']; + config.settings.defaultLanguage = 'en'; + + + return config; +} + +export default applyConfig; +``` + +And before the last `return config;` statement, write the following configuration: + +```js + config.blocks.blocksConfig.block06 = { + id: 'block06', // this is the block id, it must match the id on the previous line + title: 'Block 06', // this is the block title + view: View06, // this is the block's view component + //edit: Edit05, + blockSchema: Schema06, // this is the schema that will be used to render the edit form + icon: imagesSVG, // this is the image that will be shown in the block selector + sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block + // these are the variations available for this block + variations: [ + { + id: 'variation01', // this is the id of the variation + title: 'Variation 01', // this is the title of the variation + isDefault: true, // this signals if this is the default variation for this block + template: VariationView0601, // this is the component that will render the variation + }, + { + id: 'variation02', + title: 'Variation 02', + isDefault: false, + template: VariationView0602, + schemaEnhancer: schemaEnhancerBlock06Variation02, // this is the schema enhancer definition + }, + ], + }; + +``` + +On the top of the file you will need to import the relevant components, as follows: + +```js +import View06 from './components/ExampleBlock/View'; +import Schema06 from './components/ExampleBlock/Schema'; +import VariationView0601 from './components/ExampleBlock/VariationView01'; +import VariationView0602 from './components/ExampleBlock/VariationView02'; +import schemaEnhancerBlock06Variation02 from './components/ExampleBlock/enhancers'; + +// This is the icon we use for the example, use a meaningful one or provide your own image. +import imagesSVG from '@plone/volto/icons/images.svg'; +``` + +## See it in action + +Your block is ready to be used in your site. + +Restart your Volto site and you will be able to add it using the block add form. From 476a36bc48a3685cf5db3db9b05ae5ea78cd6a7f Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 17:51:29 +0100 Subject: [PATCH 11/52] change folder names --- .../blocks/examples/customschemaandview.md | 12 +++++----- .../examples/customviewandvariations.md | 20 ++++++++--------- .../customviewvariationsandschemaenhancer.md | 22 +++++++++---------- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md index dc68451f30..7872256465 100644 --- a/docs/source/blocks/examples/customschemaandview.md +++ b/docs/source/blocks/examples/customschemaandview.md @@ -19,11 +19,11 @@ What we need to do is to define the schema, the view component, and configure th In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. -Name this folder as {file}`ExampleBlock`. +Name this folder as {file}`ExampleBlock02`. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock02` folder, with the following contents: ```js import messages from './messages'; @@ -60,7 +60,7 @@ export default Schema; As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. -So we need a file {file}`messages.js` in the same {file}`ExampleBlock` folder with the following contents: +So we need a file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents: ```js import { defineMessages } from 'react-intl'; @@ -93,7 +93,7 @@ The view component will have all the required logic to show the information save In our case will be a samll HTML fragment. -Create a file {file}`View.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`View.jsx` in the {file}`ExampleBlock02` folder with the following contents: ```jsx import cx from 'classnames'; @@ -154,8 +154,8 @@ config.blocks.blocksConfig.block02 = { On the top of the file you will need to import the relevant components, as follows: ```js -import View02 from './components/ExampleBlock/View'; -import Schema02 from './components/ExampleBlock/Schema'; +import View02 from './components/ExampleBlock02/View'; +import Schema02 from './components/ExampleBlock02/Schema'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; diff --git a/docs/source/blocks/examples/customviewandvariations.md b/docs/source/blocks/examples/customviewandvariations.md index 4663d6793e..20759b4f3c 100644 --- a/docs/source/blocks/examples/customviewandvariations.md +++ b/docs/source/blocks/examples/customviewandvariations.md @@ -19,11 +19,11 @@ What we need to do is to define the schema, the view component, the variations a In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. -Name this folder as {file}`ExampleBlock`. +Name this folder as {file}`ExampleBlock05`. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock05` folder, with the following contents: ```js import messages from './messages'; @@ -60,7 +60,7 @@ export default Schema; As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. -So we need a file {file}`messages.js` in the same {file}`ExampleBlock` folder with the following contents: +So we need a file {file}`messages.js` in the same {file}`ExampleBlock05` folder with the following contents: ```js import { defineMessages } from 'react-intl'; @@ -93,7 +93,7 @@ In this case, as we are using variations, the view component needs to use the va This is easily achieved using the `variation` coming on the `props` of the block. -Create a file {file}`View.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`View.jsx` in the {file}`ExampleBlock05` folder with the following contents: ```jsx import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; @@ -133,7 +133,7 @@ export default withBlockExtensions(View); Now we need to create one or more variations that will be available for this block. -Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock05` folder with the following contents: ```jsx import React from 'react'; @@ -155,7 +155,7 @@ const View = (props) => { export default View; ``` -Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock05` folder with the following contents: ```jsx import React from 'react'; @@ -232,10 +232,10 @@ And before the last `return config;` statement, write the following configuratio On the top of the file you will need to import the relevant components, as follows: ```js -import View05 from './components/ExampleBlock/View'; -import Schema05 from './components/ExampleBlock/Schema'; -import VariationView0501 from './components/ExampleBlock/VariationView01'; -import VariationView0502 from './components/ExampleBlock/VariationView02'; +import View05 from './components/ExampleBlock05/View'; +import Schema05 from './components/ExampleBlock05/Schema'; +import VariationView0501 from './components/ExampleBlock05/VariationView01'; +import VariationView0502 from './components/ExampleBlock05/VariationView02'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index 27dca2925a..cbe0b97b9a 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -21,11 +21,11 @@ What we need to do is to define the schema, the view component, the variations, In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. -Name this folder as {file}`ExampleBlock`. +Name this folder as {file}`ExampleBlock06`. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock06` folder, with the following contents: ```js import messages from './messages'; @@ -62,7 +62,7 @@ export default Schema; As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. -So we need a file {file}`messages.js` in the same {file}`ExampleBlock` folder with the following contents: +So we need a file {file}`messages.js` in the same {file}`ExampleBlock06` folder with the following contents: ```js import { defineMessages } from 'react-intl'; @@ -95,7 +95,7 @@ In this case, as we are using variations, the view component needs to use the va This is easily achieved using the `variation` coming on the `props` of the block. -Create a file {file}`View.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`View.jsx` in the {file}`ExampleBlock06` folder with the following contents: ```jsx import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; @@ -157,7 +157,7 @@ export default schemaEnhancerVariation02; Now we need to create one or more variations that will be available for this block. -Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock06` folder with the following contents: ```jsx import React from 'react'; @@ -179,7 +179,7 @@ const View = (props) => { export default View; ``` -Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock` folder with the following contents: +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock06` folder with the following contents: ```jsx import React from 'react'; @@ -257,11 +257,11 @@ And before the last `return config;` statement, write the following configuratio On the top of the file you will need to import the relevant components, as follows: ```js -import View06 from './components/ExampleBlock/View'; -import Schema06 from './components/ExampleBlock/Schema'; -import VariationView0601 from './components/ExampleBlock/VariationView01'; -import VariationView0602 from './components/ExampleBlock/VariationView02'; -import schemaEnhancerBlock06Variation02 from './components/ExampleBlock/enhancers'; +import View06 from './components/ExampleBlock06/View'; +import Schema06 from './components/ExampleBlock06/Schema'; +import VariationView0601 from './components/ExampleBlock06/VariationView01'; +import VariationView0602 from './components/ExampleBlock06/VariationView02'; +import schemaEnhancerBlock06Variation02 from './components/ExampleBlock06/enhancers'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; From 9c09ad900c806de126100cb69be52ab92997eaf6 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Mon, 30 Dec 2024 17:53:55 +0100 Subject: [PATCH 12/52] volto verssion --- .../blocks/examples/customviewvariationsandschemaenhancer.md | 2 +- docs/source/blocks/examples/index.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index cbe0b97b9a..c2973f23ff 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -13,7 +13,7 @@ myst: We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. This variation is shown as an additional option in the schema editor and lets the webmaster to change how this block is viewed. Think of it as a different view of the same block. -A schema enhancer is an option of a variation. Using this schema enhancer, the block schema can be extended to have additional fields. +A {term}`schema enhancer` is an option of a variation. Using this schema enhancer, the block schema can be extended to have additional fields. What we need to do is to define the schema, the view component, the variations, the schema enhancer and configure the block settings. diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index 358aa7b634..59f07e83a5 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -11,6 +11,8 @@ myst: This part of the documentation shows some examples of custom blocks that you can use as a base to develop your own blocks. +These blocks have been tested using Volto 18.4.0. + ```{toctree} :maxdepth: 1 From 4d75f668d616c394fc80d12a7c71016a393bb6e0 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Tue, 31 Dec 2024 16:19:02 +0100 Subject: [PATCH 13/52] changelog --- packages/volto/news/6560.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 packages/volto/news/6560.documentation diff --git a/packages/volto/news/6560.documentation b/packages/volto/news/6560.documentation new file mode 100644 index 0000000000..ccf7539810 --- /dev/null +++ b/packages/volto/news/6560.documentation @@ -0,0 +1 @@ +Add Volto block examples in the documentation @erral From 68c42a4f1feb3aaedd035200f235dc4a82e08c33 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:43:24 +0100 Subject: [PATCH 14/52] Update docs/source/blocks/examples/index.md Co-authored-by: Steve Piercy --- docs/source/blocks/examples/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index 59f07e83a5..e06f313f8b 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -1,7 +1,7 @@ --- myst: html_meta: - "description": "Volto block examples." + "description": "Volto block examples" "property=og:description": "Volto block examples." "property=og:title": "Block examples" "keywords": "Volto, React, blocks, example, edit, view, Plone" From a75f94ae0fc96405fe55d8268177e78fcc7cdc82 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:43:34 +0100 Subject: [PATCH 15/52] Update docs/source/blocks/examples/index.md Co-authored-by: Steve Piercy --- docs/source/blocks/examples/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index e06f313f8b..e020206552 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -2,7 +2,7 @@ myst: html_meta: "description": "Volto block examples" - "property=og:description": "Volto block examples." + "property=og:description": "Volto block examples" "property=og:title": "Block examples" "keywords": "Volto, React, blocks, example, edit, view, Plone" --- From 7907f50bc058b80626d6ee742ff8eb2202fe1eca Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:43:42 +0100 Subject: [PATCH 16/52] Update docs/source/blocks/examples/index.md Co-authored-by: Steve Piercy --- docs/source/blocks/examples/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index e020206552..32937cd01f 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -3,7 +3,7 @@ myst: html_meta: "description": "Volto block examples" "property=og:description": "Volto block examples" - "property=og:title": "Block examples" + "property=og:title": "Volto block examples" "keywords": "Volto, React, blocks, example, edit, view, Plone" --- From 13056b180ae4edabf9f7a4e4af6886becc20329e Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:43:50 +0100 Subject: [PATCH 17/52] Update docs/source/blocks/examples/index.md Co-authored-by: Steve Piercy --- docs/source/blocks/examples/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index 32937cd01f..3479586e6d 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -7,7 +7,7 @@ myst: "keywords": "Volto, React, blocks, example, edit, view, Plone" --- -# Volto Block examples +# Volto block examples This part of the documentation shows some examples of custom blocks that you can use as a base to develop your own blocks. From 8eb9ea2e95ae74985013e161db3f17ad53454260 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:43:56 +0100 Subject: [PATCH 18/52] Update docs/source/blocks/examples/customviewvariationsandschemaenhancer.md Co-authored-by: Steve Piercy --- .../blocks/examples/customviewvariationsandschemaenhancer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index c2973f23ff..ad8dddbb43 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -208,7 +208,7 @@ As you can see, in this case the variations are pretty much the same, the only d With all the block components ready, you need to register the block into Volto. -To do so, open your addon's {file}`index.js` file, that will have the following contents: +To do so, open your add-on's {file}`index.js` file, and add the following contents. ```js const applyConfig = (config) => { From de133a91a398fb207ba0987abbda83aee53782e9 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:44:04 +0100 Subject: [PATCH 19/52] Update docs/source/blocks/examples/customviewvariationsandschemaenhancer.md Co-authored-by: Steve Piercy --- .../blocks/examples/customviewvariationsandschemaenhancer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index ad8dddbb43..ee6fbc81bf 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -223,7 +223,7 @@ const applyConfig = (config) => { export default applyConfig; ``` -And before the last `return config;` statement, write the following configuration: +Before the last `return config;` statement, write the following configuration. ```js config.blocks.blocksConfig.block06 = { From 5b70643a3ee01a4a141deda6413f718d4c1518ea Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:44:13 +0100 Subject: [PATCH 20/52] Update docs/source/blocks/examples/customviewvariationsandschemaenhancer.md Co-authored-by: Steve Piercy --- .../blocks/examples/customviewvariationsandschemaenhancer.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index ee6fbc81bf..71d10d07dd 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -251,7 +251,6 @@ Before the last `return config;` statement, write the following configuration. }, ], }; - ``` On the top of the file you will need to import the relevant components, as follows: From e507eed2db647bf9a11de1dfd995c4c07558e608 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:44:21 +0100 Subject: [PATCH 21/52] Update docs/source/blocks/examples/customviewvariationsandschemaenhancer.md Co-authored-by: Steve Piercy --- .../blocks/examples/customviewvariationsandschemaenhancer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index 71d10d07dd..9f22cd7d77 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -253,7 +253,7 @@ Before the last `return config;` statement, write the following configuration. }; ``` -On the top of the file you will need to import the relevant components, as follows: +At the top of the file, import the relevant components as follows. ```js import View06 from './components/ExampleBlock06/View'; From 3fc9aa28626e3006c91763d3f5d26d0e9898c5ee Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:44:29 +0100 Subject: [PATCH 22/52] Update docs/source/blocks/examples/customviewvariationsandschemaenhancer.md Co-authored-by: Steve Piercy --- .../blocks/examples/customviewvariationsandschemaenhancer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index 9f22cd7d77..07d501c22c 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -270,4 +270,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; Your block is ready to be used in your site. -Restart your Volto site and you will be able to add it using the block add form. +Restart your Volto site, and you can add it using the block add form. From 689615496655c7b0bdf48ee2f0e5d1e6cb057252 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:50:57 +0100 Subject: [PATCH 23/52] Update packages/volto/news/6560.documentation Co-authored-by: Steve Piercy --- packages/volto/news/6560.documentation | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/volto/news/6560.documentation b/packages/volto/news/6560.documentation index ccf7539810..6638701cfa 100644 --- a/packages/volto/news/6560.documentation +++ b/packages/volto/news/6560.documentation @@ -1 +1 @@ -Add Volto block examples in the documentation @erral +Add Volto block examples in the documentation. @erral From ff52feee0794fb680b0a615c574c373e64add63a Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:51:15 +0100 Subject: [PATCH 24/52] Update docs/source/blocks/examples/customschemaandview.md Co-authored-by: Steve Piercy --- docs/source/blocks/examples/customschemaandview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md index 7872256465..3e9bc2e905 100644 --- a/docs/source/blocks/examples/customschemaandview.md +++ b/docs/source/blocks/examples/customschemaandview.md @@ -3,7 +3,7 @@ myst: html_meta: "description": "Volto block with custom schema and view components" "property=og:description": "Volto block with custom schema and view components" - "property=og:title": "Volto block with custom schema" + "property=og:title": "Volto block with custom schema and view components" "keywords": "Volto, React, blocks, grid, container, Plone" --- From ef0983892da539a05337a813522065d4b808196f Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:51:32 +0100 Subject: [PATCH 25/52] Update docs/source/blocks/examples/customschemaandview.md Co-authored-by: Steve Piercy --- docs/source/blocks/examples/customschemaandview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md index 3e9bc2e905..03d7684ec3 100644 --- a/docs/source/blocks/examples/customschemaandview.md +++ b/docs/source/blocks/examples/customschemaandview.md @@ -11,7 +11,7 @@ myst: # Block with a custom schema -We can create a block with several settings defined using a schema, and let Volto render the edit form by itself. +You can create a block with several settings defined using a schema, and let Volto render the edit form by itself. What we need to do is to define the schema, the view component, and configure the block settings. From f87d1b41b36d2d7c21dfc21778a5830aa89042a1 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 16:05:07 +0100 Subject: [PATCH 26/52] Apply suggestions from code review Co-authored-by: Steve Piercy --- .../blocks/examples/customschemaandview.md | 32 +++++------ .../examples/customviewandvariations.md | 51 +++++++++-------- .../customviewvariationsandschemaenhancer.md | 57 +++++++++++-------- 3 files changed, 72 insertions(+), 68 deletions(-) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/customschemaandview.md index 03d7684ec3..28da14ce11 100644 --- a/docs/source/blocks/examples/customschemaandview.md +++ b/docs/source/blocks/examples/customschemaandview.md @@ -13,17 +13,15 @@ myst: You can create a block with several settings defined using a schema, and let Volto render the edit form by itself. -What we need to do is to define the schema, the view component, and configure the block settings. +To do so, define the schema, the view component, and configure the block settings. ## Preparations -In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. - -Name this folder as {file}`ExampleBlock02`. +In your Volto add-on, create a subfolder {file}`ExampleBlock02` inside the {file}`components` folder to save all the files required to create a block. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock02` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock02` folder, with the following contents. ```js import messages from './messages'; @@ -58,9 +56,9 @@ export default Schema; ## Messages -As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. - -So we need a file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents: +As you may have noted, you prepared the block for internationalization. +{term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. +To add translatable messages, create file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents. ```js import { defineMessages } from 'react-intl'; @@ -90,19 +88,18 @@ export default messages; ## View component The view component will have all the required logic to show the information saved on the block. +It will be a small HTML fragment. -In our case will be a samll HTML fragment. - -Create a file {file}`View.jsx` in the {file}`ExampleBlock02` folder with the following contents: +Create a file {file}`View.jsx` in the {file}`ExampleBlock02` folder with the following contents. ```jsx import cx from 'classnames'; import React from 'react'; const View = (props) => { - // data holds the values entered in the block edit form - // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` - // style holds the CSS properties injected to this block by Volto's `Block Sytle Wrapper` + // `data` holds the values entered in the block edit form. + // `className` holds the CSS class names injected into this block by Volto's `styleClassNameExtenders`. + // `style` holds the CSS properties injected into this block by Volto's `Block Sytle Wrapper`. const { data, className, style } = props; return (
@@ -122,7 +119,7 @@ export default View; With all the block components ready, you need to register the block into Volto. -To do so, open your addon's {file}`index.js` file, that will have the following contents: +To do so, open your add-on's {file}`index.js` file, and insert the following contents. ```js const applyConfig = (config) => { @@ -151,7 +148,7 @@ config.blocks.blocksConfig.block02 = { }; ``` -On the top of the file you will need to import the relevant components, as follows: +At the top of the file, import the relevant components as follows. ```js import View02 from './components/ExampleBlock02/View'; @@ -164,5 +161,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; ## See it in action Your block is ready to be used in your site. - -Restart your Volto site and you will be able to add it using the block add form. +Restart your Volto site, and you can add it using the block add form. diff --git a/docs/source/blocks/examples/customviewandvariations.md b/docs/source/blocks/examples/customviewandvariations.md index 20759b4f3c..fa09beee32 100644 --- a/docs/source/blocks/examples/customviewandvariations.md +++ b/docs/source/blocks/examples/customviewandvariations.md @@ -3,8 +3,8 @@ myst: html_meta: "description": "Volto block with custom schema and view components using variations" "property=og:description": "Volto block with custom schema and view components using variations" - "property=og:title": "Volto block with custom schema and variations" - "keywords": "Volto, React, blocks, grid, container, Plone" + "property=og:title": "Volto block with custom schema and view components using variations" + "keywords": "Volto, React, blocks, schema, variation, view component, Plone" --- (custom-schema-view-and-variations)= @@ -13,17 +13,15 @@ myst: We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. This variation is shown as an additional option in the schema editor and lets the webmaster to change how this block is viewed. Think of it as a different view of the same block -What we need to do is to define the schema, the view component, the variations and configure the block settings. +To do so, define the schema, view component, and variations, then configure the block settings. ## Preparations -In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. - -Name this folder as {file}`ExampleBlock05`. +In your Volto add-on, create a subfolder {file}`ExampleBlock05` inside the {file}`components` folder to save all the files required to create a block. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock05` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock05` folder, with the following contents. ```js import messages from './messages'; @@ -58,9 +56,10 @@ export default Schema; ## Messages -As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. +As you may have noted, you prepared the block for internationalization. +{term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. -So we need a file {file}`messages.js` in the same {file}`ExampleBlock05` folder with the following contents: +To do so, create a file {file}`messages.js` in the same {file}`ExampleBlock05` folder with the following contents. ```js import { defineMessages } from 'react-intl'; @@ -89,11 +88,10 @@ export default messages; ## View component -In this case, as we are using variations, the view component needs to use the variation template to render the contents of the block. - -This is easily achieved using the `variation` coming on the `props` of the block. +For variations, the view component needs to use the variation template to render the contents of the block. +You can do so using the `variation` from the `props` of the block. -Create a file {file}`View.jsx` in the {file}`ExampleBlock05` folder with the following contents: +Create a file {file}`View.jsx` in the {file}`ExampleBlock05` folder with the following contents. ```jsx import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; @@ -101,10 +99,10 @@ import cx from 'classnames'; import React from 'react'; const View = (props) => { - // data holds the values entered in the block edit form - // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` - // style holds the CSS properties injected to this block by Volto's `Block Sytle Wrapper` - // variation holds the variation selected in the block editor, and it is an object as defined in the block configuration + // `data` holds the values entered in the block edit form. + // `className` holds the CSS class names injected into this block by Volto's `styleClassNameExtenders`. + // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper`. + // `variation` holds the variation selected in the block editor, and it is an object as defined in the block configuration. const { data, className, style, variation } = props; const BodyTemplate = variation?.template; @@ -131,9 +129,9 @@ export default withBlockExtensions(View); ## Variations -Now we need to create one or more variations that will be available for this block. +Next create one or more variations that will be available for this block. -Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock05` folder with the following contents: +Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock05` folder with the following contents. ```jsx import React from 'react'; @@ -155,7 +153,8 @@ const View = (props) => { export default View; ``` -Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock05` folder with the following contents: + +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock05` folder with the following contents. ```jsx import React from 'react'; @@ -178,13 +177,15 @@ const View = (props) => { export default View; ``` -As you can see, in this case the variations are pretty much the same, the only difference is the text that is rendered in the `

` tag. But it can be anything. +As you can see in this basic example, the variations are pretty much the same. +The only difference is the text that is rendered in the `

` tag. +But it can be anything. ## Block configuration With all the block components ready, you need to register the block into Volto. -To do so, open your addon's {file}`index.js` file, that will have the following contents: +To do so, open your add-on's {file}`index.js` file, and add the following contents. ```js const applyConfig = (config) => { @@ -199,7 +200,7 @@ const applyConfig = (config) => { export default applyConfig; ``` -And before the last `return config;` statement, write the following configuration: +Before the last `return config;` statement, write the following configuration. ```js config.blocks.blocksConfig.block05 = { @@ -229,7 +230,7 @@ And before the last `return config;` statement, write the following configuratio ``` -On the top of the file you will need to import the relevant components, as follows: +At the top of the file, import the relevant components as follows. ```js import View05 from './components/ExampleBlock05/View'; @@ -245,4 +246,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; Your block is ready to be used in your site. -Restart your Volto site and you will be able to add it using the block add form. +Restart your Volto site, and you can add it using the block add form. diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md index 07d501c22c..61ea1c8454 100644 --- a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md +++ b/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md @@ -3,29 +3,31 @@ myst: html_meta: "description": "Volto block with custom schema and view components using variations and a schema enhancer in one of the variations" "property=og:description": "Volto block with custom schema and view components using variations and a schema enhancer in one of the variations" - "property=og:title": "Volto block with custom schema, variations and schema enhancer" - "keywords": "Volto, React, blocks, grid, container, Plone" + "property=og:title": "Volto block with custom schema, variations, and schema enhancer" + "keywords": "Volto, React, blocks, variation, custom, schema, enhancer, Plone" --- (custom-schema-view-variations-schema-enhancer)= -# Block with a custom schema, variations and a schema enhancer in a variation. +# Block with a custom schema, variations, and a schema enhancer in a variation. -We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. This variation is shown as an additional option in the schema editor and lets the webmaster to change how this block is viewed. Think of it as a different view of the same block. +This example builds upon the previous example, {doc}`custom-view-and-variations`, where you can create a block with a custom schema, variations, and a schema enhancer in one of the variations. +A {term}`variation` is an alternative view of a block. +The variation is shown as an additional option in the schema editor, and lets the developer change how this block is viewed. -A {term}`schema enhancer` is an option of a variation. Using this schema enhancer, the block schema can be extended to have additional fields. +A {term}`schema enhancer` is an option of a variation. +Using this schema enhancer, you can extend the block schema to have additional fields. -What we need to do is to define the schema, the view component, the variations, the schema enhancer and configure the block settings. +To do so, define the schema, view component, variations, and schema enhancer, then configure the block settings. ## Preparations -In your volto addon, create a folder inside the {file}`components` folder to save all the files required to create a block. +In your Volto add-on, create a subfolder {file}`ExampleBlock06` inside the {file}`components` folder to save all the files required to create a block. -Name this folder as {file}`ExampleBlock06`. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock06` folder, with the following contents: +Create a {file}`Schema.js` file inside the {file}`ExampleBlock06` folder, with the following contents. ```js import messages from './messages'; @@ -60,9 +62,10 @@ export default Schema; ## Messages -As you have noted, we have prepared the block to be internationalized, {term}`internanationalization` (i18n), is the process of creating user interfaces which are suitable for different languages and cultural contexts. +As you may have noted, you prepared the block for internationalization. +{term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. -So we need a file {file}`messages.js` in the same {file}`ExampleBlock06` folder with the following contents: +Create a file {file}`messages.js` in the same {file}`ExampleBlock06` folder with the following contents. ```js import { defineMessages } from 'react-intl'; @@ -91,11 +94,11 @@ export default messages; ## View component -In this case, as we are using variations, the view component needs to use the variation template to render the contents of the block. +For variations, the view component needs to use the variation template to render the contents of the block. -This is easily achieved using the `variation` coming on the `props` of the block. +You can do so using the `variation` from the `props` of the block. -Create a file {file}`View.jsx` in the {file}`ExampleBlock06` folder with the following contents: +Create a file {file}`View.jsx` in the {file}`ExampleBlock06` folder with the following contents. ```jsx import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; @@ -103,10 +106,10 @@ import cx from 'classnames'; import React from 'react'; const View = (props) => { - // data holds the values entered in the block edit form + // `data` holds the values entered in the block edit form // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` - // style holds the CSS properties injected to this block by Volto's `Block Sytle Wrapper` - // variation holds the variation selected in the block editor, and it is an object as defined in the block configuration + // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper` + // `variation` holds the variation selected in the block editor, and it is an object as defined in the block configuration const { data, className, style, variation } = props; const BodyTemplate = variation?.template; @@ -133,15 +136,16 @@ export default withBlockExtensions(View); ## Schema enhancer -We need to configure the schema enhancer function. In this case we will be adding a new field named `color` when using the Variation 2. +Next you need to configure the schema enhancer function. +In this example, you will add a new field named `color` when using `schemaEnhancerVariation02`. -Create a file {file}`enhancers.js` in the {file}`BlockSchema` folder with the following content: +Create a file {file}`enhancers.js` in the {file}`BlockSchema` folder with the following content. ```js const schemaEnhancerVariation02 = ({ formData, schema, intl }) => { // schema holds the original schema (see the Schema.js file) - // so we need to define the new property under `schema.properties` - // and push its name to the relevant fieldset, in our case the first one (note the `fieldsets[0]`) + // so you need to define the new property under `schema.properties` + // and push its name to the relevant fieldset, in this case the first one (note the `fieldsets[0]`) schema.properties.color = { title: 'Color', }; @@ -155,9 +159,9 @@ export default schemaEnhancerVariation02; ## Variations -Now we need to create one or more variations that will be available for this block. +Next create one or more variations that will be available for this block. -Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock06` folder with the following contents: +Create a file {file}`VariationView01.jsx` in the {file}`ExampleBlock06` folder with the following contents. ```jsx import React from 'react'; @@ -179,7 +183,8 @@ const View = (props) => { export default View; ``` -Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock06` folder with the following contents: + +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock06` folder with the following contents. ```jsx import React from 'react'; @@ -202,7 +207,9 @@ const View = (props) => { export default View; ``` -As you can see, in this case the variations are pretty much the same, the only difference is the text that is rendered in the `

` tag. But it can be anything. +As you can see, the variations are pretty much the same. +The only difference is the text that is rendered in the `

` tag. +But it can be anything. ## Block configuration From aa274bc39bcf2287dea7ca4323accb8c4de420fa Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:45:45 +0100 Subject: [PATCH 27/52] rename files --- .../{customschemaandview.md => custom-schema-and-view.md} | 0 ...omviewandvariations.md => custom-view-and-variations.md} | 0 ...cer.md => custom-view-variations-and-schema-enhancer.md} | 0 docs/source/blocks/examples/index.md | 6 +++--- 4 files changed, 3 insertions(+), 3 deletions(-) rename docs/source/blocks/examples/{customschemaandview.md => custom-schema-and-view.md} (100%) rename docs/source/blocks/examples/{customviewandvariations.md => custom-view-and-variations.md} (100%) rename docs/source/blocks/examples/{customviewvariationsandschemaenhancer.md => custom-view-variations-and-schema-enhancer.md} (100%) diff --git a/docs/source/blocks/examples/customschemaandview.md b/docs/source/blocks/examples/custom-schema-and-view.md similarity index 100% rename from docs/source/blocks/examples/customschemaandview.md rename to docs/source/blocks/examples/custom-schema-and-view.md diff --git a/docs/source/blocks/examples/customviewandvariations.md b/docs/source/blocks/examples/custom-view-and-variations.md similarity index 100% rename from docs/source/blocks/examples/customviewandvariations.md rename to docs/source/blocks/examples/custom-view-and-variations.md diff --git a/docs/source/blocks/examples/customviewvariationsandschemaenhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md similarity index 100% rename from docs/source/blocks/examples/customviewvariationsandschemaenhancer.md rename to docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index 3479586e6d..fca4ab4e49 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -16,7 +16,7 @@ These blocks have been tested using Volto 18.4.0. ```{toctree} :maxdepth: 1 -customschemaandview -customviewandvariations -customviewvariationsandschemaenhancer +custom-schema-and-view +custom-view-and-variations +custom-view-variations-and-schema-enhancer ``` From 9a5633184e8f6dfa33c073dbbcfff5a5894aebf7 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Fri, 3 Jan 2025 15:50:51 +0100 Subject: [PATCH 28/52] minor fixes --- docs/source/blocks/examples/custom-schema-and-view.md | 4 ++++ .../examples/custom-view-variations-and-schema-enhancer.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 28da14ce11..2cad62e990 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -161,4 +161,8 @@ import imagesSVG from '@plone/volto/icons/images.svg'; ## See it in action Your block is ready to be used in your site. +<<<<<<< HEAD +======= + +>>>>>>> 168bd09a7 (minor fixes) Restart your Volto site, and you can add it using the block add form. diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 61ea1c8454..086adb8f02 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -139,7 +139,7 @@ export default withBlockExtensions(View); Next you need to configure the schema enhancer function. In this example, you will add a new field named `color` when using `schemaEnhancerVariation02`. -Create a file {file}`enhancers.js` in the {file}`BlockSchema` folder with the following content. +Create a file {file}`enhancers.js` in the {file}`BlockSchema06` folder with the following content: ```js const schemaEnhancerVariation02 = ({ formData, schema, intl }) => { From 938ae9ad68a1081893427d1aa060ff7b1ffff86a Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sat, 4 Jan 2025 08:54:27 +0100 Subject: [PATCH 29/52] Update docs/source/blocks/settings.md Co-authored-by: Steve Piercy --- docs/source/blocks/settings.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/blocks/settings.md b/docs/source/blocks/settings.md index ed173964b0..936c4ad223 100644 --- a/docs/source/blocks/settings.md +++ b/docs/source/blocks/settings.md @@ -48,7 +48,6 @@ const customBlocks = { // Required for alternate default block types implementations. // See also [Settings reference](/configuration/settings-reference) }, - // A block can have a function that returns the schema or directly the schema // of the block that will be automatically rendered in the sidebar editor // in case that the `edit` setting of the block is set to `null` blockSchema: CustomSchema, From 34e442379acc0402a8fecc36119714f63d533c5f Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sat, 4 Jan 2025 08:54:54 +0100 Subject: [PATCH 30/52] Update docs/source/blocks/settings.md Co-authored-by: Steve Piercy --- docs/source/blocks/settings.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/blocks/settings.md b/docs/source/blocks/settings.md index 936c4ad223..5125ae766c 100644 --- a/docs/source/blocks/settings.md +++ b/docs/source/blocks/settings.md @@ -48,7 +48,6 @@ const customBlocks = { // Required for alternate default block types implementations. // See also [Settings reference](/configuration/settings-reference) }, - // of the block that will be automatically rendered in the sidebar editor // in case that the `edit` setting of the block is set to `null` blockSchema: CustomSchema, // A block can have an schema enhancer function with the signature: (schema) => schema From 158ec29fbeddc4563b3259e030c50ec8067e73bb Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:25:35 -0800 Subject: [PATCH 31/52] Apply suggestions from code review --- docs/source/blocks/settings.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/blocks/settings.md b/docs/source/blocks/settings.md index 5125ae766c..1a08cc3fd0 100644 --- a/docs/source/blocks/settings.md +++ b/docs/source/blocks/settings.md @@ -48,7 +48,9 @@ const customBlocks = { // Required for alternate default block types implementations. // See also [Settings reference](/configuration/settings-reference) }, - // in case that the `edit` setting of the block is set to `null` + // The `blockSchema` property can either be a schema by itself + // (a JavaScript object describing the schema), + // or a function that returns a schema. blockSchema: CustomSchema, // A block can have an schema enhancer function with the signature: (schema) => schema // It can be either be at block level (it's applied always), at a variation level From 9e34489998d45328460bec5195cdf1520bb0e372 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:27:42 -0800 Subject: [PATCH 32/52] Clean up bad merge --- docs/source/blocks/examples/custom-schema-and-view.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 2cad62e990..0741475bb3 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -161,8 +161,5 @@ import imagesSVG from '@plone/volto/icons/images.svg'; ## See it in action Your block is ready to be used in your site. -<<<<<<< HEAD -======= ->>>>>>> 168bd09a7 (minor fixes) Restart your Volto site, and you can add it using the block add form. From 682871d9628ecfbdafd5e64f6bdee689ad0efd93 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:29:12 -0800 Subject: [PATCH 33/52] trim code blocks --- docs/source/blocks/editcomponent.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/source/blocks/editcomponent.md b/docs/source/blocks/editcomponent.md index f47d405586..46b52a1831 100644 --- a/docs/source/blocks/editcomponent.md +++ b/docs/source/blocks/editcomponent.md @@ -40,13 +40,11 @@ const Edit = (props) => { ) } - ``` Everything that's inside the `SidebarPortal` component will be rendered in the sidebar. If you need an extra layer of configuration within `SidebarPortal`, you can use `SidebarPopup`. ```jsx - import { SidebarPopup } from '@plone/volto/components'; const Edit = (props) => { @@ -60,7 +58,6 @@ const Edit = (props) => { ) } - ``` ## Schema driven automated block settings forms @@ -148,7 +145,6 @@ const Edit = (props) => { ; ) } - ``` ## Object Browser From a7d2fc0927f7a181ca8e4f149532439b15f880dc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:31:31 -0800 Subject: [PATCH 34/52] grammar --- docs/source/blocks/examples/custom-schema-and-view.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 0741475bb3..8ca9ee26a3 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -58,7 +58,7 @@ export default Schema; As you may have noted, you prepared the block for internationalization. {term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. -To add translatable messages, create file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents. +To add translatable messages, create a file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents. ```js import { defineMessages } from 'react-intl'; From 4e5b9e05c09355d630f00acb1ef132b66643a70f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:34:00 -0800 Subject: [PATCH 35/52] punctuation --- docs/source/blocks/examples/custom-schema-and-view.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 8ca9ee26a3..f427272c34 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -134,7 +134,7 @@ const applyConfig = (config) => { export default applyConfig; ``` -And before the last `return config;` statement, write the following configuration: +And before the last `return config;` statement, write the following configuration. ```js config.blocks.blocksConfig.block02 = { From d149cfe51cb5cf5bc28a6986660ebc72ddce3e5f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:34:46 -0800 Subject: [PATCH 36/52] grammar --- docs/source/blocks/examples/custom-schema-and-view.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index f427272c34..a4db910ac3 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -134,7 +134,7 @@ const applyConfig = (config) => { export default applyConfig; ``` -And before the last `return config;` statement, write the following configuration. +Before the last `return config;` statement, write the following configuration. ```js config.blocks.blocksConfig.block02 = { From 739e58876127908d450988abf2e6be73e1253a25 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:38:52 -0800 Subject: [PATCH 37/52] s/webmaster/editor, one sentence per line, shorten intro --- docs/source/blocks/examples/custom-view-and-variations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index fa09beee32..fe03dff915 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -11,7 +11,9 @@ myst: # Block with a custom schema and variations -We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. This variation is shown as an additional option in the schema editor and lets the webmaster to change how this block is viewed. Think of it as a different view of the same block +We can create a block that uses `variations`. +A {term}`variation` is an alternative view of a block. +This variation is shown as an additional option in the schema editor, and lets the editor change how this block is viewed. To do so, define the schema, view component, and variations, then configure the block settings. From 3d83b5497c3ee0dd8f2f0709a7c6cce834ad3f3b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:43:12 -0800 Subject: [PATCH 38/52] Move comment about HOC from code block to narrative text --- docs/source/blocks/examples/custom-view-and-variations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index fe03dff915..f44da69385 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -124,11 +124,11 @@ const View = (props) => { ); }; -// the `withBlockExtensions` HOC, makes the variation selector available in the block edit form -// and provides the `variation` property in the props. export default withBlockExtensions(View); ``` +The `withBlockExtensions` {term}`HOC` makes the variation selector available in the block edit form and provides the `variation` property in the props. + ## Variations Next create one or more variations that will be available for this block. From bc5e43681ebd9d28e648dab57f3f4189017b0a23 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 4 Jan 2025 01:59:47 -0800 Subject: [PATCH 39/52] Apply suggestions from code review Also move HOC comment to narrative text to allow a term --- ...stom-view-variations-and-schema-enhancer.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 086adb8f02..c937712434 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -9,11 +9,11 @@ myst: (custom-schema-view-variations-schema-enhancer)= -# Block with a custom schema, variations, and a schema enhancer in a variation. +# Block with a custom schema, variations, and a schema enhancer in a variation This example builds upon the previous example, {doc}`custom-view-and-variations`, where you can create a block with a custom schema, variations, and a schema enhancer in one of the variations. A {term}`variation` is an alternative view of a block. -The variation is shown as an additional option in the schema editor, and lets the developer change how this block is viewed. +The variation is shown as an additional option in the schema editor, and lets the editor change how this block is viewed. A {term}`schema enhancer` is an option of a variation. Using this schema enhancer, you can extend the block schema to have additional fields. @@ -106,10 +106,10 @@ import cx from 'classnames'; import React from 'react'; const View = (props) => { - // `data` holds the values entered in the block edit form - // className holds the CSS class names injected to this block by Volto's `styleClassNameExtenders` - // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper` - // `variation` holds the variation selected in the block editor, and it is an object as defined in the block configuration + // `data` holds the values entered in the block edit form. + // `className` holds the CSS class names injected to this block by Volto's `styleClassNameExtenders`. + // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper`. + // `variation` holds the variation selected in the block editor, and it is an object as defined in the block configuration. const { data, className, style, variation } = props; const BodyTemplate = variation?.template; @@ -129,11 +129,11 @@ const View = (props) => { ); }; -// the `withBlockExtensions` HOC, makes the variation selector available in the block edit form -// and provides the `variation` property in the props. export default withBlockExtensions(View); ``` +The `withBlockExtensions` {term}`HOC` makes the variation selector available in the block edit form and provides the `variation` property in the props. + ## Schema enhancer Next you need to configure the schema enhancer function. @@ -275,6 +275,6 @@ import imagesSVG from '@plone/volto/icons/images.svg'; ## See it in action -Your block is ready to be used in your site. +Your block is ready to use in your site. Restart your Volto site, and you can add it using the block add form. From a8cbfb0ea388f70df99723aba9cec3915f4944f1 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:23:51 +0100 Subject: [PATCH 40/52] Apply suggestions from code review Co-authored-by: David Ichim --- docs/source/blocks/examples/custom-schema-and-view.md | 4 ++-- docs/source/blocks/examples/custom-view-and-variations.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index a4db910ac3..e14f7b00d2 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -99,7 +99,7 @@ import React from 'react'; const View = (props) => { // `data` holds the values entered in the block edit form. // `className` holds the CSS class names injected into this block by Volto's `styleClassNameExtenders`. - // `style` holds the CSS properties injected into this block by Volto's `Block Sytle Wrapper`. + // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper`. const { data, className, style } = props; return (
@@ -162,4 +162,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; Your block is ready to be used in your site. -Restart your Volto site, and you can add it using the block add form. +Restart your Volto site, and now you can add the new block from the block chooser found in the `edit` or `add` new content views. diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index f44da69385..fcfb607a6b 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -13,7 +13,7 @@ myst: We can create a block that uses `variations`. A {term}`variation` is an alternative view of a block. -This variation is shown as an additional option in the schema editor, and lets the editor change how this block is viewed. +This variation is shown as an additional option in the block settings sidebar and lets the editor change how this block is rendered. To do so, define the schema, view component, and variations, then configure the block settings. From 3102b4dfbb299a11a342cfa66125ffcdff897cbf Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:24:59 +0100 Subject: [PATCH 41/52] signal that we do not need an edit component --- docs/source/blocks/examples/custom-schema-and-view.md | 1 + docs/source/blocks/examples/custom-view-and-variations.md | 3 ++- .../examples/custom-view-variations-and-schema-enhancer.md | 3 ++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index e14f7b00d2..3e64758e5f 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -141,6 +141,7 @@ config.blocks.blocksConfig.block02 = { id: 'block02', // this is the block id, it must match the id on the previous line title: 'Block 02', // this is the block title view: View02, // this is the block's view component + // We do not need a specific edit component, Volto will use the default // edit: null; blockSchema: Schema02, // this is the schema that will be used to render the edit form icon: imagesSVG, // this is the image that will be shown in the block selector diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index fcfb607a6b..64f01d09d6 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -209,7 +209,8 @@ Before the last `return config;` statement, write the following configuration. id: 'block05', // this is the block id, it must match the id on the previous line title: 'Block 05', // this is the block title view: View05, // this is the block's view component - //edit: Edit05, + // We do not need a specific edit component, Volto will use the default + // edit: null, blockSchema: Schema05, // this is the schema that will be used to render the edit form icon: imagesSVG, // this is the image that will be shown in the block selector sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index c937712434..8b5f1e2399 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -237,7 +237,8 @@ Before the last `return config;` statement, write the following configuration. id: 'block06', // this is the block id, it must match the id on the previous line title: 'Block 06', // this is the block title view: View06, // this is the block's view component - //edit: Edit05, + // We do not need a specific edit component, Volto will use the default + // edit: null, blockSchema: Schema06, // this is the schema that will be used to render the edit form icon: imagesSVG, // this is the image that will be shown in the block selector sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block From ad7b2c0d547744438b4b9ec8befbc68e1e671c63 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:26:29 +0100 Subject: [PATCH 42/52] show the field added by the schema enhancer in the corresponding variation --- .../examples/custom-view-variations-and-schema-enhancer.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 8b5f1e2399..fd0d998a04 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -198,6 +198,7 @@ const View = (props) => {
  • Title: {data.title}
  • URL: {data.url}
    • +
  • Color: {data.color}
@@ -208,7 +209,7 @@ export default View; ``` As you can see, the variations are pretty much the same. -The only difference is the text that is rendered in the `

` tag. +The differences are the text that is rendered in the `

` tag and that we are showing the new field added by the schema enhancer. But it can be anything. ## Block configuration From 59328e7b0567bcf42479c96046250593f7a2125d Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:28:03 +0100 Subject: [PATCH 43/52] use the i18n pattern in the schema enhancer --- .../custom-view-variations-and-schema-enhancer.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index fd0d998a04..9bfcd8dd6b 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -87,6 +87,10 @@ const messages = defineMessages({ id: 'title', defaultMessage: 'Title', }, + color: { + id: 'color', + defaultMessage: 'Color', + } }); export default messages; @@ -142,12 +146,15 @@ In this example, you will add a new field named `color` when using `schemaEnhanc Create a file {file}`enhancers.js` in the {file}`BlockSchema06` folder with the following content: ```js + +import messages from './messages'; + const schemaEnhancerVariation02 = ({ formData, schema, intl }) => { // schema holds the original schema (see the Schema.js file) // so you need to define the new property under `schema.properties` // and push its name to the relevant fieldset, in this case the first one (note the `fieldsets[0]`) schema.properties.color = { - title: 'Color', + title: intl.formatMessage(messages.color), }; schema.fieldsets[0].fields.push('color'); return schema; From 83405f8b18396a7200c4fdac7052b250faf56648 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:29:19 +0100 Subject: [PATCH 44/52] signal that the folder will be used to save the variations and the schema enhancer too --- docs/source/blocks/examples/custom-view-and-variations.md | 2 +- .../examples/custom-view-variations-and-schema-enhancer.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index 64f01d09d6..23675c7465 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -19,7 +19,7 @@ To do so, define the schema, view component, and variations, then configure the ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock05` inside the {file}`components` folder to save all the files required to create a block. +In your Volto add-on, create a subfolder {file}`ExampleBlock05` inside the {file}`components` folder to save all the files required to create a block and its variations. ## Schema diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 9bfcd8dd6b..5a6b75dac7 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -22,7 +22,7 @@ To do so, define the schema, view component, variations, and schema enhancer, th ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock06` inside the {file}`components` folder to save all the files required to create a block. +In your Volto add-on, create a subfolder {file}`ExampleBlock06` inside the {file}`components` folder to save all the files required to create a block, its variations and the schema enhancer. ## Schema From 524436523844ef520c56002e41c62a5bb588fe9a Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:31:16 +0100 Subject: [PATCH 45/52] split comments to make them visible easier --- docs/source/blocks/examples/custom-schema-and-view.md | 8 +++++--- .../blocks/examples/custom-view-and-variations.md | 11 +++++++---- .../custom-view-variations-and-schema-enhancer.md | 11 +++++++---- 3 files changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 3e64758e5f..efe616ae3e 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -97,9 +97,11 @@ import cx from 'classnames'; import React from 'react'; const View = (props) => { - // `data` holds the values entered in the block edit form. - // `className` holds the CSS class names injected into this block by Volto's `styleClassNameExtenders`. - // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper`. + // - `data` holds the values entered in the block edit form. + // - `className` holds the CSS class names injected into this block + // by Volto's `styleClassNameExtenders`. + // - `style` holds the CSS properties injected into this block + // by Volto's `Block Style Wrapper`. const { data, className, style } = props; return (
diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index 23675c7465..6a5059d348 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -101,10 +101,13 @@ import cx from 'classnames'; import React from 'react'; const View = (props) => { - // `data` holds the values entered in the block edit form. - // `className` holds the CSS class names injected into this block by Volto's `styleClassNameExtenders`. - // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper`. - // `variation` holds the variation selected in the block editor, and it is an object as defined in the block configuration. + // - `data` holds the values entered in the block edit form. + // - `className` holds the CSS class names injected into this block + // by Volto's `styleClassNameExtenders`. + // - `style` holds the CSS properties injected into this block + // by Volto's `Block Style Wrapper`. + // - `variation` holds the variation selected in the block editor, + // and it is an object as defined in the block configuration. const { data, className, style, variation } = props; const BodyTemplate = variation?.template; diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 5a6b75dac7..add31d6fa3 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -110,10 +110,13 @@ import cx from 'classnames'; import React from 'react'; const View = (props) => { - // `data` holds the values entered in the block edit form. - // `className` holds the CSS class names injected to this block by Volto's `styleClassNameExtenders`. - // `style` holds the CSS properties injected into this block by Volto's `Block Style Wrapper`. - // `variation` holds the variation selected in the block editor, and it is an object as defined in the block configuration. + // - `data` holds the values entered in the block edit form. + // - `className` holds the CSS class names injected into this block + // by Volto's `styleClassNameExtenders`. + // - `style` holds the CSS properties injected into this block + // by Volto's `Block Style Wrapper`. + // - `variation` holds the variation selected in the block editor, + // and it is an object as defined in the block configuration. const { data, className, style, variation } = props; const BodyTemplate = variation?.template; From 8dbf8f888dd28508293eb8ced5f00fc44bc82363 Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:33:44 +0100 Subject: [PATCH 46/52] rewrite the block configuration settings docs --- .../blocks/examples/custom-schema-and-view.md | 17 +---------------- .../examples/custom-view-and-variations.md | 17 +---------------- ...ustom-view-variations-and-schema-enhancer.md | 17 +---------------- 3 files changed, 3 insertions(+), 48 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index efe616ae3e..28264a99b9 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -121,22 +121,7 @@ export default View; With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and insert the following contents. - -```js -const applyConfig = (config) => { - config.settings.isMultilingual = false; - config.settings.supportedLanguages = ['en']; - config.settings.defaultLanguage = 'en'; - - - return config; -} - -export default applyConfig; -``` - -Before the last `return config;` statement, write the following configuration. +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js config.blocks.blocksConfig.block02 = { diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index 6a5059d348..c4315a9118 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -190,22 +190,7 @@ But it can be anything. With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and add the following contents. - -```js -const applyConfig = (config) => { - config.settings.isMultilingual = false; - config.settings.supportedLanguages = ['en']; - config.settings.defaultLanguage = 'en'; - - - return config; -} - -export default applyConfig; -``` - -Before the last `return config;` statement, write the following configuration. +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js config.blocks.blocksConfig.block05 = { diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index add31d6fa3..1d22a5c59e 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -226,22 +226,7 @@ But it can be anything. With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and add the following contents. - -```js -const applyConfig = (config) => { - config.settings.isMultilingual = false; - config.settings.supportedLanguages = ['en']; - config.settings.defaultLanguage = 'en'; - - - return config; -} - -export default applyConfig; -``` - -Before the last `return config;` statement, write the following configuration. +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js config.blocks.blocksConfig.block06 = { From 43d0fa6991c1ebcedf071ae2069e25b57b47f9bb Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:46:36 +0100 Subject: [PATCH 47/52] add an example with a custom edit form --- .../examples/custom-schema-view-and-edit.md | 210 ++++++++++++++++++ docs/source/blocks/examples/index.md | 1 + 2 files changed, 211 insertions(+) create mode 100644 docs/source/blocks/examples/custom-schema-view-and-edit.md diff --git a/docs/source/blocks/examples/custom-schema-view-and-edit.md b/docs/source/blocks/examples/custom-schema-view-and-edit.md new file mode 100644 index 0000000000..5b9b734137 --- /dev/null +++ b/docs/source/blocks/examples/custom-schema-view-and-edit.md @@ -0,0 +1,210 @@ +--- +myst: + html_meta: + "description": "Volto block with custom schema, view and edit components" + "property=og:description": "Volto block with custom schema, view and edit components" + "property=og:title": "Volto block with custom schema, view and edit components" + "keywords": "Volto, React, blocks, grid, container, Plone" +--- + +(custom-schema-edit-and-view)= + +# Block with a custom schema and edit components + +You can create a block with several settings defined using a schema, and write a custom edit form instead of using the one provided by Volto. + +To do so, define the schema, the view component, the edit component, and configure the block settings. + +## Preparations + +In your Volto add-on, create a subfolder {file}`ExampleBlock03` inside the {file}`components` folder to save all the files required to create a block. + +## Schema + +Create a {file}`Schema.js` file inside the {file}`ExampleBlock03` folder, with the following contents. + +```js +import messages from './messages'; + +const Schema = ({ intl }) => { + return { + title: intl.formatMessage(messages.block03), + block: 'block03', + fieldsets: [ + { + id: 'default', + title: intl.formatMessage(messages.default), + fields: ['url', 'title'], + }, + ], + + properties: { + url: { + title: intl.formatMessage(messages.URL), + widget: 'url', + }, + title: { + title: intl.formatMessage(messages.title), + }, + }, + required: [], + }; +}; + +export default Schema; +``` + +## Messages + +As you may have noted, you prepared the block for internationalization. +{term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. +To add translatable messages, create a file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents. + +```js +import { defineMessages } from 'react-intl'; + +const messages = defineMessages({ + block03: { + id: 'block03', + defaultMessage: 'Block 03', + }, + default: { + id: 'default', + defaultMessage: 'Default', + }, + URL: { + id: 'URL', + defaultMessage: 'URL', + }, + title: { + id: 'title', + defaultMessage: 'Title', + }, +}); + +export default messages; +``` + +## View component + +The view component will have all the required logic to show the information saved on the block. +It will be a small HTML fragment. + +Create a file {file}`View.jsx` in the {file}`ExampleBlock03` folder with the following contents. + +```jsx +import cx from 'classnames'; +import React from 'react'; + +const View = (props) => { + // - `data` holds the values entered in the block edit form. + // - `className` holds the CSS class names injected into this block + // by Volto's `styleClassNameExtenders`. + // - `style` holds the CSS properties injected into this block + // by Volto's `Block Style Wrapper`. + const { data, className, style } = props; + return ( +
+ I am the Block view component! +
    +
  • Title: {data.title}
    • +
  • URL: {data.url}
    • +
+
+ ); +}; + +export default View; +``` + +## Edit component + +The Edit component needs to render a form where the editor can change the block settings. + +This Edit component is a minimal component that renders the block and the same edit form as the one rendered automatically. + +Create a file {file}`Edit.jsx` in the {file}`ExampleBlock03` folder with the following contents: + +```jsx + +// We manually import the schema +import schema from './Schema'; +import BlockDataForm from '@plone/volto/components/manage/Form/BlockDataForm'; +import { SidebarPortal } from '@plone/volto/components'; +// The Edit component needs to render also the view of the block, not only the form +// So we import the View component that we have just written to render its contents +import View from './View'; + + +const Edit = (props) => { + const { onChangeBlock, block, data, selected, className, style } = props; + + // The schema is a function, so we call it to have the definition + const blockSchema = schema(props); + + return ( + <> + + + + { + onChangeBlock(block, { + ...data, + [id]: value, + }); + }} + onChangeBlock={onChangeBlock} + formData={data} + block={block} + /> + + + ); +}; + +export default Edit; +``` + +## Block configuration + +With all the block components ready, you need to register the block into Volto. + +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: + +```js +config.blocks.blocksConfig.block03 = { + id: 'block03', // this is the block id, it must match the id on the previous line + title: 'Block 03', // this is the block title + view: View02, // this is the block's view component + edit: Edit03, // this is the block's edit component + // We do not need to define the schema here, + // because we are using a custom edit component + // blockSchema: Schema03, + + // this is the image that will be shown in the block selector + icon: imagesSVG, + // this is set to 1 to have the `Block` tab selected in the sidebar editor + // when editing this block + sidebarTab: 1, + }; +``` + +At the top of the file, import the relevant components as follows. + +```js +import View03 from './components/ExampleBlock03/View'; +import Edit03 from './components/ExampleBlock03/Edit'; +import Schema03 from './components/ExampleBlock03/Schema'; + +// This is the icon we use for the example, use a meaningful one or provide your own image. +import imagesSVG from '@plone/volto/icons/images.svg'; +``` + +## See it in action + +Your block is ready to be used in your site. + +Restart your Volto site, and now you can add the new block from the block chooser found in the `edit` or `add` new content views. diff --git a/docs/source/blocks/examples/index.md b/docs/source/blocks/examples/index.md index fca4ab4e49..f64f6c1ea8 100644 --- a/docs/source/blocks/examples/index.md +++ b/docs/source/blocks/examples/index.md @@ -17,6 +17,7 @@ These blocks have been tested using Volto 18.4.0. :maxdepth: 1 custom-schema-and-view +custom-schema-view-and-edit custom-view-and-variations custom-view-variations-and-schema-enhancer ``` From 720b3e287f1845e3a5f9fb1d562d1a77b7a7ec0a Mon Sep 17 00:00:00 2001 From: Mikel Larreategi Date: Sun, 5 Jan 2025 18:47:28 +0100 Subject: [PATCH 48/52] rename the blocks --- .../blocks/examples/custom-schema-and-view.md | 34 ++++++------ .../examples/custom-schema-view-and-edit.md | 34 ++++++------ .../examples/custom-view-and-variations.md | 48 ++++++++--------- ...tom-view-variations-and-schema-enhancer.md | 54 +++++++++---------- 4 files changed, 85 insertions(+), 85 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 28264a99b9..f985ccd142 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -17,19 +17,19 @@ To do so, define the schema, the view component, and configure the block setting ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock02` inside the {file}`components` folder to save all the files required to create a block. +In your Volto add-on, create a subfolder {file}`ExampleBlock01` inside the {file}`components` folder to save all the files required to create a block. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock02` folder, with the following contents. +Create a {file}`Schema.js` file inside the {file}`ExampleBlock01` folder, with the following contents. ```js import messages from './messages'; const Schema = ({ intl }) => { return { - title: intl.formatMessage(messages.block02), - block: 'block02', + title: intl.formatMessage(messages.block01), + block: 'block01', fieldsets: [ { id: 'default', @@ -58,15 +58,15 @@ export default Schema; As you may have noted, you prepared the block for internationalization. {term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. -To add translatable messages, create a file {file}`messages.js` in the same {file}`ExampleBlock02` folder with the following contents. +To add translatable messages, create a file {file}`messages.js` in the same {file}`ExampleBlock01` folder with the following contents. ```js import { defineMessages } from 'react-intl'; const messages = defineMessages({ - block02: { - id: 'block02', - defaultMessage: 'Block 02', + block01: { + id: 'block01', + defaultMessage: 'Block 01', }, default: { id: 'default', @@ -90,7 +90,7 @@ export default messages; The view component will have all the required logic to show the information saved on the block. It will be a small HTML fragment. -Create a file {file}`View.jsx` in the {file}`ExampleBlock02` folder with the following contents. +Create a file {file}`View.jsx` in the {file}`ExampleBlock01` folder with the following contents. ```jsx import cx from 'classnames'; @@ -104,7 +104,7 @@ const View = (props) => { // by Volto's `Block Style Wrapper`. const { data, className, style } = props; return ( -
+
I am the Block view component!
  • Title: {data.title}
    • @@ -124,13 +124,13 @@ With all the block components ready, you need to register the block into Volto. To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js -config.blocks.blocksConfig.block02 = { - id: 'block02', // this is the block id, it must match the id on the previous line - title: 'Block 02', // this is the block title - view: View02, // this is the block's view component +config.blocks.blocksConfig.block01 = { + id: 'block01', // this is the block id, it must match the id on the previous line + title: 'Block 01', // this is the block title + view: View01, // this is the block's view component // We do not need a specific edit component, Volto will use the default // edit: null; - blockSchema: Schema02, // this is the schema that will be used to render the edit form + blockSchema: Schema01, // this is the schema that will be used to render the edit form icon: imagesSVG, // this is the image that will be shown in the block selector sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block }; @@ -139,8 +139,8 @@ config.blocks.blocksConfig.block02 = { At the top of the file, import the relevant components as follows. ```js -import View02 from './components/ExampleBlock02/View'; -import Schema02 from './components/ExampleBlock02/Schema'; +import View01 from './components/ExampleBlock01/View'; +import Schema01 from './components/ExampleBlock01/Schema'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; diff --git a/docs/source/blocks/examples/custom-schema-view-and-edit.md b/docs/source/blocks/examples/custom-schema-view-and-edit.md index 5b9b734137..390ec052ba 100644 --- a/docs/source/blocks/examples/custom-schema-view-and-edit.md +++ b/docs/source/blocks/examples/custom-schema-view-and-edit.md @@ -17,19 +17,19 @@ To do so, define the schema, the view component, the edit component, and configu ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock03` inside the {file}`components` folder to save all the files required to create a block. +In your Volto add-on, create a subfolder {file}`ExampleBlock02` inside the {file}`components` folder to save all the files required to create a block. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock03` folder, with the following contents. +Create a {file}`Schema.js` file inside the {file}`ExampleBlock02` folder, with the following contents. ```js import messages from './messages'; const Schema = ({ intl }) => { return { - title: intl.formatMessage(messages.block03), - block: 'block03', + title: intl.formatMessage(messages.block02), + block: 'block02', fieldsets: [ { id: 'default', @@ -64,9 +64,9 @@ To add translatable messages, create a file {file}`messages.js` in the same {fil import { defineMessages } from 'react-intl'; const messages = defineMessages({ - block03: { - id: 'block03', - defaultMessage: 'Block 03', + block02: { + id: 'block02', + defaultMessage: 'Block 02', }, default: { id: 'default', @@ -90,7 +90,7 @@ export default messages; The view component will have all the required logic to show the information saved on the block. It will be a small HTML fragment. -Create a file {file}`View.jsx` in the {file}`ExampleBlock03` folder with the following contents. +Create a file {file}`View.jsx` in the {file}`ExampleBlock02` folder with the following contents. ```jsx import cx from 'classnames'; @@ -123,7 +123,7 @@ The Edit component needs to render a form where the editor can change the block This Edit component is a minimal component that renders the block and the same edit form as the one rendered automatically. -Create a file {file}`Edit.jsx` in the {file}`ExampleBlock03` folder with the following contents: +Create a file {file}`Edit.jsx` in the {file}`ExampleBlock02` folder with the following contents: ```jsx @@ -175,14 +175,14 @@ With all the block components ready, you need to register the block into Volto. To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js -config.blocks.blocksConfig.block03 = { - id: 'block03', // this is the block id, it must match the id on the previous line - title: 'Block 03', // this is the block title +config.blocks.blocksConfig.block02 = { + id: 'block02', // this is the block id, it must match the id on the previous line + title: 'Block 02', // this is the block title view: View02, // this is the block's view component - edit: Edit03, // this is the block's edit component + edit: Edit02, // this is the block's edit component // We do not need to define the schema here, // because we are using a custom edit component - // blockSchema: Schema03, + // blockSchema: Schema02, // this is the image that will be shown in the block selector icon: imagesSVG, @@ -195,9 +195,9 @@ config.blocks.blocksConfig.block03 = { At the top of the file, import the relevant components as follows. ```js -import View03 from './components/ExampleBlock03/View'; -import Edit03 from './components/ExampleBlock03/Edit'; -import Schema03 from './components/ExampleBlock03/Schema'; +import View02 from './components/ExampleBlock02/View'; +import Edit02 from './components/ExampleBlock02/Edit'; +import Schema02 from './components/ExampleBlock02/Schema'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index c4315a9118..4b87474cbe 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -19,19 +19,19 @@ To do so, define the schema, view component, and variations, then configure the ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock05` inside the {file}`components` folder to save all the files required to create a block and its variations. +In your Volto add-on, create a subfolder {file}`ExampleBlock03` inside the {file}`components` folder to save all the files required to create a block and its variations. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock05` folder, with the following contents. +Create a {file}`Schema.js` file inside the {file}`ExampleBlock03` folder, with the following contents. ```js import messages from './messages'; const Schema = ({ intl }) => { return { - title: intl.formatMessage(messages.block05), - block: 'block05', + title: intl.formatMessage(messages.block03), + block: 'block03', fieldsets: [ { id: 'default', @@ -61,15 +61,15 @@ export default Schema; As you may have noted, you prepared the block for internationalization. {term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. -To do so, create a file {file}`messages.js` in the same {file}`ExampleBlock05` folder with the following contents. +To do so, create a file {file}`messages.js` in the same {file}`ExampleBlock03` folder with the following contents. ```js import { defineMessages } from 'react-intl'; const messages = defineMessages({ - block05: { - id: 'block05', - defaultMessage: 'Block 05', + block03: { + id: 'block03', + defaultMessage: 'Block 03', }, default: { id: 'default', @@ -93,7 +93,7 @@ export default messages; For variations, the view component needs to use the variation template to render the contents of the block. You can do so using the `variation` from the `props` of the block. -Create a file {file}`View.jsx` in the {file}`ExampleBlock05` folder with the following contents. +Create a file {file}`View.jsx` in the {file}`ExampleBlock03` folder with the following contents. ```jsx import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; @@ -116,8 +116,8 @@ const View = (props) => {
    { export default View; ``` -Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock05` folder with the following contents. +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock03` folder with the following contents. ```jsx import React from 'react'; @@ -193,13 +193,13 @@ With all the block components ready, you need to register the block into Volto. To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js - config.blocks.blocksConfig.block05 = { - id: 'block05', // this is the block id, it must match the id on the previous line - title: 'Block 05', // this is the block title - view: View05, // this is the block's view component + config.blocks.blocksConfig.block03 = { + id: 'block03', // this is the block id, it must match the id on the previous line + title: 'Block 03', // this is the block title + view: View03, // this is the block's view component // We do not need a specific edit component, Volto will use the default // edit: null, - blockSchema: Schema05, // this is the schema that will be used to render the edit form + blockSchema: Schema03, // this is the schema that will be used to render the edit form icon: imagesSVG, // this is the image that will be shown in the block selector sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block // these are the variations available for this block @@ -208,13 +208,13 @@ To do so, open your add-on's {file}`index.js` file, and insert the following con id: 'variation01', // this is the id of the variation title: 'Variation 01', // this is the title of the variation isDefault: true, // this signals if this is the default variation for this block - template: VariationView0501, // this is the component that will render the variation + template: VariationView0301, // this is the component that will render the variation }, { id: 'variation02', title: 'Variation 02', isDefault: false, - template: VariationView0502, + template: VariationView0302, }, ], }; @@ -224,10 +224,10 @@ To do so, open your add-on's {file}`index.js` file, and insert the following con At the top of the file, import the relevant components as follows. ```js -import View05 from './components/ExampleBlock05/View'; -import Schema05 from './components/ExampleBlock05/Schema'; -import VariationView0501 from './components/ExampleBlock05/VariationView01'; -import VariationView0502 from './components/ExampleBlock05/VariationView02'; +import View03 from './components/ExampleBlock03/View'; +import Schema03 from './components/ExampleBlock03/Schema'; +import VariationView0301 from './components/ExampleBlock03/VariationView01'; +import VariationView0302 from './components/ExampleBlock03/VariationView02'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 1d22a5c59e..18f68dc26d 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -22,20 +22,20 @@ To do so, define the schema, view component, variations, and schema enhancer, th ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock06` inside the {file}`components` folder to save all the files required to create a block, its variations and the schema enhancer. +In your Volto add-on, create a subfolder {file}`ExampleBlock04` inside the {file}`components` folder to save all the files required to create a block, its variations and the schema enhancer. ## Schema -Create a {file}`Schema.js` file inside the {file}`ExampleBlock06` folder, with the following contents. +Create a {file}`Schema.js` file inside the {file}`ExampleBlock04` folder, with the following contents. ```js import messages from './messages'; const Schema = ({ intl }) => { return { - title: intl.formatMessage(messages.block06), - block: 'block06', + title: intl.formatMessage(messages.block04), + block: 'block04', fieldsets: [ { id: 'default', @@ -65,15 +65,15 @@ export default Schema; As you may have noted, you prepared the block for internationalization. {term}`Internationalization` (i18n) is the process of creating user interfaces which are suitable for different languages and cultural contexts. -Create a file {file}`messages.js` in the same {file}`ExampleBlock06` folder with the following contents. +Create a file {file}`messages.js` in the same {file}`ExampleBlock04` folder with the following contents. ```js import { defineMessages } from 'react-intl'; const messages = defineMessages({ - block06: { - id: 'block06', - defaultMessage: 'Block 06', + block04: { + id: 'block04', + defaultMessage: 'Block 04', }, default: { id: 'default', @@ -102,7 +102,7 @@ For variations, the view component needs to use the variation template to render You can do so using the `variation` from the `props` of the block. -Create a file {file}`View.jsx` in the {file}`ExampleBlock06` folder with the following contents. +Create a file {file}`View.jsx` in the {file}`ExampleBlock04` folder with the following contents. ```jsx import withBlockExtensions from '@plone/volto/helpers/Extensions/withBlockExtensions'; @@ -125,8 +125,8 @@ const View = (props) => {
    { export default View; ``` -Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock06` folder with the following contents. +Create a file {file}`VariationView02.jsx` in the {file}`ExampleBlock04` folder with the following contents. ```jsx import React from 'react'; @@ -229,13 +229,13 @@ With all the block components ready, you need to register the block into Volto. To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: ```js - config.blocks.blocksConfig.block06 = { - id: 'block06', // this is the block id, it must match the id on the previous line - title: 'Block 06', // this is the block title - view: View06, // this is the block's view component + config.blocks.blocksConfig.block04 = { + id: 'block04', // this is the block id, it must match the id on the previous line + title: 'Block 04', // this is the block title + view: View04, // this is the block's view component // We do not need a specific edit component, Volto will use the default // edit: null, - blockSchema: Schema06, // this is the schema that will be used to render the edit form + blockSchema: Schema04, // this is the schema that will be used to render the edit form icon: imagesSVG, // this is the image that will be shown in the block selector sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block // these are the variations available for this block @@ -244,14 +244,14 @@ To do so, open your add-on's {file}`index.js` file, and insert the following con id: 'variation01', // this is the id of the variation title: 'Variation 01', // this is the title of the variation isDefault: true, // this signals if this is the default variation for this block - template: VariationView0601, // this is the component that will render the variation + template: VariationView0401, // this is the component that will render the variation }, { id: 'variation02', title: 'Variation 02', isDefault: false, - template: VariationView0602, - schemaEnhancer: schemaEnhancerBlock06Variation02, // this is the schema enhancer definition + template: VariationView0402, + schemaEnhancer: schemaEnhancerBlock04Variation02, // this is the schema enhancer definition }, ], }; @@ -260,11 +260,11 @@ To do so, open your add-on's {file}`index.js` file, and insert the following con At the top of the file, import the relevant components as follows. ```js -import View06 from './components/ExampleBlock06/View'; -import Schema06 from './components/ExampleBlock06/Schema'; -import VariationView0601 from './components/ExampleBlock06/VariationView01'; -import VariationView0602 from './components/ExampleBlock06/VariationView02'; -import schemaEnhancerBlock06Variation02 from './components/ExampleBlock06/enhancers'; +import View04 from './components/ExampleBlock04/View'; +import Schema04 from './components/ExampleBlock04/Schema'; +import VariationView0401 from './components/ExampleBlock04/VariationView01'; +import VariationView0402 from './components/ExampleBlock04/VariationView02'; +import schemaEnhancerBlock04Variation02 from './components/ExampleBlock04/enhancers'; // This is the icon we use for the example, use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; From c06b755c969c0814d2baeb92d1eff67a10190ac2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 5 Jan 2025 15:08:34 -0800 Subject: [PATCH 49/52] Add add and edit content SVG icons --- docs/source/_static/add-document.svg | 6 ++++++ docs/source/_static/pen.svg | 3 +++ 2 files changed, 9 insertions(+) create mode 100644 docs/source/_static/add-document.svg create mode 100644 docs/source/_static/pen.svg diff --git a/docs/source/_static/add-document.svg b/docs/source/_static/add-document.svg new file mode 100644 index 0000000000..29594b298e --- /dev/null +++ b/docs/source/_static/add-document.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/source/_static/pen.svg b/docs/source/_static/pen.svg new file mode 100644 index 0000000000..3c535f378e --- /dev/null +++ b/docs/source/_static/pen.svg @@ -0,0 +1,3 @@ + + + From 591505f87fbb8d04682d5008b7eef2ec59b446af Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 5 Jan 2025 15:10:29 -0800 Subject: [PATCH 50/52] Apply suggestions from code review --- .../examples/custom-schema-view-and-edit.md | 40 ++++++++++--------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-view-and-edit.md b/docs/source/blocks/examples/custom-schema-view-and-edit.md index 390ec052ba..a5fd7d57e1 100644 --- a/docs/source/blocks/examples/custom-schema-view-and-edit.md +++ b/docs/source/blocks/examples/custom-schema-view-and-edit.md @@ -1,10 +1,10 @@ --- myst: html_meta: - "description": "Volto block with custom schema, view and edit components" - "property=og:description": "Volto block with custom schema, view and edit components" - "property=og:title": "Volto block with custom schema, view and edit components" - "keywords": "Volto, React, blocks, grid, container, Plone" + "description": "Volto block with custom schema and edit components" + "property=og:description": "Volto block with custom schema and edit components" + "property=og:title": "Volto block with custom schema and edit components" + "keywords": "Volto, React, blocks, custom, schema, edit, component, Plone" --- (custom-schema-edit-and-view)= @@ -119,27 +119,28 @@ export default View; ## Edit component -The Edit component needs to render a form where the editor can change the block settings. +The edit component renders a form where the editor can change the block settings. +This edit component is a minimal component that renders the block and the same edit form as the one rendered automatically. -This Edit component is a minimal component that renders the block and the same edit form as the one rendered automatically. - -Create a file {file}`Edit.jsx` in the {file}`ExampleBlock02` folder with the following contents: +Create a file {file}`Edit.jsx` in the {file}`ExampleBlock02` folder with the following contents. ```jsx -// We manually import the schema +// manually import the schema import schema from './Schema'; import BlockDataForm from '@plone/volto/components/manage/Form/BlockDataForm'; import { SidebarPortal } from '@plone/volto/components'; -// The Edit component needs to render also the view of the block, not only the form -// So we import the View component that we have just written to render its contents +// The edit component also renders the view of the block, +// not only the form. +// So you must import the view component that you just wrote +// to render its contents. import View from './View'; const Edit = (props) => { const { onChangeBlock, block, data, selected, className, style } = props; - // The schema is a function, so we call it to have the definition + // The schema is a function. Call it to get its definition. const blockSchema = schema(props); return ( @@ -172,7 +173,7 @@ export default Edit; With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config;` statement. ```js config.blocks.blocksConfig.block02 = { @@ -180,13 +181,13 @@ config.blocks.blocksConfig.block02 = { title: 'Block 02', // this is the block title view: View02, // this is the block's view component edit: Edit02, // this is the block's edit component - // We do not need to define the schema here, - // because we are using a custom edit component + // You do not need to define the schema here, + // because you are using a custom edit component // blockSchema: Schema02, // this is the image that will be shown in the block selector icon: imagesSVG, - // this is set to 1 to have the `Block` tab selected in the sidebar editor + // this is set to 1, which selects the `Block` tab in the sidebar editor // when editing this block sidebarTab: 1, }; @@ -199,12 +200,13 @@ import View02 from './components/ExampleBlock02/View'; import Edit02 from './components/ExampleBlock02/Edit'; import Schema02 from './components/ExampleBlock02/Schema'; -// This is the icon we use for the example, use a meaningful one or provide your own image. +// This is the icon to use for this example. +// Use a meaningful one or provide your own image. import imagesSVG from '@plone/volto/icons/images.svg'; ``` ## See it in action -Your block is ready to be used in your site. +Your block is ready to use in your site. -Restart your Volto site, and now you can add the new block from the block chooser found in the `edit` or `add` new content views. +Restart your Volto site, and now you can add the new block from the block chooser found in the {guilabel}`Edit` Edit icon or {guilabel}`Add` Add icon content views. From f1abca2da10a6f8411b401ce9d928043e3c6dfb1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 5 Jan 2025 15:20:40 -0800 Subject: [PATCH 51/52] Apply omitted suggestions from code review --- docs/source/blocks/examples/custom-schema-and-view.md | 4 ++-- docs/source/blocks/examples/custom-view-and-variations.md | 4 ++-- .../custom-view-variations-and-schema-enhancer.md | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index f985ccd142..714b230fa1 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -121,7 +121,7 @@ export default View; With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config;` statement. ```js config.blocks.blocksConfig.block01 = { @@ -150,4 +150,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; Your block is ready to be used in your site. -Restart your Volto site, and now you can add the new block from the block chooser found in the `edit` or `add` new content views. +Restart your Volto site, and now you can add the new block from the block chooser found in the {guilabel}`Edit` Edit icon or {guilabel}`Add` Add icon content views. diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index 4b87474cbe..940937eb7f 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -190,7 +190,7 @@ But it can be anything. With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config;` statement. ```js config.blocks.blocksConfig.block03 = { @@ -237,4 +237,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; Your block is ready to be used in your site. -Restart your Volto site, and you can add it using the block add form. +Restart your Volto site, and now you can add the new block from the block chooser found in the {guilabel}`Edit` Edit icon or {guilabel}`Add` Add icon content views. diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 18f68dc26d..1fd09e19d9 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -22,7 +22,7 @@ To do so, define the schema, view component, variations, and schema enhancer, th ## Preparations -In your Volto add-on, create a subfolder {file}`ExampleBlock04` inside the {file}`components` folder to save all the files required to create a block, its variations and the schema enhancer. +In your Volto add-on, create a subfolder {file}`ExampleBlock04` inside the {file}`components` folder to save all the files required to create a block, its variations, and the schema enhancer. ## Schema @@ -219,14 +219,14 @@ export default View; ``` As you can see, the variations are pretty much the same. -The differences are the text that is rendered in the `

    ` tag and that we are showing the new field added by the schema enhancer. +The differences are the text that is rendered in the `

    ` tag, and the new field that you added with the schema enhancer. But it can be anything. ## Block configuration With all the block components ready, you need to register the block into Volto. -To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config` statement: +To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config;` statement. ```js config.blocks.blocksConfig.block04 = { @@ -274,4 +274,4 @@ import imagesSVG from '@plone/volto/icons/images.svg'; Your block is ready to use in your site. -Restart your Volto site, and you can add it using the block add form. +Restart your Volto site, and now you can add the new block from the block chooser found in the {guilabel}`Edit` Edit icon or {guilabel}`Add` Add icon content views. From 058b4b07ded1ee7e27f3212ed8f3879cd6385db3 Mon Sep 17 00:00:00 2001 From: David Ichim Date: Mon, 6 Jan 2025 13:15:18 +0200 Subject: [PATCH 52/52] Break comments into 2 lines to avoid overflow scrollbar when viewing the examples in the browser. --- .../blocks/examples/custom-schema-and-view.md | 27 +++---- .../examples/custom-view-and-variations.md | 59 ++++++++------- ...tom-view-variations-and-schema-enhancer.md | 71 ++++++++++--------- 3 files changed, 79 insertions(+), 78 deletions(-) diff --git a/docs/source/blocks/examples/custom-schema-and-view.md b/docs/source/blocks/examples/custom-schema-and-view.md index 714b230fa1..cf099fc554 100644 --- a/docs/source/blocks/examples/custom-schema-and-view.md +++ b/docs/source/blocks/examples/custom-schema-and-view.md @@ -1,10 +1,10 @@ --- myst: html_meta: - "description": "Volto block with custom schema and view components" - "property=og:description": "Volto block with custom schema and view components" - "property=og:title": "Volto block with custom schema and view components" - "keywords": "Volto, React, blocks, grid, container, Plone" + 'description': 'Volto block with custom schema and view components' + 'property=og:description': 'Volto block with custom schema and view components' + 'property=og:title': 'Volto block with custom schema and view components' + 'keywords': 'Volto, React, blocks, grid, container, Plone' --- (custom-schema-and-view)= @@ -125,15 +125,16 @@ To do so, open your add-on's {file}`index.js` file, and insert the following con ```js config.blocks.blocksConfig.block01 = { - id: 'block01', // this is the block id, it must match the id on the previous line - title: 'Block 01', // this is the block title - view: View01, // this is the block's view component - // We do not need a specific edit component, Volto will use the default - // edit: null; - blockSchema: Schema01, // this is the schema that will be used to render the edit form - icon: imagesSVG, // this is the image that will be shown in the block selector - sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block - }; + id: 'block01', // this is the block id, it must match the id on the previous line + title: 'Block 01', // this is the block title + view: View01, // this is the block's view component + // We do not need a specific edit component, Volto will use the default + // edit: null; + blockSchema: Schema01, // this is the schema that will be used to render the edit form + icon: imagesSVG, // this is the image that will be shown in the block selector + sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar + // editor when editing this block +}; ``` At the top of the file, import the relevant components as follows. diff --git a/docs/source/blocks/examples/custom-view-and-variations.md b/docs/source/blocks/examples/custom-view-and-variations.md index 940937eb7f..5fc95e3e97 100644 --- a/docs/source/blocks/examples/custom-view-and-variations.md +++ b/docs/source/blocks/examples/custom-view-and-variations.md @@ -1,10 +1,10 @@ --- myst: html_meta: - "description": "Volto block with custom schema and view components using variations" - "property=og:description": "Volto block with custom schema and view components using variations" - "property=og:title": "Volto block with custom schema and view components using variations" - "keywords": "Volto, React, blocks, schema, variation, view component, Plone" + 'description': 'Volto block with custom schema and view components using variations' + 'property=og:description': 'Volto block with custom schema and view components using variations' + 'property=og:title': 'Volto block with custom schema and view components using variations' + 'keywords': 'Volto, React, blocks, schema, variation, view component, Plone' --- (custom-schema-view-and-variations)= @@ -193,32 +193,31 @@ With all the block components ready, you need to register the block into Volto. To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config;` statement. ```js - config.blocks.blocksConfig.block03 = { - id: 'block03', // this is the block id, it must match the id on the previous line - title: 'Block 03', // this is the block title - view: View03, // this is the block's view component - // We do not need a specific edit component, Volto will use the default - // edit: null, - blockSchema: Schema03, // this is the schema that will be used to render the edit form - icon: imagesSVG, // this is the image that will be shown in the block selector - sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block - // these are the variations available for this block - variations: [ - { - id: 'variation01', // this is the id of the variation - title: 'Variation 01', // this is the title of the variation - isDefault: true, // this signals if this is the default variation for this block - template: VariationView0301, // this is the component that will render the variation - }, - { - id: 'variation02', - title: 'Variation 02', - isDefault: false, - template: VariationView0302, - }, - ], - }; - +config.blocks.blocksConfig.block03 = { + id: 'block03', // this is the block id, it must match the id on the previous line + title: 'Block 03', // this is the block title + view: View03, // this is the block's view component + // We do not need a specific edit component, Volto will use the default + // edit: null, + blockSchema: Schema03, // this is the schema that will be used to render the edit form + icon: imagesSVG, // this is the image that will be shown in the block selector + sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar + // editor when editing this block these are the variations available for this block + variations: [ + { + id: 'variation01', // this is the id of the variation + title: 'Variation 01', // this is the title of the variation + isDefault: true, // this signals if this is the default variation for this block + template: VariationView0301, // this is the component that will render the variation + }, + { + id: 'variation02', + title: 'Variation 02', + isDefault: false, + template: VariationView0302, + }, + ], +}; ``` At the top of the file, import the relevant components as follows. diff --git a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md index 1fd09e19d9..90f6ffebe0 100644 --- a/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md +++ b/docs/source/blocks/examples/custom-view-variations-and-schema-enhancer.md @@ -1,10 +1,10 @@ --- myst: html_meta: - "description": "Volto block with custom schema and view components using variations and a schema enhancer in one of the variations" - "property=og:description": "Volto block with custom schema and view components using variations and a schema enhancer in one of the variations" - "property=og:title": "Volto block with custom schema, variations, and schema enhancer" - "keywords": "Volto, React, blocks, variation, custom, schema, enhancer, Plone" + 'description': 'Volto block with custom schema and view components using variations and a schema enhancer in one of the variations' + 'property=og:description': 'Volto block with custom schema and view components using variations and a schema enhancer in one of the variations' + 'property=og:title': 'Volto block with custom schema, variations, and schema enhancer' + 'keywords': 'Volto, React, blocks, variation, custom, schema, enhancer, Plone' --- (custom-schema-view-variations-schema-enhancer)= @@ -24,7 +24,6 @@ To do so, define the schema, view component, variations, and schema enhancer, th In your Volto add-on, create a subfolder {file}`ExampleBlock04` inside the {file}`components` folder to save all the files required to create a block, its variations, and the schema enhancer. - ## Schema Create a {file}`Schema.js` file inside the {file}`ExampleBlock04` folder, with the following contents. @@ -90,7 +89,7 @@ const messages = defineMessages({ color: { id: 'color', defaultMessage: 'Color', - } + }, }); export default messages; @@ -149,13 +148,13 @@ In this example, you will add a new field named `color` when using `schemaEnhanc Create a file {file}`enhancers.js` in the {file}`BlockSchema04` folder with the following content: ```js - import messages from './messages'; const schemaEnhancerVariation02 = ({ formData, schema, intl }) => { // schema holds the original schema (see the Schema.js file) // so you need to define the new property under `schema.properties` - // and push its name to the relevant fieldset, in this case the first one (note the `fieldsets[0]`) + // and push its name to the relevant fieldset, in this case the first one + // (note the `fieldsets[0]`) schema.properties.color = { title: intl.formatMessage(messages.color), }; @@ -164,7 +163,6 @@ const schemaEnhancerVariation02 = ({ formData, schema, intl }) => { }; export default schemaEnhancerVariation02; - ``` ## Variations @@ -229,32 +227,35 @@ With all the block components ready, you need to register the block into Volto. To do so, open your add-on's {file}`index.js` file, and insert the following contents before the last `return config;` statement. ```js - config.blocks.blocksConfig.block04 = { - id: 'block04', // this is the block id, it must match the id on the previous line - title: 'Block 04', // this is the block title - view: View04, // this is the block's view component - // We do not need a specific edit component, Volto will use the default - // edit: null, - blockSchema: Schema04, // this is the schema that will be used to render the edit form - icon: imagesSVG, // this is the image that will be shown in the block selector - sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar editor when editing this block - // these are the variations available for this block - variations: [ - { - id: 'variation01', // this is the id of the variation - title: 'Variation 01', // this is the title of the variation - isDefault: true, // this signals if this is the default variation for this block - template: VariationView0401, // this is the component that will render the variation - }, - { - id: 'variation02', - title: 'Variation 02', - isDefault: false, - template: VariationView0402, - schemaEnhancer: schemaEnhancerBlock04Variation02, // this is the schema enhancer definition - }, - ], - }; +config.blocks.blocksConfig.block04 = { + id: 'block04', // this is the block id, it must match the id on the previous line + title: 'Block 04', // this is the block title + view: View04, // this is the block's view component + // We do not need a specific edit component, Volto will use the default + // edit: null, + blockSchema: Schema04, // this is the schema that will be used to render the edit form + icon: imagesSVG, // this is the image that will be shown in the block selector + sidebarTab: 1, // this is set to 1 to have the `Block` tab selected in the sidebar + // editor when editing this block these are the variations available for this block + // these are the variations available for this block + variations: [ + { + id: 'variation01', // this is the id of the variation + title: 'Variation 01', // this is the title of the variation + isDefault: true, // this signals if this is the default variation for this block + template: VariationView0401, // this is the component that will render + // the variation + }, + { + id: 'variation02', + title: 'Variation 02', + isDefault: false, + template: VariationView0402, + schemaEnhancer: schemaEnhancerBlock04Variation02, // this is the schema enhancer + // definition + }, + ], +}; ``` At the top of the file, import the relevant components as follows.