Update blocks module API

docs/api/assets.md

@@ -22,6 +22,7 @@ const assetManager = editor.AssetManager;
 
 *   `asset:open` - Asset Manager opened.
 *   `asset:close` - Asset Manager closed.
+*   `asset:add` - Asset added. The [Asset] is passed as an argument to the callback.
 *   `asset:remove` - Asset removed. The [Asset] is passed as an argument to the callback.
 *   `asset:update` - Asset updated. The updated [Asset] and the object containing changes are passed as arguments to the callback.
 *   `asset:upload:start` - Before the upload is started.

docs/api/block_manager.md

@@ -12,16 +12,22 @@ const editor = grapesjs.init({
 })
 ```
 
-Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance
+Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.
 
 ```js
+// Listen to events
+editor.on('block:add', (block) => { ... });
+
+// Use the API
 const blockManager = editor.BlockManager;
+blockManager.add(...);
 ```
 
 ## Available Events
 
-*   `block:add` - New block added
-*   `block:remove` - Block removed
+*   `block:add` - Block added. The [Block] is passed as an argument to the callback.
+*   `block:remove` - Block removed. The [Block] is passed as an argument to the callback.
+*   `block:update` - Block updated. The [Block] and the object containing changes are passed as arguments to the callback.
 *   `block:drag:start` - Started dragging block, model of the block is passed as an argument
 *   `block:drag` - Dragging block, the block's model and the drag event are passed as arguments
 *   `block:drag:stop` - Dragging of the block is stopped. As agruments for the callback you get, the dropped component model (if dropped successfully) and the model of the block
@@ -46,27 +52,15 @@ Get configuration object
 
 Returns **[Object][11]** 
 
-## onLoad
-
-Load default blocks if the collection is empty
-
 ## add
 
-Add new block to the collection.
+Add new block.
 
 ### Parameters
 
-*   `id` **[string][12]** Block id
-*   `opts` **[Object][11]** Options
-
-    *   `opts.label` **[string][12]** Name of the block
-    *   `opts.content` **[string][12]** HTML content
-    *   `opts.category` **([string][12] | [Object][11])** Group the block inside a category.
-        You should pass objects with id property, eg:
-        {id: 'some-uid', label: 'My category'}
-        The string will be converted in:
-        'someid' => {id: 'someid', label: 'someid'}
-    *   `opts.attributes` **[Object][11]** Block attributes (optional, default `{}`)
+*   `id` **[String][12]** Block ID
+*   `props` **[Block]** Block properties
+*   `opts`   (optional, default `{}`)
 
 ### Examples
 
@@ -85,11 +79,11 @@ Returns **[Block]** Added block
 
 ## get
 
-Return the block by id
+Get the block by id.
 
 ### Parameters
 
-*   `id` **[string][12]** Block id
+*   `id` **[String][12]** Block id
 
 ### Examples
 
@@ -103,7 +97,7 @@ Returns **[Block]**
 
 ## getAll
 
-Return all blocks
+Return all blocks.
 
 ### Examples
 
@@ -113,28 +107,30 @@ console.log(JSON.stringify(blocks));
 // [{label: 'Heading', content: '<h1>Put your ...'}, ...]
 ```
 
-Returns **Collection** 
+Returns **Collection<[Block]>** 
 
 ## getAllVisible
 
 Return the visible collection, which containes blocks actually rendered
 
-Returns **Collection** 
+Returns **Collection<[Block]>** 
 
 ## remove
 
-Remove a block by id
+Remove block.
 
 ### Parameters
 
-*   `id` **[string][12]** Block id
+*   `block` **([String][12] | [Block])** Block or block ID
+*   `opts`   (optional, default `{}`)
 
 ### Examples
 
 ```javascript
-// Id of the block which need to be removed
-const id = 'button';
-blockManager.remove(id);
+const removed = blockManager.remove('BLOCK_ID');
+// or by passing the Block
+const block = blockManager.get('BLOCK_ID');
+blockManager.remove(block);
 ```
 
 Returns **[Block]** Removed block

docs/modules/Blocks.md

@@ -307,7 +307,7 @@ For a complete list of available events, you can check it [here](/api/block_mana
 
 
 
-
+<!--
 ## Custom render <Badge text="0.14.55+"/>
 
 If you need to customize the aspect of each block you can pass a `render` callback function in the block definition. Let's see how it works.
@@ -350,6 +350,7 @@ blockManager.add('some-block-id', {
 });
 ```
 <img :src="$withBase('/block-custom-render2.jpg')">
+-->
 
 
 

src/block_manager/index.js

@@ -22,6 +22,7 @@
  * ## Available Events
  * * `block:add` - Block added. The [Block] is passed as an argument to the callback.
  * * `block:remove` - Block removed. The [Block] is passed as an argument to the callback.
+ * * `block:update` - Block updated. The [Block] and the object containing changes are passed as arguments to the callback.
  * * `block:drag:start` - Started dragging block, model of the block is passed as an argument
  * * `block:drag` - Dragging block, the block's model and the drag event are passed as arguments
  * * `block:drag:stop` - Dragging of the block is stopped. As agruments for the callback you get, the dropped component model (if dropped successfully) and the model of the block
@@ -52,8 +53,8 @@ import BlocksView from './view/BlocksView';
 
 export const evAll = 'block';
 export const evPfx = `${evAll}:`;
-export const evUpdate = `${evPfx}update`;
 export const evAdd = `${evPfx}add`;
+export const evUpdate = `${evPfx}update`;
 export const evRemove = `${evPfx}remove`;
 export const evRemoveBefore = `${evRemove}:before`;
 // export const evCustom = `${evPfx}custom`;
@@ -117,18 +118,11 @@ export default () => {
       return c;
     },
 
-    /**
-     * Load default blocks if the collection is empty
-     */
     onLoad() {
       const blocks = this.getAll();
       !blocks.length && blocks.reset(c.blocks);
     },
 
-    /**
-     * Executed once the main editor instance is rendered
-     * @private
-     */
     postRender() {
       const collection = blocksVisible;
       blocksView = new BlocksView({ collection, categories }, c);
@@ -142,17 +136,9 @@ export default () => {
     },
 
     /**
-     * Add new block to the collection.
-     * @param {string} id Block id
-     * @param {Object} opts Options
-     * @param {string} opts.label Name of the block
-     * @param {string} opts.content HTML content
-     * @param {string|Object} opts.category Group the block inside a category.
-     *                                      You should pass objects with id property, eg:
-     *                                      {id: 'some-uid', label: 'My category'}
-     *                                      The string will be converted in:
-     *                                      'someid' => {id: 'someid', label: 'someid'}
-     * @param {Object} [opts.attributes={}] Block attributes
+     * Add new block.
+     * @param {String} id Block ID
+     * @param {[Block]} props Block properties
      * @returns {[Block]} Added block
      * @example
      * blockManager.add('h1-block', {
@@ -164,15 +150,15 @@ export default () => {
      *   }
      * });
      */
-    add(id, opts) {
-      var obj = opts || {};
-      obj.id = id;
-      return blocks.add(obj);
+    add(id, props, opts = {}) {
+      const prp = props || {};
+      prp.id = id;
+      return blocks.add(prp, opts);
     },
 
     /**
-     * Return the block by id
-     * @param  {string} id Block id
+     * Get the block by id.
+     * @param  {String} id Block id
      * @returns {[Block]}
      * @example
      * const block = blockManager.get('h1-block');
@@ -185,7 +171,7 @@ export default () => {
 
     /**
      * Return all blocks.
-     * @return {Collection<[Block]>}
+     * @returns {Collection<[Block]>}
      * @example
      * const blocks = blockManager.getAll();
      * console.log(JSON.stringify(blocks));
@@ -197,7 +183,7 @@ export default () => {
 
     /**
      * Return the visible collection, which containes blocks actually rendered
-     * @return {Collection}
+     * @returns {Collection<[Block]>}
      */
     getAllVisible() {
       return blocksVisible;
@@ -213,8 +199,8 @@ export default () => {
      * const block = blockManager.get('BLOCK_ID');
      * blockManager.remove(block);
      */
-    remove(id, opts) {
-      return this.__remove(id, opts);
+    remove(block, opts = {}) {
+      return this.__remove(block, opts);
     },
 
     /**