diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index aeeb5b2e..1b71da9d 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,7 @@ - `New` — *Block Tunes API* — Now `render()` method of a Block Tune can return config with just icon, label and callback instead of custom HTML. This impovement is a key to the new straightforward way of configuring tune's appearance in Block Tunes menu. - `New` — *Tools API* — As well as `render()` in `Tunes API`, Tool's `renderSettings()` now also supports new configuration format. - `New` — *UI* — Meet the new icons from [CodeX Icons](https://github.com/codex-team/icons) pack 🛍 💝 +- `New` — *BlocksAPI* — the `blocks.insert()` method now also have the optional `id` param. If passed, this id will be used instead of the generated one. - `Deprecated` — *Styles API* — CSS classes `.cdx-settings-button` and `.cdx-settings-button--active` are not recommended to use. Consider configuring your block settings with new JSON API instead. - `Fix` — Wrong element not highlighted anymore when popover opened. - `Fix` — When Tunes Menu open keydown events can not be handled inside plugins. diff --git a/src/components/modules/api/blocks.ts b/src/components/modules/api/blocks.ts index c5a98941..a711d52f 100644 --- a/src/components/modules/api/blocks.ts +++ b/src/components/modules/api/blocks.ts @@ -227,6 +227,7 @@ export default class BlocksAPI extends Module { * @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 {string} id — An optional id for the new block. If omitted then the new id will be generated */ public insert = ( type: string = this.config.defaultBlock, @@ -235,9 +236,11 @@ export default class BlocksAPI extends Module { config: ToolConfig = {}, index?: number, needToFocus?: boolean, - replace?: boolean + replace?: boolean, + id?: string ): BlockAPIInterface => { const insertedBlock = this.Editor.BlockManager.insert({ + id, tool: type, data, index, diff --git a/test/cypress/tests/api/blocks.spec.ts b/test/cypress/tests/api/blocks.spec.ts index a29e7077..ab3f2ac8 100644 --- a/test/cypress/tests/api/blocks.spec.ts +++ b/test/cypress/tests/api/blocks.spec.ts @@ -119,4 +119,26 @@ describe('api.blocks', () => { }); }); }); + + /** + * api.blocks.insert(type, data, config, index, needToFocus, replace, id) + */ + describe('.insert()', function () { + it('should preserve block id if it is passed', function () { + cy.get('@editorInstance').then(async (editor: any) => { + const type = 'paragraph'; + const data = { text: 'codex' }; + const config = undefined; + const index = undefined; + const needToFocus = undefined; + const replace = undefined; + const id = 'test-id-123'; + + const block = editor.blocks.insert(type, data, config, index, needToFocus, replace, id); + + expect(block).not.to.be.undefined; + expect(block.id).to.be.eq(id); + }); + }); + }); }); diff --git a/types/api/blocks.d.ts b/types/api/blocks.d.ts index f684bf78..0a90b031 100644 --- a/types/api/blocks.d.ts +++ b/types/api/blocks.d.ts @@ -102,6 +102,8 @@ export interface Blocks { * @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 + * @param {string} id — An optional id for the new block. If omitted then the new id will be generated + */ insert( type?: string, @@ -110,6 +112,7 @@ export interface Blocks { index?: number, needToFocus?: boolean, replace?: boolean, + id?: string, ): BlockAPI;