Block examples documentation

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.

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`.
@@ -28,22 +28,36 @@ You need to instantiate it this way:
 ```jsx
 import { SidebarPortal } from '@plone/volto/components';
 
-[...]
+const Edit = (props) => {
+  const { selected } = props;
+  return (
+
+    [...]
 
-<SidebarPortal selected={this.props.selected}>
-  // ...
-</SidebarPortal>
+    <SidebarPortal selected={selected}>
+      // ...
+    </SidebarPortal>
+  )
+
+}
 ```
 
 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';
 
-<SidebarPopup open={this.props.sidebarOpen}>
-  ...
-</SidebarPopup>
+const Edit = (props) => {
+  const { sidebarOpen } = props;
+
+  return (
+    [...]
+
+    <SidebarPopup open={sidebarOpen}>
+      ...
+    </SidebarPopup>
+  )
+}
 ```
 
 ## Schema driven automated block settings forms
@@ -107,24 +121,30 @@ import schema from './schema';
 import BlockDataForm from '@plone/volto/components/manage/Form/BlockDataForm';
 import { Icon } from '@plone/volto/components';
 
-<SidebarPortal selected={this.props.selected}>
-  <BlockDataForm
-    icon={<Icon size="24px" name={nameSVG} />}
-    schema={schema}
-    title={schema.title}
-    headerActions={<button onClick={() => {}}>Action</button>}
-    footer={<div>I am footer</div>}
-    onChangeField={(id, value) => {
-      this.props.onChangeBlock(this.props.block, {
-        ...this.props.data,
-        [id]: value,
-      });
-    }}
-    onChangeBlock={onChangeBlock}
-    formData={this.props.data}
-    block={block}
-  />
-</SidebarPortal>;
+const Edit = (props) => {
+  const {selected, block, data, onChangeBlock} = props;
+
+  return (
+    <SidebarPortal selected={selected}>
+      <BlockDataForm
+        icon={<Icon size="24px" name={nameSVG} />}
+        schema={schema}
+        title={schema.title}
+        headerActions={<button onClick={() => {}}>Action</button>}
+        footer={<div>I am footer</div>}
+        onChangeField={(id, value) => {
+          onChangeBlock(block, {
+            ...data,
+            [id]: value,
+          });
+        }}
+        onChangeBlock={onChangeBlock}
+        formData={data}
+        block={block}
+      />
+    </SidebarPortal>;
+  )
+}
 ```
 
 ## Object Browser

docs/source/blocks/examples/custom-schema-and-view.md

@@ -0,0 +1,165 @@
+---
+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"
+---
+
+(custom-schema-and-view)=
+
+# Block with a custom schema
+
+You can create a block with several settings defined using a schema, and let Volto render the edit form by itself.
+
+To do so, define the schema, the view component, and configure the block settings.
+
+## 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.
+
+## Schema
+
+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.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 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({
+  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.
+It will be a small HTML fragment.
+
+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 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 (
+    <div className={cx('block', 'block02', className)} style={style}>
+      I am the Block view component!
+      <ul>
+        <li>Title: {data.title}</li>
+        <li>URL: {data.url}</li>
+      </ul>
+    </div>
+  );
+};
+
+export default View;
+```
+
+## 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.
+
+```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.
+
+```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
+    // 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
+    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.
+
+```js
+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';
+```
+
+## See it in action
+
+Your block is ready to be used in your site.
+
+Restart your Volto site, and you can add it using the block add form.