visual-space/visual-editor

Visual-editor-teaser

Visual Editor is a Rich Text editor for Flutter originally forked from Flutter Quill. The editor is built around the powerful Quilljs Delta document format originally developed by QuillJs. Delta documents can be easily converted to JSON, the encoding is easy to read and modify and offers many extensibility options. This document explains the reasons why we forked Quill and the improvements that were made.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/visual-editor-demo.gif

Edit Delta Docs In Dart Server

You can edit delta docs on the server side using DocumentController. This can come in handy for a couple of scenarios:

• SEO - You can get retrieve the plain text of a delta doc and then render it as a plain old html document using whatever server side technology you desire.
• Elastic Search - If you need to write a search feature for a large number of documents, once again, you will need the plain text server side. Again running the visual editor on the server side is super handy.
• Coop Editing - In case you want to implement a master server to compare the edits of multiple users, again you can run doc edits on the dart server itself.

Highlights

Highlight custom regions of text with temporary markers that are sensitive to taps and hovering. Highlights are not stored in the delta document. Useful when you want to temporarily showcase a particular range of text. Check out the highlights docs.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/highlights.gif

Markers

Markers have similar mechanics as highlights but instead of being stored temporarily in the controller they are stored permanently in the document. Markers can be enabled or disabled on demand. Check out the markers docs.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/markers.gif

Markers Attachments

Markers can have attachments assigned to them. Custom data can be stored in the attachments. Visual Editor exposes the necessary hooks to implement markers attachments. You can easily customize all the behaviors/rendering. Check out the markers docs.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/markers-attachments.gif

Quick Menu

A quick menu can be displayed on top of the current text selection, on top of highlights or markers, or any arbitrary region of text. Visual Editor exposes the necessary hooks to implement custom menus. You can easily customize all the behaviors/rendering.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/quick-menu.gif

Jump To Heading

A document index can be displayed. Tapping the headings will scroll the document to the correct position. Visual Editor exposes the necessary hooks to implement custom menus. You can easily customize all the behaviors/rendering.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/headings-index.gif

Headings Validation

Fancy behaviors such as custom validation of heading lengths can be implemented. We extract a list of headings, we check against custom validation rules and we display highlights where we spot problems. This is by no means a standard feature in rich text editors, therefore we expose the hooks needed to implement it. You can easily customize all the behaviors/rendering.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/headings-validation.gif

Custom Embeds

Inside of delta document you can inject any type of custom embed. Custom embeds store the data necessary to init the embed. In order to render custom embeds client apps need to provide the custom embed builders. Visual Editor exposes the necessary hooks to implement custom menus. You can easily customize all the behaviors/rendering. Check out the custom embeds docs.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/custom-embeds.gif

Link Menu

Clicking on a link/text (which is set as a link) opens the link menu, which displays the url of the link, in order to open the link into another tab, beside the URL, there are 3 buttons. One for removing the link, leaving the text as it is without the link attribute. Second the edit link which opens the edit link menu. Third is the copy to clipboard menu.

Planned Features

• Better links editing UI
• Hashtags
• At notation
• Slash commands
• Coop editing
• Math formulas

Getting Started

The current version is getting close to a clean state. Visual Editor will soon be ready to be published in pub.dev without major changes. Until then you can use it by linking directly from Github:

dependencies:
  visual_editor:
    git: https://github.com/visual-space/visual-editor.git

Minimal Example - You will need an editor, a toolbar and a controller to link them together.

final _controller = EditorController();

Column(
  children: [
    EditorToolbar(
      controller: _controller,
    ),
    VisualEditor(
      controller: _controller,
    ),
  ],
)

Make sure you don't create a new EditorController instance on setState(). This mistake degrades performance and you will lose the document's edit history. You can update or change the document directly from the controller.

Saving a Document

final json = jsonEncode(_controller.document.toDelta().toJson());

Retrieving a Document

const blogPost = jsonDecode(response);

final _controller = EditorController(
  document: DocDeltaM.fromJson(blogPost)
);

Empty Document

For empty documents the editor can display a placeholder text. This is an empty document. For convenience you can import and use the EMPTY_DELTA_DOC_JSON constant.

[{"insert":"\n"}] 

Export Delta Or Plain Text

Visual Editor uses [Delta] operations as an internal data format to describe the attributes of each fragment of text.

_controller.document.toDelta();
_controller.document.toPlainText();

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/youtube.jpg Youtube Subscribe to our Visual Coding Youtube channel to learn the skills needed to use and extend Visual Editor. Our episodes go in many topics including Flutter and production ready Software Architecture.

https://github.com/visual-space/visual-editor/blob/develop/example/assets/github/discord.jpg Discord Join us on Visual Editor Discord to get live advice from the maintainers and core users. Our goal is to create a friendly and active support community that shares help and resources.

Demos & Code Samples

In this repository you can also find a demo app with various pages that showcase all sorts of configurations for the editor. One particularly useful page is the "Delta Sandbox" page. In this page you can see side by side a live editor and a json preview panel. This demo will help you to quickly learn how the Delta format works.

• You can start the demo app by running main.dart in Android Studio.
• Soon we will have a website with the same demo pages so you don't have to run the samples locally.

Documentation

For a detailed overview of the public API and the code architecture check out our documentation:

• Editor - The widget that renders the document content as commanded by the EditorController.
• Controller - Controls the editor, and the editor toolbar, exposes useful callbacks.
• Documents - Delta documents are used to store text edits and styling attributes.
• Toolbar - Displays buttons used to edit the styling of the text.
• Document Tree - Documents templates are composed of lines of text and blocks of text.
• Embeds - Visual Editor can display any custom component inside of the documents.
• Cursor - Indicates the position where new characters will be inserted.
• Inputs - Hardware Keyboard and Software keyboard.
• Rules - Rules execute behavior when certain condition are met.
• Selection - Handles the rendering of text selection handles and toolbar.
• Highlights - Renders temporary text markers sensitive to taps.
• Markers - Renders permanent text markers sensitive to taps as part of the delta document.
• Coop - Instructions on how to run Visual Editor in coop mode (WIP).

For Contributors: If you start contributing in the codebase make sure to setup the line char limit to 160 chars. We find the 80 chars default from Flutter way too restrictive.

• Why Fork Quill - Explains the reasons why we forked Quill.
• Changelog - Journal of changes made to the visual editor.
• Architecture Overview - Overview of the editor architecture.
• State Store - State store architecture decisions.
• Migration - A simple guide with instructions to migrate from Flutter Quill.

Who Is Maintaining Visual Editor?

• Visual Space - We are the team behind the Visual Editor fork. We are building a social media platform for engineers and innovators. This platforms makes heavy use of advanced rich text editing features. Many of these features had to be built from scratch in Visual Editor since they are not yet available in the Flutter ecosystem from other providers.

Useful Resources

QuillJs Delta • Designing The Delta Format • Language Tool • Language Server Protocol • Word Processing Terminology 1 • Word Processing Terminology 2 • Flutter custom selection toolbar