revised version of container hydra api

README.md

@@ -251,52 +251,70 @@ 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.
+Many blocks are best handled as containers of other blocks and hydra will provide a UI for you manage these sub-blocks.
 
-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 ColumnsBlock. A ColumnsBlock containers one or more ColumnBlock, which is a container of 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
-<table data-block-uid="..." data-block-container-horizontal="blocks">
- <tr data-block-uid="...">
- <td data-editable-field="value"><p>my text</p></td>
- </tr>
- <tr data-block-uid="...">
- <td data-editable-field="value"><p>other slate</p></td>
+<table data-block-uid="...">
+ <tr>
+ <td data-block-uid="...">
+ <p data-block-uid="...">my text</p>
+ <img data-block-uid="..." src="..."/>
+ </td>
+ <td data-block-uid="...">
+ <p data-block-uid="...">other slate</p>
+ </td>
  </tr>
 </table>
 ```
 
-but if you wanted to allow many columns each with many blocks inside you can use specify a column block
+Now an editor can do the following:
+- Add a new sub-block visually on the frontend. The add icon is in the direction the new block will appear.
+- You can see all container settings on the sidebar when a sub-block is selected, e.g. Column settings and ColumnBlock settings.
+- To add another column select the parent column and click add and a new column will appear next to it.
+ - Select the column by clicking "up" on the quanta toolbar or close the sub-block settings.
+- remove blocks from a container
+- DND blocks in and out of containers or to reorder them
+- To select the container close sub-block section on the sidebar. This also allows you
+ to manage the containers sub blocks from the side panel 
+
+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 grid block where cells can only contain a Video or Image.
+You can specify this with a container specification in ```data-block-container```.
 
 ```html
-<table data-block-uid="..." data-block-container-vertical="blocks,4">
- <tr data-block-uid="..." data-block-container-vertical="blocks">
- <td data-block-uid="..." data-editable-field="value"><p>my text</p></td>
- </tr>
- <tr data-block-uid="..." data-block-container-vertical="blocks">
- <td data-block-uid="..." data-editable-field="value"><p>other slate</p></td>
+<table data-block-uid="..." data-block-container="{'allowed':['VideoBlock','ImageBlock']}">
+ <tr>
+ <td data-block-uid="..."><video src="..."></video></td>
+ <td data-block-uid="..."><img src="..."></td>
  </tr>
 </table>
 ```
 
-- 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```.
-
-Now an editor can do the following on a container such as the Grid Block:
-- Add a new sub-block visually on the frontend
-- 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. 
+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
 
+Note: The content object is itself a container so the same specifications can be used for the Page as a whole. 
 
 ### Level 5: Enable Visual frontend editing of Text, Media and links ([TODO](https://github.com/collective/volto-hydra/issues/5))