Skip to content

Commit

Permalink
Merge branch 'main' into fix-useClipboard
Browse files Browse the repository at this point in the history
  • Loading branch information
nileshgulia1 authored Jan 13, 2025
2 parents 17d59e9 + 1c88feb commit deeb9b4
Show file tree
Hide file tree
Showing 45 changed files with 1,255 additions and 55 deletions.
6 changes: 6 additions & 0 deletions docs/source/_static/add-document.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions docs/source/_static/pen.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/source/blocks/anatomy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
74 changes: 47 additions & 27 deletions docs/source/blocks/editcomponent.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
154 changes: 154 additions & 0 deletions docs/source/blocks/examples/custom-schema-and-view.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
---
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}`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}`ExampleBlock01` folder, with the following contents.

```js
import messages from './messages';

const Schema = ({ intl }) => {
return {
title: intl.formatMessage(messages.block01),
block: 'block01',
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}`ExampleBlock01` folder with the following contents.

```js
import { defineMessages } from 'react-intl';

const messages = defineMessages({
block01: {
id: 'block01',
defaultMessage: 'Block 01',
},
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}`ExampleBlock01` 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 (
<div className={cx('block', 'block01', 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 before the last `return config;` statement.

```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
};
```

At the top of the file, import the relevant components as follows.

```js
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';
```

## 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 {guilabel}`Edit` <img alt="Edit icon" src="../../_static/pen.svg" class="inline"> or {guilabel}`Add` <img alt="Add icon" src="../../_static/add-document.svg" class="inline"> content views.
Loading

0 comments on commit deeb9b4

Please sign in to comment.