Rename initialBlock to defaultBlock

docs/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### 2.19
 
+- `Improvements` - The `initialBlock` property of Editor config is deprecated. Use the `defaultBlock` instead. [#993](https://github.com/codex-team/editor.js/issues/993)
 - `Fix` - Fixed the issue of toolbar not disappearing on entering input in Chinese, Hindi and some other languages. [#1196](https://github.com/codex-team/editor.js/issues/1196)
 - `Improvements` - BlockAPI `call()` method now returns the result of calling method, thus allowing it to expose arbitrary data as needed [#1205](https://github.com/codex-team/editor.js/pull/1205)
 

docs/tools.md

@@ -78,7 +78,7 @@ var editor = new EditorJS({
     },
     header: Header
   },
-  initialBlock : 'text',
+  defaultBlock : 'text',
 });
 ```
 
@@ -118,7 +118,7 @@ To handle pasted HTML elements object returned from `pasteConfig` getter should
 | -- | -- | -- |
 | `tags` | `String[]` | _Optional_. Should contain all tag names you want to be extracted from pasted data and processed by your `onPaste` method |
 
-For correct work you MUST provide `onPaste` handler at least for `initialBlock` Tool.
+For correct work you MUST provide `onPaste` handler at least for `defaultBlock` Tool.
 
 > Example
 
@@ -144,7 +144,7 @@ Your Tool can analyze text by RegExp patterns to substitute pasted string with d
 
 **Note** Editor will check pattern's full match, so don't forget to handle all available chars in there.
 
-Pattern will be processed only if paste was on `initialBlock` Tool and pasted string length is less than 450 characters.
+Pattern will be processed only if paste was on `defaultBlock` Tool and pasted string length is less than 450 characters.
 
 > Example
 

example/example-dev.html

@@ -167,7 +167,7 @@
       /**
        * This Tool will be used as default
        */
-      // initialBlock: 'paragraph',
+      // defaultBlock: 'paragraph',
 
       /**
        * Initial Editor data

example/example.html

@@ -156,7 +156,7 @@
       /**
        * This Tool will be used as default
        */
-      // initialBlock: 'paragraph',
+      // defaultBlock: 'paragraph',
 
       /**
        * Initial Editor data

src/components/core.ts

@@ -130,11 +130,10 @@ export default class Core {
     /**
      * If holderId is preset, assign him to holder property and work next only with holder
      */
+    _.deprecationAssert(!!config.holderId, 'config.holderId', 'config.holder');
     if (config.holderId && !config.holder) {
       config.holder = config.holderId;
       config.holderId = null;
-      _.log('holderId property is deprecated and will be removed in the next major release. ' +
-        'Use holder property instead.', 'warn');
     }
 
     /**
@@ -157,10 +156,13 @@ export default class Core {
 
     _.setLogLevel(this.config.logLevel);
 
+
     /**
-     * If initial Block's Tool was not passed, use the Paragraph Tool
+     * If default Block's Tool was not passed, use the Paragraph Tool
      */
-    this.config.initialBlock = this.config.initialBlock || 'paragraph';
+    _.deprecationAssert(Boolean(this.config.initialBlock), 'config.initialBlock', 'config.defaultBlock');
+    this.config.defaultBlock = this.config.defaultBlock || this.config.initialBlock || 'paragraph';
+
 
     /**
      * Height of Editor's bottom area that allows to set focus on the last Block
@@ -170,13 +172,13 @@ export default class Core {
     this.config.minHeight = this.config.minHeight !== undefined ? this.config.minHeight : 300;
 
     /**
-     * Initial block type
+     * Default block type
      * Uses in case when there is no blocks passed
      *
      * @type {{type: (*), data: {text: null}}}
      */
-    const initialBlockData = {
-      type: this.config.initialBlock,
+    const defaultBlockData = {
+      type: this.config.defaultBlock,
       data: {},
     };
 
@@ -196,14 +198,14 @@ export default class Core {
     this.config.onChange = this.config.onChange || ((): void => {});
 
     /**
-     * Initialize Blocks to pass data to the Renderer
+     * Initialize default Block to pass data to the Renderer
      */
     if (_.isEmpty(this.config.data)) {
       this.config.data = {} as OutputData;
-      this.config.data.blocks = [ initialBlockData ];
+      this.config.data.blocks = [ defaultBlockData ];
     } else {
       if (!this.config.data.blocks || this.config.data.blocks.length === 0) {
-        this.config.data.blocks = [ initialBlockData ];
+        this.config.data.blocks = [ defaultBlockData ];
       }
     }
 

src/components/modules/api/blocks.ts

@@ -118,7 +118,7 @@ export default class BlocksAPI extends Module {
 
     /**
      * in case of last block deletion
-     * Insert new initial empty block
+     * Insert the new default empty block
      */
     if (this.Editor.BlockManager.blocks.length === 0) {
       this.Editor.BlockManager.insert();
@@ -172,10 +172,10 @@ export default class BlocksAPI extends Module {
    * @deprecated Use BlockAPI interface to stretch Blocks
    */
   public stretchBlock(index: number, status = true): void {
-    _.log(
-      '`blocks.stretchBlock()` method is deprecated and will be removed in the next major release. ' +
-      'Use BlockAPI interface instead',
-      'warn'
+    _.deprecationAssert(
+      true,
+      'blocks.stretchBlock()',
+      'BlockAPI'
     );
 
     const block = this.Editor.BlockManager.getBlockByIndex(index);
@@ -197,7 +197,7 @@ export default class BlocksAPI extends Module {
    * @param {boolean?} needToFocus - flag to focus inserted Block
    */
   public insert = (
-    type: string = this.config.initialBlock,
+    type: string = this.config.defaultBlock,
     data: BlockToolData = {},
     config: ToolConfig = {},
     index?: number,

src/components/modules/blockEvents.ts

@@ -140,12 +140,12 @@ export default class BlockEvents extends Module {
       return;
     }
 
-    const canOpenToolbox = Tools.isInitial(currentBlock.tool) && currentBlock.isEmpty;
+    const canOpenToolbox = Tools.isDefault(currentBlock.tool) && currentBlock.isEmpty;
     const conversionToolbarOpened = !currentBlock.isEmpty && ConversionToolbar.opened;
     const inlineToolbarOpened = !currentBlock.isEmpty && !SelectionUtils.isCollapsed && InlineToolbar.opened;
 
     /**
-     * For empty Blocks we show Plus button via Toolbox only for initial Blocks
+     * For empty Blocks we show Plus button via Toolbox only for default Blocks
      */
     if (canOpenToolbox) {
       this.activateToolbox();
@@ -209,7 +209,7 @@ export default class BlockEvents extends Module {
 
     const selectionPositionIndex = BlockManager.removeSelectedBlocks();
 
-    Caret.setToBlock(BlockManager.insertInitialBlockAtIndex(selectionPositionIndex, true), Caret.positions.START);
+    Caret.setToBlock(BlockManager.insertDefaultBlockAtIndex(selectionPositionIndex, true), Caret.positions.START);
 
     /** Clear selection */
     BlockSelection.clearSelection(event);
@@ -254,7 +254,7 @@ export default class BlockEvents extends Module {
      * If enter has been pressed at the start of the text, just insert paragraph Block above
      */
     if (this.Editor.Caret.isAtStart && !this.Editor.BlockManager.currentBlock.hasMedia) {
-      this.Editor.BlockManager.insertInitialBlockAtIndex(this.Editor.BlockManager.currentBlockIndex);
+      this.Editor.BlockManager.insertDefaultBlockAtIndex(this.Editor.BlockManager.currentBlockIndex);
     } else {
       /**
        * Split the Current Block into two blocks
@@ -268,7 +268,7 @@ export default class BlockEvents extends Module {
     /**
      * If new Block is empty
      */
-    if (this.Editor.Tools.isInitial(newCurrent.tool) && newCurrent.isEmpty) {
+    if (this.Editor.Tools.isDefault(newCurrent.tool) && newCurrent.isEmpty) {
       /**
        * Show Toolbar
        */

src/components/modules/blockManager.ts

@@ -230,7 +230,7 @@ export default class BlockManager extends Module {
    * Insert new block into _blocks
    *
    * @param {object} options - insert options
-   * @param {string} options.tool - plugin name, by default method inserts initial block type
+   * @param {string} options.tool - plugin name, by default method inserts the default block type
    * @param {object} options.data - plugin data
    * @param {number} options.index - index where to insert new Block
    * @param {boolean} options.needToFocus - flag shows if needed to update current Block index
@@ -239,7 +239,7 @@ export default class BlockManager extends Module {
    * @returns {Block}
    */
   public insert({
-    tool = this.config.initialBlock,
+    tool = this.config.defaultBlock,
     data = {},
     index,
     needToFocus = true,
@@ -283,7 +283,7 @@ export default class BlockManager extends Module {
    * @returns {Block}
    */
   public replace({
-    tool = this.config.initialBlock,
+    tool = this.config.defaultBlock,
     data = {},
   }): Block {
     return this.insert({
@@ -321,7 +321,7 @@ export default class BlockManager extends Module {
   }
 
   /**
-   * Insert new initial block at passed index
+   * Insert new default block at passed index
    *
    * @param {number} index - index where Block should be inserted
    * @param {boolean} needToFocus - if true, updates current Block index
@@ -330,8 +330,8 @@ export default class BlockManager extends Module {
    *
    * @returns {Block} inserted Block
    */
-  public insertInitialBlockAtIndex(index: number, needToFocus = false): Block {
-    const block = this.composeBlock({ tool: this.config.initialBlock });
+  public insertDefaultBlockAtIndex(index: number, needToFocus = false): Block {
+    const block = this.composeBlock({ tool: this.config.defaultBlock });
 
     this._blocks[index] = block;
 
@@ -356,7 +356,7 @@ export default class BlockManager extends Module {
     this.currentBlockIndex = this.blocks.length - 1;
 
     /**
-     * Insert initial typed block
+     * Insert the default typed block
      */
     return this.insert();
   }
@@ -443,7 +443,7 @@ export default class BlockManager extends Module {
 
   /**
    * Attention!
-   * After removing insert new initial typed Block and focus on it
+   * After removing insert the new default typed Block and focus on it
    * Removes all blocks
    */
   public removeAllBlocks(): void {
@@ -649,15 +649,15 @@ export default class BlockManager extends Module {
   /**
    * Clears Editor
    *
-   * @param {boolean} needAddInitialBlock - 1) in internal calls (for example, in api.blocks.render)
-   *                                        we don't need to add empty initial block
+   * @param {boolean} needToAddDefaultBlock - 1) in internal calls (for example, in api.blocks.render)
+   *                                             we don't need to add an empty default block
    *                                        2) in api.blocks.clear we should add empty block
    */
-  public clear(needAddInitialBlock = false): void {
+  public clear(needToAddDefaultBlock = false): void {
     this._blocks.removeAll();
     this.dropPointer();
 
-    if (needAddInitialBlock) {
+    if (needToAddDefaultBlock) {
       this.insert();
     }
 

src/components/modules/blockSelection.ts

@@ -198,7 +198,7 @@ export default class BlockSelection extends Module {
     if (this.anyBlockSelected && isKeyboard && isPrintableKey && !SelectionUtils.isSelectionExists) {
       const indexToInsert = BlockManager.removeSelectedBlocks();
 
-      BlockManager.insertInitialBlockAtIndex(indexToInsert, true);
+      BlockManager.insertDefaultBlockAtIndex(indexToInsert, true);
       Caret.setToBlock(BlockManager.currentBlock);
       _.delay(() => {
         Caret.insertContentAtCaretPosition((reason as KeyboardEvent).key);

src/components/modules/caret.ts

@@ -330,10 +330,10 @@ export default class Caret extends Module {
     }
 
     /**
-     * If last block is empty and it is an initialBlock, set to that.
+     * If last block is empty and it is an defaultBlock, set to that.
      * Otherwise, append new empty block and set to that
      */
-    if (this.Editor.Tools.isInitial(lastBlock.tool) && lastBlock.isEmpty) {
+    if (this.Editor.Tools.isDefault(lastBlock.tool) && lastBlock.isEmpty) {
       this.setToBlock(lastBlock);
     } else {
       const newBlock = this.Editor.BlockManager.insertAtEnd();
@@ -383,15 +383,15 @@ export default class Caret extends Module {
 
     if (!nextBlock && !nextInput) {
       /**
-       * If there is no nextBlock and currentBlock is initial, do not navigate
+       * If there is no nextBlock and currentBlock is default, do not navigate
        */
-      if (Tools.isInitial(currentBlock.tool)) {
+      if (Tools.isDefault(currentBlock.tool)) {
         return false;
       }
 
       /**
-       * If there is no nextBlock, but currentBlock is not initial,
-       * insert new initial block at the end and navigate to it
+       * If there is no nextBlock, but currentBlock is not default,
+       * insert new default block at the end and navigate to it
        */
       nextBlock = BlockManager.insertAtEnd();
     }