diff --git a/docs/source/blocks/settings.md b/docs/source/blocks/settings.md index 0dcb406c45..6c72cf944f 100644 --- a/docs/source/blocks/settings.md +++ b/docs/source/blocks/settings.md @@ -192,42 +192,140 @@ const groupBlocksOrder = [ You can change it (and add your own group) in your project configuration object. -### initialBlocks - Initial Blocks per content type +### initialBlocks - Initial Blocks Configuration in Volto -By default, the default blocks for all content types are a title block and a text block. You can override this and provide your own by modifying the configuration object: +The `config.blocks.initialBlocks` setting allows developers to specify the initial blocks automatically added for specific content types in Volto. By default, all content types include a title block and a text block. You can override this behavior and define custom initial blocks for each content type. -```js -const initialBlocks = {}; -``` +### Example: Setting Custom Initial Blocks + +Here’s how to configure the `initialBlocks` object to define blocks for a custom content type: -and provide your own per content type, e.g: +Basic Example: ```js const initialBlocks = { - Document: ['leadimage', 'title', 'text', 'listing' ] + Document: ['leadimage', 'title', 'text', 'listing'], }; ``` -You can also pass the full configuration for the block using an object: +This configuration ensures that when a new Document is created, it initializes with the following blocks in order: + +1. Lead Image +2. Title +3. Text +4. Listing + +### Advanced Example: Full Block Configuration: + +You can also define detailed configurations for each block, including settings such as `fixed`, `required`, and default values: ```js const initialBlocks = { Document: [ { '@type': 'leadImage', fixed: true, required: true }, { '@type': 'title' }, - { '@type': 'slate', value: 'My default text', plaintext: 'My default text' }, + { + '@type': 'slate', + value: 'My default text', + plaintext: 'My default text', + }, ], }; ``` -## Listing block configuration +### Disabling New Blocks and Requiring Specific Blocks + +For scenarios where you want to restrict users from adding new blocks or make certain blocks mandatory: + +### Configuring Required and `disableNewBlocks`: + +```js +const initialBlocks = { + CustomContentType: [ + { '@type': 'title', required: true, fixed: true }, + { '@type': 'listing', required: true, fixed: true }, + ], +}; +``` + +- `required`: Ensures the block cannot be removed. + +- `fixed`: Prevents the block from being reordered. + +### Schema Automation for Required and DisableNewBlocks: + +To automate these settings for a custom content type, you can override the content type schema or use a plugin that applies these properties programmatically. + +### Overwriting Block Behavior for a Custom Content Type + +To modify block behavior specifically for one content type without affecting others, you can shadow components. For example, to customize the title block for a specific content type: -`allowed_headline_tags` -: Allows you to customize the choices of the "Headline Tag" types shown in the block settings by default. It has the following syntax (a list of lists, where a list item consists of `['token', 'display_name']`): + 1. ### Component Shadowing for Title Block: + + - Override the `Title` block component to check the content type and apply the desired settings: + + ```js + import TitleBlockEdit from '@plone/volto/components/manage/Blocks/Title/Edit'; + + const CustomTitleBlockEdit = (props) => { + const { data, block } = props; + if (data.contentType === 'CustomContentType') { + return ; + } + return ; + }; + + export default CustomTitleBlockEdit; + ``` + + 2. ### Customizing Layout in the Volto Add-On: + + - Add schema configuration for your custom content type in your Volto add-on: + + ```js + const customSchemaEnhancer = (schema) => { + if (schema.id === 'CustomContentType') { + schema.disableNewBlocks = true; + schema.blocks = { + required: ['title', 'listing'], + allowedBlocks: ['title', 'listing'], + }; + } + return schema; + }; + ``` + +### Restricting Blocks to Enforce Layout +To enforce that a content type only allows specific blocks (e.g., title and listing), define `allowedBlocks` in your configuration: + +```js +const blocksConfig = { + CustomContentType: { + allowedBlocks: ['title', 'listing'], + initialBlocks: [ + { '@type': 'title', required: true }, + { '@type': 'listing', required: true }, + ], + }, +}; +``` + +This ensures that only the `title` and `listing` blocks can be added to the content type. + + +## Adding Listing Block Customization + +The Listing block can also be configured with advanced settings like `allowed_headline_tags`. Here’s an example: + +Example Configuration: + +```js +const listingBlockConfig = { + allowed_headline_tags: [['h2', 'h2'], ['h3', 'h3']], +}; +``` - ```js - allowed_headline_tags: [['h2', 'h2'], ['h3', 'h3']] - ``` + If only one tag is provided (e.g., `[['h2', 'h2']]`), the setting will hide itself from the listing block settings. If not specified, an internal hardcoded default is the above shown example.