diff --git a/docs/source/_static/user-manual/blocks/add_new_block.gif b/docs/source/_static/user-manual/blocks/add-new-block.gif similarity index 100% rename from docs/source/_static/user-manual/blocks/add_new_block.gif rename to docs/source/_static/user-manual/blocks/add-new-block.gif diff --git a/docs/source/_static/user-manual/blocks/block_left_plus_icon.png b/docs/source/_static/user-manual/blocks/block-left-add-icon.png similarity index 100% rename from docs/source/_static/user-manual/blocks/block_left_plus_icon.png rename to docs/source/_static/user-manual/blocks/block-left-add-icon.png diff --git a/docs/source/_static/user-manual/blocks/blocks_type_menu.png b/docs/source/_static/user-manual/blocks/block-types-menu.png similarity index 100% rename from docs/source/_static/user-manual/blocks/blocks_type_menu.png rename to docs/source/_static/user-manual/blocks/block-types-menu.png diff --git a/docs/source/_static/user-manual/blocks/grid-block-manage-blocks.png b/docs/source/_static/user-manual/blocks/grid-block-manage-blocks.png new file mode 100644 index 0000000000..46554cffd1 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/grid-block-manage-blocks.png differ diff --git a/docs/source/_static/user-manual/blocks/grid-block-number-of-columns.png b/docs/source/_static/user-manual/blocks/grid-block-number-of-columns.png new file mode 100644 index 0000000000..9d3e887867 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/grid-block-number-of-columns.png differ diff --git a/docs/source/_static/user-manual/blocks/hero-block.png b/docs/source/_static/user-manual/blocks/hero-block.png new file mode 100644 index 0000000000..6b284bac90 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/hero-block.png differ diff --git a/docs/source/_static/user-manual/blocks/html-block.png b/docs/source/_static/user-manual/blocks/html-block.png new file mode 100644 index 0000000000..64481f922f Binary files /dev/null and b/docs/source/_static/user-manual/blocks/html-block.png differ diff --git a/docs/source/_static/user-manual/blocks/image-block-configuration-options.png b/docs/source/_static/user-manual/blocks/image-block-configuration-options.png new file mode 100644 index 0000000000..555308d43d Binary files /dev/null and b/docs/source/_static/user-manual/blocks/image-block-configuration-options.png differ diff --git a/docs/source/_static/user-manual/blocks/image-block.png b/docs/source/_static/user-manual/blocks/image-block.png new file mode 100644 index 0000000000..2cdba7290b Binary files /dev/null and b/docs/source/_static/user-manual/blocks/image-block.png differ diff --git a/docs/source/_static/user-manual/blocks/images-grid-block-manage-images.png b/docs/source/_static/user-manual/blocks/images-grid-block-manage-images.png new file mode 100644 index 0000000000..efa356c7cd Binary files /dev/null and b/docs/source/_static/user-manual/blocks/images-grid-block-manage-images.png differ diff --git a/docs/source/_static/user-manual/blocks/images-grid-block-number-of-columns.png b/docs/source/_static/user-manual/blocks/images-grid-block-number-of-columns.png new file mode 100644 index 0000000000..9d3e887867 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/images-grid-block-number-of-columns.png differ diff --git a/docs/source/_static/user-manual/blocks/listing-block-configuration.png b/docs/source/_static/user-manual/blocks/listing-block-configuration.png new file mode 100644 index 0000000000..4ef4628d93 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/listing-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/listing-block.png b/docs/source/_static/user-manual/blocks/listing-block.png new file mode 100644 index 0000000000..8073df0fbd Binary files /dev/null and b/docs/source/_static/user-manual/blocks/listing-block.png differ diff --git a/docs/source/_static/user-manual/blocks/map-blocks-configuration.png b/docs/source/_static/user-manual/blocks/map-blocks-configuration.png new file mode 100644 index 0000000000..c6213fe009 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/map-blocks-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/maps-block.png b/docs/source/_static/user-manual/blocks/maps-block.png new file mode 100644 index 0000000000..fd08e0b62e Binary files /dev/null and b/docs/source/_static/user-manual/blocks/maps-block.png differ diff --git a/docs/source/_static/user-manual/blocks/search-block-configuration.png b/docs/source/_static/user-manual/blocks/search-block-configuration.png new file mode 100644 index 0000000000..43f174a8df Binary files /dev/null and b/docs/source/_static/user-manual/blocks/search-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/search-block.png b/docs/source/_static/user-manual/blocks/search-block.png new file mode 100644 index 0000000000..70c6e72ea7 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/search-block.png differ diff --git a/docs/source/_static/user-manual/blocks/table-block-configuration.png b/docs/source/_static/user-manual/blocks/table-block-configuration.png new file mode 100644 index 0000000000..236762bf2c Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/table-block.png b/docs/source/_static/user-manual/blocks/table-block.png new file mode 100644 index 0000000000..ca73e45924 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-block.png differ diff --git a/docs/source/_static/user-manual/blocks/table-of-contents-block-configuration.png b/docs/source/_static/user-manual/blocks/table-of-contents-block-configuration.png new file mode 100644 index 0000000000..6da6c6ad64 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-of-contents-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/table-of-contents-block.png b/docs/source/_static/user-manual/blocks/table-of-contents-block.png new file mode 100644 index 0000000000..73faaba5da Binary files /dev/null and b/docs/source/_static/user-manual/blocks/table-of-contents-block.png differ diff --git a/docs/source/_static/user-manual/blocks/teaser-block-configuration.png b/docs/source/_static/user-manual/blocks/teaser-block-configuration.png new file mode 100644 index 0000000000..84a7e4fb4f Binary files /dev/null and b/docs/source/_static/user-manual/blocks/teaser-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/teaser-block.png b/docs/source/_static/user-manual/blocks/teaser-block.png new file mode 100644 index 0000000000..a69c7dac0d Binary files /dev/null and b/docs/source/_static/user-manual/blocks/teaser-block.png differ diff --git a/docs/source/_static/user-manual/blocks/video-block-configuration.png b/docs/source/_static/user-manual/blocks/video-block-configuration.png new file mode 100644 index 0000000000..b6c5283ca3 Binary files /dev/null and b/docs/source/_static/user-manual/blocks/video-block-configuration.png differ diff --git a/docs/source/_static/user-manual/blocks/video-block.png b/docs/source/_static/user-manual/blocks/video-block.png new file mode 100644 index 0000000000..870ac385bc Binary files /dev/null and b/docs/source/_static/user-manual/blocks/video-block.png differ diff --git a/docs/source/user-manual/blocks.md b/docs/source/user-manual/blocks.md index 4ca9104a80..ad2f3ed10a 100644 --- a/docs/source/user-manual/blocks.md +++ b/docs/source/user-manual/blocks.md @@ -7,79 +7,596 @@ myst: "keywords": "Volto, Plone, frontend, React, User manual, edit blocks" --- -# Edit content using blocks +(edit-content-using-blocks-label)= -```{todo} -This page needs content -``` +# Edit content using blocks Volto features the [Pastanaga UI](https://github.com/plone/pastanaga), allowing you to visually compose a page using blocks. The blocks editor allows you to add, modify, reorder, and delete blocks given your requirements. Blocks provide the user the ability to display content in a specific way, although they can also define behavior and have specific features. -## Choose a pre-built block type -```{todo} -Add description of a Volto block. -``` +(manage-blocks-label)= + +## Manage blocks + +In Volto, "blocks" are individual pieces of content that can be added to a page or other content area. +These blocks can be used to add different types of content—such as text, images, or multimedia—and can be arranged and customized to create a wide range of different layouts. + +Blocks are a key feature of Volto, and are designed to make it easy for users to add and manage content on their website. +They are created using React components, which are modular pieces of code that can be easily reused and customized. -Volto offers several default block types out of the box. -You can access and choose a block type to add to your content type when you have an empty block in it. -To create an empty block after an existing block, click in the block, then hit the {kbd}`Enter` key. +(create-a-block-label)= + +### Create a block + +To create or add an empty block after an existing block, click in the block, then hit the {kbd}`Enter` key. A new empty block appears. -```{image} ../_static/user-manual/blocks/add_new_block.gif -:alt: add new block +```{image} ../_static/user-manual/blocks/add-new-block.gif +:alt: Add new block ``` ```{note} -There is a new experimental feature that places a `+` below every block in a content type. +There is a new experimental feature that places a `+` below a block when it is active or moused over, and when clicked inserts an empty block below the current block. See https://github.com/plone/volto/pull/3815 for details of the feature and how to enable it. ``` +(configure-a-block-label)= + +### Configure a block + +When you select a block, its block editor appears in the right margin of the page. +Almost all blocks have some configuration options. + + +(rearrange-blocks-label)= + +### Rearrange blocks + +To rearrange blocks, to the right of the block you want to move, click on its drag handle, move the block where you want it in the page, and release the drag handle. + + +(delete-a-block-label)= + +### Delete a block + +To delete a block, to the right of the block, click its delete button, a trash can icon. + + +(default-block-types-label)= + +## Default block types + +Volto offers several default block types out of the box. +You can access and choose a block type to add to your content type when you have an empty block in it. + Now with your empty block available, you can select its type in one of two ways. -1. Click the `+` button on the left-hand side of the empty block. - ```{image} ../_static/user-manual/blocks/block_left_plus_icon.png - :alt: Plus button + +1. Click the `+` button to the left of the empty block. + + ```{image} ../_static/user-manual/blocks/block-left-add-icon.png + :alt: Add block button ``` -2. Type `/` inside empty block to open the blocks menu. - ```{image} ../_static/user-manual/blocks/blocks_type_menu.png - :alt: Types of blocks menu + +2. Type `/` inside the empty block to open the block types menu. + You can type a few letters to filter available block types. + You can use the up and down arrow keys to navigate within the list of block types. + To select the block type, you can click or tap on it, or use the {kbd}`Enter` key. + + ```{image} ../_static/user-manual/blocks/block-types-menu.png + :alt: Block types menu ``` (user-manual-description-block-label)= -## Description Block +### Description block + +A description block accepts plain text. +When displayed, it appears as the description in the page, and for search engine optimization in HTML meta tags as `` and ``. -A description block provides a blank textarea to write plain text. (user-manual-grid-block-label)= -## Grid Block +### Grid block + +A grid block creates a single row of columns in a grid, which can be used to display content in a structured, organized way. +You can select the number of columns to insert. + +```{image} ../_static/user-manual/blocks/grid-block-number-of-columns.png +:alt: Choose the number of columns to insert in a grid block. +``` + +After choosing the number of columns to insert in a grid block, you can manage the columns. + +```{image} ../_static/user-manual/blocks/grid-block-manage-blocks.png +:alt: Add a specific block type into a grid block's column +``` + +- Specify the block type in a column by clicking its `+` button. +- Rearrange the order of columns in the grid block by dragging and dropping them. +- Add a column to the grid block by clicking the `+` button above and to the left of it. +- Remove a column from a grid block by clicking its `×` button. + (user-manual-html-block-label)= -## HTML Block +### HTML block + +An HTML block allows users to add custom HTML code to a page. +This can be useful for adding custom functionality or styling to a page, or for integrating with external services or applications. +For example, you can insert an HTML snippet or widget from a third party service to embed a calendar, payment or donation button, or social media into a page. + +```{image} ../_static/user-manual/blocks/html-block.png +:alt: HTML block +``` + +To use an HTML block, you need to have some knowledge of how to write HTML, unless you are provided an HTML code snippet from a third party that you can copy and paste into the block. + (user-manual-hero-block-label)= -## Hero Block +### Hero block + +A hero block creates a full-width banner or header for a page. +It is typically used to highlight important content or to create a visual impact at the top of a page. + +```{image} ../_static/user-manual/blocks/hero-block.png +:alt: Hero block +``` + +Hero blocks typically include a background image or color. +They can also include a title, description, and links to other pages in your site. + +You can use the block editor to configure its options. +You can set the background image or color, its title and description, and links. +For links, you can enter an external URL or select a page in your site by clicking the list icon, and give the link a title. + (user-manual-image-block-label)= -## Image Block +### Image block + +An image block lets a user insert an image into a page and configure its attributes. + +```{image} ../_static/user-manual/blocks/image-block.png +:alt: Image block +``` + +After inserting an image block, an image must be specified by any of the following methods. +- Choose an existing image in the site by clicking the block's list icon. +- Upload a new image by either clicking the block's upload icon or drag and drop. +- Enter a remote image's URL in the block's text area. + Click the arrow icon to save the URL. + +Once you have specified an image, its configurable options become available. +```{image} ../_static/user-manual/blocks/image-block-configuration-options.png +:alt: Image block configuration options +``` + +Source +: The path or URL to the image. + +Alt text +: Alternative text (alt text) is used by screen readers and search engines to describe the image. + Alt text should not be used for decorative images, as it adds noise to the screen reader. + +Alignment +: Options for alignment include left, right, center, and full width. + +Image size +: The image size determines its relative display width, either small, medium, or large. + +Link to +: You can enter a URL in the text field, or click the list icon and choose a page in your website, as the target for a link. + You can optionally have the link open in a new tab when the user clicks it by checking the checkbox {guilabel}`Open in a new tab`. + (user-manual-images-grid-block-label)= -## Images grid Block +### Images grid block + +An images grid block displays a row of images on a page. +It is typically used to showcase a collection of images in a visually appealing way. +It can be configured to display the images in different layouts and styles. + +```{image} ../_static/user-manual/blocks/images-grid-block-number-of-columns.png +:alt: Choose the number of images to insert in an images grid block. +``` + +After choosing the number of images to insert in an images grid block, you can configure the images exactly as you would configure a single image in an image block. + +```{image} ../_static/user-manual/blocks/image-block-configuration-options.png +:alt: Image block configuration options +``` + +Source +: The path or URL to the image. + +Alt text +: Alternative text (alt text) is used by screen readers and search engines to describe the image. + Alt text should not be used for decorative images, as it adds noise to the screen reader. + +Alignment +: Options for alignment include left, right, center, and full width. + +Image size +: The image size determines its relative display width, either small, medium, or large. + +Link to +: You can enter a URL in the text field, or click the list icon and choose a page in your website, as the target for a link. + You can optionally have the link open in a new tab when the user clicks it by checking the checkbox {guilabel}`Open in a new tab`. + +You can also manage the images in the images grid block. + +```{image} ../_static/user-manual/blocks/images-grid-block-manage-images.png +:alt: Manage images in an images gride block +``` + +- Rearrange the order of images in the images grid block by dragging and dropping them. +- Add an image to the images grid block by clicking the `+` button above and to the left of it. +- Remove an image from an images grid block by clicking its `×` button. + + +After inserting an image grid block, an image must be specified by any of the following methods. + (user-manual-listing-block-label)= -## Listing Block +### Listing block + +A listing block allows users to display a list of content items in your Plone site on a page. +A site editor can configure the criteria to use for retrieving content items, including text, title, dates, and creator. +The retrieved results can be configured with a sort order, limit of results, and whether to batch the results with pagination. + +```{image} ../_static/user-manual/blocks/listing-block.png +:alt: Listing block +``` + +The listing block has several configuration options. + +```{image} ../_static/user-manual/blocks/listing-block-configuration.png +:alt: Listing block configuration +``` + +Variation +: Options for variation include {guilabel}`Default`, {guilabel}`Image gallery`, and {guilabel}`Summary`. + +Headline +: Optionally add a headline to the listing block. + +Headline level +: Headline level sets the level of the headline to either {guilabel}`H2` or {guilabel}`H3`. + +Criteria +: Add criteria for the search. + Options include searching metadata, dates, and text. + Each criterion has its own options. + For example, you can configure a search for content that was created between two dates, or for its location within a path of your Plone site. + +Sort on +: Sort the retrieved results by a given option. + Options include metadata, dates, and text. + +Results limit +: Limit the number of results returned. + +Item batch size +: Batch the search result items into a specified batch size. + (user-manual-maps-block-label)= -## Maps Block +### Maps block + +A map block allows a user to add a map to a page. +It is typically used to display a geographic location or region, or provide travel directions. + +```{image} ../_static/user-manual/blocks/maps-block.png +:alt: Maps block +``` + +To use a map block, the third party map service must provide a snippet of HTML code that you can copy and paste into the map block. +Usually the snippet includes an `