From 18c79885ed57f3d78d583867c4950882011ea6b6 Mon Sep 17 00:00:00 2001 From: zang77 Date: Wed, 6 Jul 2022 22:23:06 -0700 Subject: [PATCH 1/3] Improved block.insert() by allowing passing parameters as an object --- src/components/modules/api/blocks.ts | 19 ++++++--------- src/components/ui/toolbox.ts | 12 ++++------ types/api/block.d.ts | 36 ++++++++++++++++++++++++++++ types/api/blocks.d.ts | 21 ++++------------ 4 files changed, 53 insertions(+), 35 deletions(-) diff --git a/src/components/modules/api/blocks.ts b/src/components/modules/api/blocks.ts index 8d742c850..5900e2f4c 100644 --- a/src/components/modules/api/blocks.ts +++ b/src/components/modules/api/blocks.ts @@ -231,19 +231,14 @@ export default class BlocksAPI extends Module { * @param replace - pass true to replace the Block existed under passed index */ public insert = ( - type: string = this.config.defaultBlock, - data: BlockToolData = {}, - config: ToolConfig = {}, - index?: number, - needToFocus?: boolean, - replace?: boolean + newBlock ): 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); @@ -278,7 +273,7 @@ export default class BlocksAPI extends Module { public insertNewBlock(): void { _.log('Method blocks.insertNewBlock() is deprecated and it will be removed in the next major release. ' + 'Use blocks.insert() instead.', 'warn'); - this.insert(); + this.insert({}); } /** diff --git a/src/components/ui/toolbox.ts b/src/components/ui/toolbox.ts index 7ae48c58f..4a95d60a9 100644 --- a/src/components/ui/toolbox.ts +++ b/src/components/ui/toolbox.ts @@ -404,14 +404,12 @@ 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, 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..dbdbe68f9 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..10b8fc874 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 - new block config + * + */ + insert(newBlock: NewBlock): BlockAPI; /** From c25bc53a0fe4b7e329777eb3bf11375b55f08de2 Mon Sep 17 00:00:00 2001 From: zang77 Date: Fri, 8 Jul 2022 18:11:33 -0700 Subject: [PATCH 2/3] Fixed some issues commented out from last pr. Set the default parameter for insert. --- src/components/modules/api/blocks.ts | 19 +++++++++---------- src/components/ui/toolbox.ts | 1 + types/api/block.d.ts | 6 +++--- types/api/blocks.d.ts | 2 +- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/components/modules/api/blocks.ts b/src/components/modules/api/blocks.ts index 5900e2f4c..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,17 +221,16 @@ 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 = ( - newBlock + newBlock: NewBlock = { + type: this.config.defaultBlock, + data: {}, + config: {} + } ): BlockAPIInterface => { const insertedBlock = this.Editor.BlockManager.insert({ tool: newBlock.type, @@ -273,7 +272,7 @@ export default class BlocksAPI extends Module { public insertNewBlock(): void { _.log('Method blocks.insertNewBlock() is deprecated and it will be removed in the next major release. ' + 'Use blocks.insert() instead.', 'warn'); - this.insert({}); + this.insert(); } /** diff --git a/src/components/ui/toolbox.ts b/src/components/ui/toolbox.ts index 4a95d60a9..cf40e7067 100644 --- a/src/components/ui/toolbox.ts +++ b/src/components/ui/toolbox.ts @@ -407,6 +407,7 @@ export default class Toolbox extends EventsDispatcher { const newBlock = this.api.blocks.insert({ type: toolName, data: blockData, + config: undefined, index, replace: currentBlock.isEmpty, }); diff --git a/types/api/block.d.ts b/types/api/block.d.ts index dbdbe68f9..3094a62b0 100644 --- a/types/api/block.d.ts +++ b/types/api/block.d.ts @@ -83,17 +83,17 @@ export interface NewBlock { /** * Tool name */ - type?: string; + type: string; /** * Tool data to insert */ - data?: BlockToolData; + data: BlockToolData; /** * Tool config */ - config?: ToolConfig; + config: ToolConfig; /** * index where to insert new Block diff --git a/types/api/blocks.d.ts b/types/api/blocks.d.ts index 10b8fc874..a9703e58e 100644 --- a/types/api/blocks.d.ts +++ b/types/api/blocks.d.ts @@ -96,7 +96,7 @@ export interface Blocks { /** * Insert new Block and return inserted Block API * - * @param newBlock - new block config + * @param{NewBlock} newBlock - new block config * */ insert(newBlock: NewBlock): BlockAPI; From c1d3a3ec499ec3aa1fde4553be366e4e51ce104b Mon Sep 17 00:00:00 2001 From: zang77 Date: Mon, 11 Jul 2022 14:32:26 -0700 Subject: [PATCH 3/3] Added changelog for insert function. --- docs/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) 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