Blocks

Blocks are the foundation of working with the editor. You can configure them according to your requirements, extend their functionality, or create your own blocks using the existing model.

Basic Usage

Connect and use blocks in the editor configuration.

import 'texditor/styles/theme.css';
import Texditor from 'texditor';
import {
  Gallery,
  Files,
  H2,
  List,
  Paragraph
} from 'texditor/entities/blocks';

const editor = new Texditor({
  // HTML element identifier
  handle: 'texditor',
  // List of block models
  blocks: [
    Paragraph,
    List,

    // Configure a simple block
    H2.setup({
      // Placeholder (if data is not filled)
      placeholder: 'My Heading',
      // Basic sanitization parameters
      sanitizerConfig: {
        elements: ['a', 'sup', 'sub']
        // ...
      }
      // ... other parameters from the main and base model
    }),

    /*
      Example of the Gallery block, which has
      its own configuration parameters.
    */
    Gallery.setup({
      mimeTypes: [
        "image/png",
        "image/jpeg",
        "video/mp4",
        "image/webp"
      ],
      multiple: true,
      uploadLabelMessage: "Upload your files in .png, .jpg, .mp4, or .gif formats",
      showOnlyWhenEmpty: true,
      stylesLtr: "left",
      styles: [],
      defaultStyle: 'slider',
      ajaxConfig: {
        url: "https://texditor.priveted.com/api/upload",
        options: {
          data: {
            hello: 33
          }
        }
      }
    }),
    
    /*
      Although this element will function as a block,
      uploading files will require configuration similar to that
      used in the Gallery block.
    */
    Files,

    // ... any custom block that matches the BlockModel model.
  ]
});

To configure each block in more detail and learn about its specifics, it is recommended to refer to the API.

Extending and Creating Custom Blocks

Blocks have a high degree of extensibility and can utilize all the capabilities of the editor's API. They are built on the base block model, which provides various methods for managing the DOM tree.

Extending a Block

We took the Paragraph block as a basis, which does not require major changes in configuration and has a structure based on the base block model BlockModel. Then we adapted it to our needs.

Javascript

import { BlockElement } from "texditor";
import { Paragraph } from "texditor/entities/blocks";

export class CustomParagraph extends Paragraph {
  // Using standard configuration
  configure() {
    // Be sure to base it on the parent configuration
    const config = super.configure();
    config.placeholder = 'My Paragraph'

    return config;
  }

  // Executes after mounting the block element in the DOM tree
  onMount(el) {
    this.myCustomMethod();
  }

  // This is just an example of how it works (do not do this in real projects)
  myCustomMethod() {
    const { blockManager, events } = this.editor;
    const blockElement = this.getElement();

    // Get the current block element
    console.log(blockElement);

    // Test example of removing a block
    blockManager.removeBlock(2);

    // Subscribe to an event
    events.on('keydown', (evt) => {
      console.log(evt);
    });
  }
}

Typescript

import {
  BlockElement,
  type BlockModelConfig,
  type TexditorEvent
} from "texditor";
import { Paragraph } from "texditor/entities/blocks";

export class CustomParagraph extends Paragraph {
  // Using standard configuration
  protected configure(): Partial<BlockModelConfig> {
    // Be sure to base it on the parent configuration
    const config = super.configure();
    config.placeholder = 'My Paragraph'

    return config;
  }

  // Executes after mounting the block element in the DOM tree
  protected onMount(_el: BlockElement): void {
    this.myCustomMethod();
  }

  // This is just an example of how it works (do not do this in real projects)
  private myCustomMethod(): void {
    const { blockManager, events } = this.editor;
    const blockElement = this.getElement();

    // Get the current block element
    console.log(blockElement);

    // Test example of removing a block
    blockManager.removeBlock(2);

    // Subscribe to an event
    events.on('keydown', (evt: TexditorEvent) => {
      console.log(evt);
    });
  }
}

Creating a Block

To create a block, you need to extend the BlockModel class. For the block to function correctly, you need to implement the main configure method.

Javascript

import { BlockModel } from 'texditor/core/models';

export class CustomListBlock extends BlockModel {
  // Define the main block configuration
  configure() {
    return {
      name: 'ul',
      translation: 'list',
      groupCode: 'list',
      tagName: 'ul',
      itemTagName: 'li',
      itemName: 'li',
      itemClassName: 'tex-list-item',
      itemBodyClassName: 'tex-list-item-body',
      autoParse: true,
      autoMerge: true,
      icon: { raw: '<svg>...</svg>' },
      editable: false,
      editableItems: true,
      visibleTools: true,
      sanitizer: true,
      normalize: true,
      convertible: true,
      className: 'tex-list',
      sortableItems: true,
      sanitizerConfig: {
        elements: ['b', 'a', 'i', 's', 'u', 'sup', 'sub', 'mark', 'code'],
        attributes: {
          a: ['href', 'target'],
        },
        protocols: {
          a: {
            href: ['https', 'ftp', 'http', 'mailto'],
          },
        },
      },
    };
  }

  // Further use all the capabilities of the block model...
}

Typescript

import { BlockModel } from 'texditor/core/models';
import { type BlockModelConfig } from "texditor";

export class CustomListBlock extends BlockModel {
  // Define the main block configuration
  protected configure(): Partial<BlockModelConfig> {
    return {
      name: 'ul',
      translation: 'list',
      groupCode: 'list',
      tagName: 'ul',
      itemTagName: 'li',
      itemName: 'li',
      itemClassName: 'tex-list-item',
      itemBodyClassName: 'tex-list-item-body',
      autoParse: true,
      autoMerge: true,
      icon: { raw: '<svg>...</svg>' },
      editable: false,
      editableItems: true,
      visibleTools: true,
      sanitizer: true,
      normalize: true,
      convertible: true,
      className: 'tex-list',
      sortableItems: true,
      sanitizerConfig: {
        elements: ['b', 'a', 'i', 's', 'u', 'sup', 'sub', 'mark', 'code'],
        attributes: {
          a: ['href', 'target'],
        },
        protocols: {
          a: {
            href: ['https', 'ftp', 'http', 'mailto'],
          },
        },
      },
    };
  }

  // Further use all the capabilities of the block model...
}

Adding Custom Blocks to the Editor

Now we can add new blocks to the list of models, and they will work correctly.

import CustomParagraph from './blocks/CustomParagraph';
import CustomListBlock from './blocks/CustomListBlock';

const texditor = new Texditor({
  handle: 'texditor',
  blocks: [
    CustomParagraph,
    CustomListBlock
  ]
})