diff --git a/README.md b/README.md index 433de30..f90b72e 100644 --- a/README.md +++ b/README.md @@ -251,51 +251,62 @@ Now an editor can :- #### Container Blocks ([TODO](https://github.com/collective/volto-hydra/issues/99)) -If your block can contain other blocks you can let hydra know where the sub-blocks can be added by marking the html element that will contain them. +My blocks are best handled as containers of other blocks and hydra will provide a UI for you manage these subblocks. -For example if you had a grid implemented as a table that can only allow a single block per column then you might have +Lets say you have a table block. A table is container of rows, which is a container of cells, which is a container or other blocks. +In the simplest case you don't need any special markup. Just render the blocks from "blocks" and "blocks_layout" fields with the +```data-block-uid``` and hydra will manage the UI for you. ```html - +
- + - +

my text

my text

other slate

other slate
``` -but if you wanted to allow many columns each with many blocks inside you can use specify a column block +During editing containers are never empty to ensure they take up space and are easy to select and navigate. +This means all containers have a default block type that will get created if the last block is removed. +By default a container allows allow other blocks and it's default block is the SlateBlock. A slate block +is special in that using the "/" shortcut you can turn it into another block. + +Some containers you will need another way to pick the first block in the container. For example, +let's say you have a table where cells can only contain a Video or Image. +You can specify this with a container specification in ```data-block-container```. ```html - - - - - - +

my text

other slate

+ +
``` -- The allowed block types for a given container can be overridden in the hydra settings at initialization. -- The first of the allowed blocks is the default block. In the case where the only remaining block is deleted, a new empty default - block will be created in its place so that a container is never empty (TODO). - - if you want to allow choice of the first block then a chooser block can be the default (TODO) -- The orientation tells hydra where to place the add button and DND drop markers. -- if there is a maximum number of blocks a container can hold then specify it in the data attribute ```data-block-container-horizontal="blocks,4"``` -- it might be that a container has more than area to add blocks. In which case you use a different field prefix, e.g. ```data-block-container-horizontal="left"```. - This will put the blocks into a dict in the field ```left``` and the order in a list in ```left_layout```. +In this case, the initial block will be of a special type called ```ChooserBlock```. Just render it to take up +the normal amount of space one of the other blocks would be expected to take up and Hydra will add a "+" icon +in the middle which allows the user to replace this dummy block with one of the actual block types. ChooserBlocks +won't get saved so won't be rendered when not editing. + +The optional specifications you can give the container are + +- allowed: which block types to let be added, default=[]=any block +- default: the block type to create when blocks is less than min. default=ChooserBlock or Slate if allowed. +- min: default blocks will be created to make up this number. default=1 +- max: you can't add more blocks than this. default=null=unlimited +- style: ```horizontal``` or ```vertical``` to help put the "add" button in the right place. default=null=opposite of parent. +- field: You can have more than one area of sub-blocks in a container by using a different field prefix. default=blocks. +- hide_chooser_add: you might want to put in a custom add button via ```data-block-choose``` or an api call. default=false if it's a ChooserBlock Now an editor can do the following on a container such as the Grid Block: -- Add a new sub-block visually on the frontend +- Add a new sub-block visually on the frontend. The add icon is in the direction the new block will appear. - Use enter on a rich text block to add a sub-block - remove blocks from a container - DND blocks in and out of containers or to reorder them -- if it is hard to select a container using the mouse then the quanta toolbar provides an "up" action ([TODO](https://github.com/collective/volto-hydra/issues/66)) - to select the container of the current block. On mobile a single press - selects the container and a double press selects the sub-block. +- You can see all container settings on the sidebar when a sub-block is selected, and you can close those settings to select the parent and + and manage the containers sub blocks from the side panel ### Level 5: Enable Visual frontend editing of Text, Media and links ([TODO](https://github.com/collective/volto-hydra/issues/5))