diff --git a/docs/api/assets.md b/docs/api/assets.md index 02ee44616..bbc3cffd1 100644 --- a/docs/api/assets.md +++ b/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. diff --git a/docs/api/block_manager.md b/docs/api/block_manager.md index 65e1086a6..770de1ec5 100644 --- a/docs/api/block_manager.md +++ b/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: '

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 diff --git a/docs/modules/Blocks.md b/docs/modules/Blocks.md index 090b0e24e..6b59e5b64 100644 --- a/docs/modules/Blocks.md +++ b/docs/modules/Blocks.md @@ -307,7 +307,7 @@ For a complete list of available events, you can check it [here](/api/block_mana - + diff --git a/src/block_manager/index.js b/src/block_manager/index.js index 0a2a5c8b4..8382b25ee 100644 --- a/src/block_manager/index.js +++ b/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); }, /**