How do I?

In this page we answer a list of commonly asked things

How do I watch for changes to the editor?#

Create a plugin that watches changes to the editor, see exporting data for an example.

How do I handle editor's DOM events ?#

Create a plugin which listens to DOM events as show below:

new Plugin({
  key: new PluginKey('myDropPlugin'),
  props: {
    handleDOMEvents: {
      drop(view, event) {
        // your logic
      },
    },
  },
});

💡 See Prosemirror.EditorProps for the API.

How do I add a keyboard shortcut ?#

📖 See Keybindings Guide

How do I execute a command ?#

If you are using the vanilla setup, you can get access to view from the editor instance. For example

const editor =  new BangleEditor({ ... })
const view = editor.view
const state = view.state
const dispatch = view.dispatch

// dry run a command
const success = toggleBold()(view.state);
// execute the command
toggleBold()(view.state, view.dispatch, view);

In a React setup you can get the view from the hook useEditorViewContext for components rendered inside the <BangleEditor />. For components outside <BangleEditor />, save the editor in your applications state management for retrieval and access. Don't forget to clean it up when your editor is destroyed.

How do I get access to the `view`, `state`, `dispatch` for a command?#

See ### How do I execute a command ? above.

How do I get access to Prosemirror schema ?#

If you are using specs:[ ... ] notation, switch to using SpecRegistry.

const specRegistry = new SpecRegistry([]);
const schema = specRegistry.schema;

How do I access `prosemirror-*` module ?#

You can either npm install them:

npm i -S prosemirror-view prosemirror-state

or use the ones provided in bangle core which follow the path of @bangle.dev/core/prosemirror/<name_of_module>:

import { EditorView } from '@bangle.dev/core/prosemirror/view';
import { TextSelection } from '@bangle.dev/core/prosemirror/state';
import { Slice } from '@bangle.dev/core/prosemirror/model';

I recommend the later approach to avoid problems with different versions of Prosemirror existing in your application.

How do I change the selection ?#

First, you will need to figure out whether you want a TextSelection (majority of the cases) or a NodeSelection. Below is an example of setting selection to the end:

const setSelectionAtEnd = (state, dispatch) => {
  const textSelection = TextSelection.create(
    state.doc,
    state.doc.content.size - 1,
  );
  // doing this creates a new Transaction
  const tr = state.tr;
  // this convention allows for dry running of a command
  if (dispatch) {
    dispatch(tr.setSelection(textSelection));
  }
  // return the success of the command
  return true;
};

How do I programmatically update the doc content?#

This is a pretty heavy question as this requires Prosemirror knowledge of dealing with transactions. To get started read up on

Read the Prosemirror guide at least 3 times.
Browse the source code of some of your favourite components to get a hang of carrying out transactions.
Checkout prosemirror-utils for more code examples.

How do I create a new paragraph node ?#

Below is an example of how you can create a new paragraph node:

const { doc, schema, tr } = view.state;
const type = schema.nodes.paragraph;
// Insert a paragraph node at the end of document.
const transaction = tr.insert(doc.content.size, type.create('Hello'));
// Commit it.
view.dispatch(transaction);