Migration Guide: Super Editor = 0.2.x to Super Editor 0.3.0

super_editor v0.3.0 introduces major breaking changes so that the logical editor forces all changes through a single pipeline, allowing for undo/redo, tagging, content conversions, and more.

The following describes how to migrate from super_editor v0.2.x to v0.3.0.

From DocumentEditor to Editor

At a high level, any place where a DocumentEditor was used in v0.2.x, a new Editor object should be used in v0.3.0.

Configuring a SuperEditor

In v0.2.x a SuperEditor only required a DocumentEditor:

void initState() {
  super.initState();
  _myDocument = createDocument();
  _myEditor = DocumentEditor(document: _myDocument);
}

Widget build(BuildContext context) {
  return SuperEditor(
    editor: _myEditor,
  );
}

In v0.3.0 a SuperEditor requires an Editor, a Document, and a DocumentComposer.

Creating a new Editor requires a MutableDocument, and a MutableDocumentComposer.

The Editor has a lot of possible configuration for the typical use-case. Therefore, a top-level method is made available to create a typical Editor.

void initState() {
  super.initState();
  _myDocument = createDocument();
  _myComposer = MutableDocumentComposer();
  _myEditor = createDefaultDocumentEditor(document: _myDocument, composer: _myComposer);
}

Widget build(BuildContext context) {
  return SuperEditor(
    editor: _myEditor,
    document: _myDocument,
    composer: _myComposer,
  );
}

Commands

The concept of editor commands existed before v0.3.0, but in v0.2.x those commands could mutate anything at any time. The primary change in v0.3.0 is that all changes need to happen within a single pipeline.

A command in v0.2.x would look something like:

class MyCommand implements EditorCommand {
  MyCommand({
    // args
  });

  // properties

  @override
  void execute(Document document, DocumentEditorTransaction transaction) {
    // command behavior here
  }
}

Also, some commands in v0.2.x might be implemented in a functional way like this:

editor.executeCommand(
  EditorCommandFunction(
    (doc, transaction) {
      // command behavior here
    },
  ),
);

In v0.3.0, a change should typically include an EditRequest and an EditCommand. There's no longer any support for an functional command.

A request/command pair in v0.3.0 should look something like this:

class MyRequest implements EditRequest {
  MyRequest({
    // args
  });

  // properties
}

class MyCommand implements EditCommand {
  MyCommand({
    // args
  });

  // properties

  @override
  void execute(EditContext context, CommandExecutor executor) {
    // Most commands will require access to the mutable version of the Document, and the
    // mutable version of the DocumentComposer.
    //
    // You can add your own `Editable`s to the `Editor`'s `EditContext` and access them
    // just like this.
    final document = context.find<MutableDocument>(Editor.documentKey);
    final composer = context.find<MutableComposer>(Editor.composerKey);
  }
}