diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 5d37082a4..5a9e45328 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -5,6 +5,7 @@ - `New` — *Tools API* — Introducing new feature — toolbox now can have multiple entries for one tool!
Due to that API changes: tool's `toolbox` getter now can return either a single config item or an array of config items - `New` — *Blocks API* — `composeBlockData()` method was added. +- `Improvement` — *Blocks API* — the `insert()` method now allows passing parameters as an object instead of set. ### 2.24.4 diff --git a/src/components/modules/api/blocks.ts b/src/components/modules/api/blocks.ts index 8d742c850..2e8090ac3 100644 --- a/src/components/modules/api/blocks.ts +++ b/src/components/modules/api/blocks.ts @@ -1,4 +1,4 @@ -import { BlockAPI as BlockAPIInterface, Blocks } from '../../../../types/api'; +import { BlockAPI as BlockAPIInterface, Blocks, NewBlock } from '../../../../types/api'; import { BlockToolData, OutputData, ToolConfig } from '../../../../types'; import * as _ from './../../utils'; import BlockAPI from '../../block/api'; @@ -221,29 +221,23 @@ export default class BlocksAPI extends Module { } /** - * Insert new Block and returns it's API + * Insert new Block and returns its API * - * @param {string} type — Tool name - * @param {BlockToolData} data — Tool data to insert - * @param {ToolConfig} config — Tool config - * @param {number?} index — index where to insert new Block - * @param {boolean?} needToFocus - flag to focus inserted Block - * @param replace - pass true to replace the Block existed under passed index + * @param {NewBlock} newBlock — the block that will be inserted */ public insert = ( - type: string = this.config.defaultBlock, - data: BlockToolData = {}, - config: ToolConfig = {}, - index?: number, - needToFocus?: boolean, - replace?: boolean + newBlock: NewBlock = { + type: this.config.defaultBlock, + data: {}, + config: {} + } ): BlockAPIInterface => { const insertedBlock = this.Editor.BlockManager.insert({ - tool: type, - data, - index, - needToFocus, - replace, + tool: newBlock.type, + data: newBlock.data, + index: newBlock.index, + needToFocus: newBlock.needToFocus, + replace: newBlock.replace, }); return new BlockAPI(insertedBlock); diff --git a/src/components/ui/toolbox.ts b/src/components/ui/toolbox.ts index 7ae48c58f..cf40e7067 100644 --- a/src/components/ui/toolbox.ts +++ b/src/components/ui/toolbox.ts @@ -404,14 +404,13 @@ export default class Toolbox extends EventsDispatcher { blockData = Object.assign(defaultBlockData, blockDataOverrides); } - const newBlock = this.api.blocks.insert( - toolName, - blockData, - undefined, + const newBlock = this.api.blocks.insert({ + type: toolName, + data: blockData, + config: undefined, index, - undefined, - currentBlock.isEmpty - ); + replace: currentBlock.isEmpty, + }); /** * Apply callback before inserting html diff --git a/types/api/block.d.ts b/types/api/block.d.ts index c20e46222..3094a62b0 100644 --- a/types/api/block.d.ts +++ b/types/api/block.d.ts @@ -74,3 +74,39 @@ export interface BlockAPI { */ dispatchChange(): void; } + +/** + * @interface NewBlock Describes new block configuration + */ + +export interface NewBlock { + /** + * Tool name + */ + type: string; + + /** + * Tool data to insert + */ + data: BlockToolData; + + /** + * Tool config + */ + config: ToolConfig; + + /** + * index where to insert new Block + */ + index?: number; + + /** + * flag to focus inserted Block + */ + needToFocus?: boolean; + + /** + * should the existed Block on that index be replaced or not + */ + replace?: boolean; +} diff --git a/types/api/blocks.d.ts b/types/api/blocks.d.ts index 21649db8a..a9703e58e 100644 --- a/types/api/blocks.d.ts +++ b/types/api/blocks.d.ts @@ -1,6 +1,6 @@ import {OutputData} from '../data-formats/output-data'; import {BlockToolData, ToolConfig} from '../tools'; -import {BlockAPI} from './block'; +import {BlockAPI, NewBlock} from './block'; /** * Describes methods to manipulate with Editor`s blocks @@ -96,21 +96,10 @@ export interface Blocks { /** * Insert new Block and return inserted Block API * - * @param {string} type — Tool name - * @param {BlockToolData} data — Tool data to insert - * @param {ToolConfig} config — Tool config - * @param {number?} index — index where to insert new Block - * @param {boolean?} needToFocus - flag to focus inserted Block - * @param {boolean?} replace - should the existed Block on that index be replaced or not - */ - insert( - type?: string, - data?: BlockToolData, - config?: ToolConfig, - index?: number, - needToFocus?: boolean, - replace?: boolean, - ): BlockAPI; + * @param{NewBlock} newBlock - new block config + * + */ + insert(newBlock: NewBlock): BlockAPI; /**