Dojo NG is being built in the open, one section at a time — follow along on Heptapod.

Playground Docs Components Migrate Blog Community Source GitHub
★ GitHub ★ Heptapod Get started

API REFERENCE · RICH TEXT PLUGINS

@dojo-ng/rich-text-slash

A / command menu for <dj-rich-text>: type / to insert headings, lists, tables, images, and more.

Try it in the playground

@dojo-ng/rich-text-slash · v0.1.1 · A plugin for <dj-rich-text>, not a custom element

npm install @dojo-ng/rich-text-slash

Compose the slash plugin with the default set and the node-contributing plugins whose commands you want in the menu. Type / to open it; /h filters to headings.

<dj-rich-text id="editor" label="Article"></dj-rich-text>
<script type="module">
  import "@dojo-ng/rich-text";
  import { defaultPlugins } from "@dojo-ng/rich-text";
  import { headingsPlugin } from "@dojo-ng/rich-text-headings";
  import { listsPlugin } from "@dojo-ng/rich-text-lists";
  import { imagePlugin } from "@dojo-ng/rich-text-image";
  import { slashPlugin } from "@dojo-ng/rich-text-slash";
  document.getElementById("editor").plugins = [...defaultPlugins, headingsPlugin, listsPlugin, imagePlugin, slashPlugin];
</script>

Using it

  • Typing / at the start of a block or after a space opens a menu at the caret. ArrowUp and ArrowDown move the highlight; Enter, Tab, or a click runs the item; Escape closes the menu.
  • Choosing an item removes the /query text, then runs the item.
  • A query that matches nothing hides the menu.

What is in the menu

  • The items come from every loaded plugin's inserts, plus any extra you pass. Headings adds Paragraph, Heading 1 to 3, and Quote; lists adds the three list types; image adds Image; table adds Table.
  • The menu never opens when no plugin adds an item.
  • To add actions from your own plugin, give it an inserts array (or a function (ctx) => items) of { id, label, keywords?, run(ctx) }.

Setup

  • Exports slashPlugin, createSlashPlugin({ extra? }), DEFAULT_SLASH_TRIGGER, and the aggregateInserts and filterInserts helpers.
  • Setting plugins replaces the default set, so spread ...defaultPlugins to keep bold, italic, underline, undo, and redo.

Examples

Add a custom command

Pass extra items to createSlashPlugin. Each item is { id, label, keywords?, run(ctx) }; run is called outside any editor update, so it can dispatch commands or open UI.

<dj-rich-text id="editor" label="Article"></dj-rich-text>
<script type="module">
  import "@dojo-ng/rich-text";
  import { defaultPlugins } from "@dojo-ng/rich-text";
  import { createSlashPlugin } from "@dojo-ng/rich-text-slash";
  const slash = createSlashPlugin({
    extra: [{ id: "date", label: "Today's date", keywords: ["date", "now"], run: (ctx) => ctx.editor.update(() => {}) }],
  });
  document.getElementById("editor").plugins = [...defaultPlugins, slash];
</script>

Functions

aggregateInserts

function aggregateInserts(ctx: RichTextContext, extra?: RichTextInsertItem[]): RichTextInsertItem[];

createSlashPlugin

function createSlashPlugin(options?: SlashPluginOptions): RichTextPlugin;

filterInserts

function filterInserts(items: RichTextInsertItem[], query: string): RichTextInsertItem[];

Values

DEFAULT_SLASH_TRIGGER

const DEFAULT_SLASH_TRIGGER: RegExp;

slashPlugin

const slashPlugin: RichTextPlugin;

Types

SlashPluginOptions

interface SlashPluginOptions {
  extra?: RichTextInsertItem[];
}