# ProseMirror Plugins

The [Kendo UI for Angular Editor](https://www.telerik.com/kendo-angular-ui/components/editor) component is based on the [ProseMirror library](https://prosemirror.net/). ProseMirror provides a set of tools and concepts for building rich text editors, using user interface inspired by what-you-see-is-what-you-get.

## Concepts

The ProseMirror [plugin system](https://prosemirror.net/docs/ref/#state.Plugin_System) enables developers to create custom tools and functionality. One of the main building blocks of each editor is its [`EditorState`](https://prosemirror.net/docs/ref/#state) object. The state is created through a static [`create`](https://prosemirror.net/docs/ref/#state.EditorState^create) method which takes a configuration object, containing the starting document node, the [schema](https://prosemirror.net/docs/ref/#model.Schema), and a collection of [plugins](https://prosemirror.net/docs/ref/#state.Plugin) which will be active in this state.

Plugins are instances of the [`Plugin` class](https://prosemirror.net/docs/ref/#state.Plugin) and can model a wide variety of features. The basic ones only add some [properties](https://prosemirror.net/docs/ref/#view.EditorProps) to the editor view to respond to certain events, for example. More complicated features may add a new state to the editor and update it based on [transactions](https://prosemirror.net/docs/ref/#state.Transaction).

For further details about the ProseMirror plugins, refer to the [this ProseMirror guide](https://prosemirror.net/docs/guide/#state.plugins).

## Custom Plugins

Following the ProseMirror concepts, the Kendo UI for Angular Editor provides a set of built-in plugins, enabling various functionalities, such as history, key bindings, a placeholder, and also allows you to extend and customize its functionality and features by using custom plugins.

To provide custom plugins, bind the Editor [`plugins`](https://www.telerik.com/kendo-angular-ui/components/editor/api/editorcomponent#plugins) option to a callback which exposes the default set of plugins, and returns a new `Plugin` array.

```ts
    @Component({
    selector: 'my-app',
    template: `
        <kendo-editor [plugins]="myPlugins"></kendo-editor>
    `
    export class AppComponent {
        public myPlugins = (args: Plugin[]) => [...args, this.myPlugin];

        private myPlugin = new Plugin({
            // TODO: define the custom Plugin configuration.
        });
    }
```

> You can set custom plugins only once—upon the initialization of the Editor component. Further changes will not be reflected and the Editor will continue to use the initially provided plugins.

### Paragraph Marker Tool

To create a custom tool that toggles paragraph markers in the Editor, use:

* The [Decoration](https://prosemirror.net/docs/ref/#view.Decoration) plugin of the ProseMirror.
* Custom CSS styles for the marker.

The following example demonstrates how to display a paragraph marker by utilizing the `Decoration` plugin.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/editor/plugins/paragraph-marker/source.txt)

### Popup Tools

You can implement a plugin that shows a popup which contains additional tools or supplementary information based on the user selection.

The following example demonstrates how to show a search icon above the Editor selection and perform a Google search with the selected text when clicking the icon.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/editor/plugins/popup-tool/source.txt)

### Input Rules

Input rules provide an option for modifying the input of the user on the fly and represent pairs of matches and corresponding actions. When the user input matches an input rule, the typed text is transformed based on the action of that rule.

For more details about the ProseMirror [`InputRule` class](https://prosemirror.net/docs/ref/#inputrules.InputRule) and its properties and utility functions, refer to the [official ProseMirror documentation](https://prosemirror.net/docs/).

The following example demonstrates how to implement input rules which transform markdown statements, followed by space ("␣"), into their respective HTML alternatives. For example, typing '##' and pressing space will yield an `<h2>` tag in the Editor value.

The example uses the following input rules:

* Converts "- " or "+ " to a bullet list.
* Converts "1. " or another number to an ordered list.
* Converts "# ", "## ", "### ", "#### ", "##### ", "###### " into heading 1, 2, 3, 4, 5, and 6, according to the "#" characters count.
* Converts three backticks ("\`\`\`") to a code block.
* Converts double dashes to an emdash ("—").
* Converts three dots to an ellipsis ("...")character.
* Converts an URl to a link.
* Converts '!image\[https\://image-path/something.png]' to image.
* Converts '> ' into a blockquote.

The following example demonstrates the input rules listed above, which automatically transform Markdown-style syntax into HTML as the user types.

[Demo Source](https://demos.telerik.com/kendo-angular-ui/demos/editor/plugins/input-rules/source.txt)

## Suggested Links

* [API Index of the Editor](https://www.telerik.com/kendo-angular-ui/components/editor/api)
* [API Reference of the EditorComponent](https://www.telerik.com/kendo-angular-ui/components/editor/api/editorcomponent)
* [ProseMirror Documentation](https://prosemirror.net/docs/)
* [ProseMirror Plugins Guide](https://prosemirror.net/docs/guide/#state.plugins)
* [ProseMirror Plugin class](https://prosemirror.net/docs/ref/#state.Plugin)
* [Angular Editor](https://www.telerik.com/kendo-angular-ui/editor)