Feat: Write a comprehensive WYSIWYG Tutorial for Flutter 📝

[nelsonic]

This is going to be one of our biggest standalone tutorials yet but it needs to be comprehensive because we are going to use what we learn from this immediately in our App. ref: dwyl/app#275

Our WYSIWYG requirements for the App are actually quite basic dwyl/app#275 (comment)
but we need to be able to add our own custom buttons+actions so please have that in mind when researching. 🔍

Todo

• Create a new Flutter App. 🆕
• Research and share the available WISYWIG libraries. 🔍
• Implement the most promising lib that will allow us to meet our objectives:
  • Basics: B, I and U (underline) 📝
  • Upload an in-line an image; ref: https://github.com/dwyl/flutter-image-upload-demo 🖼️
  • Advanced: Create our own Custom Actions/Buttons

The single most important requirement that won't immediately be clear from the the WYSIWIG title
is actually how the data gets transformed when you apply an action. 🪄
See: https://github.com/dwyl/deltamin

The USP of what we are building is to have the full history of every action that is taken
thus having full "undo" capability and "replay-ability".
Therefore we need to not just have a WISYWIG lib, we need one that gives us Operational Transform
So that we can easily store the "story" of what has happened to an item
and can replay it both on the connected devices and to future team members
when they need an answer to the question: "How did we get here?"

Which is why I'm leaning toward: https://github.com/singerdmx/flutter-quill or https://pub.dev/packages/quill_html_editor
which both implement Quill which has Delta.

Yes, I know that YJS is the new "hotness" in this space.
The demos are sick: https://yjs.dev/#demos
But there isn't anything in Dart we can use for our Flutter App right now ...
Given that Delta is just a description language, it should be fairly easy to port to anything else in the future ... 💭
So I don't have any "concerns" with using it for now.

[nelsonic]

@LuchoTurtle as soon as you're done with dwyl/flutter-date-time-tutorial#1 please take a look at this. It's probably more than T1d ... but we really need to time-box the work to not go down too much of a rabbit hole. 🐇

Remember our goal for _this repo is fairly basic: "How add an extensible WYSIWYG editor to a Flutter app".
We don't need to build a full-on Google Docs clone. Just the basics for now so we can ship this in our App. 📱 🙏

[nelsonic]

A good preparation or side-quest for working on this might be to understand the Delta format by taking a look at: dwyl/deltamin#10 💭

[LuchoTurtle]

I'm going to pick up on this now since dwyl/deltamin#10 is already completed.

I've been scouring through the documentation of https://github.com/singerdmx/flutter-quill and inclusively watched all of the videos from https://www.youtube.com/playlist?list=PLbhaS_83B97vONkOAWGJrSXWX58et9zZ2 and I think this is perhaps the best editor we could/should go for given the requirements you've stated.

• it appears to have more support when compared with https://github.com/the-airbender/quill_html_editor.
• it's extendable, so we can add our own custom buttons and add embeds.
• it doesn't appear to support videos just yet (ref: https://youtu.be/x_A7fjxGjtA?t=31), though there seems to be in development, as seen in https://github.com/singerdmx/flutter-quill/blob/master/flutter_quill_extensions/lib/embeds/widgets/video_app.dart They support videos.
• it appears to support the web platform (you need to use a defaultEmbedBuilderWeb embed to make it work - the reason they've decided to make this separate is because the web version entails more dependencies that are not needed in mobile applications).
• we might have to change deltamin a bit, given the attributes that are possible (from https://www.youtube.com/watch?v=r502AfCX-Hw&list=PLbhaS_83B97vONkOAWGJrSXWX58et9zZ2&index=4&ab_channel=XCode and https://www.youtube.com/watch?v=oooJtULKKcc&list=PLbhaS_83B97vONkOAWGJrSXWX58et9zZ2&index=4&ab_channel=XCode). However, as of now, if we stick to the basics, it should be 100% compatible.
• appears to have undo/redo capabilities out-of-the-box (ref: https://github.com/singerdmx/flutter-quill/blob/master/CodeIntroduction.md).
• seems to be easier to test (they have their own utility package 'package:flutter_quill/flutter_quill_test.dart', which https://github.com/the-airbender/quill_html_editor doesn't appear to have).

In light of the above, this is why I believe flutter-quill is probably our best choice. Don't get me wrong, https://github.com/the-airbender/quill_html_editor is also a great choice but flutter-quill appears to have more dev activity and appears easier to test.

I've tried to look for other options other than the two mentioned but they pale in comparison:

• https://github.com/JideGuru/rich_editor, although good, does not support Delta.
• https://github.com/superlistapp/super_editor, an editor made 100% in Dart and appears to have a great reputation regarding their documentation and codebase.. Unfortunately, they do not implement Delta.

Forked version?

https://github.com/visual-space/visual-editor, a forked version of flutter-quill. This one is quite interesting. The reasoning for the owner of the repo to fork the original repo is explicitly stated in https://github.com/visual-space/visual-editor/blob/develop/QUILL_FORK.md.
Having perused the code, it's much better structured and better documented than its counterpart. The only thing that is keeping me from making a final decision between the forked version and the original version is activity.
While flutter-quill had code commits 2 weeks ago, visual-editor had this 4 months ago.

@nelsonic , what do you think it's best? Maybe this repo would be a great opportunity to try both and see how they fare in terms of testing and compatibility with our requirements.

[nelsonic]

@LuchoTurtle agree with trying both if it doesn't add toooo much time.
The visual-editor looks like it has some good added features.
But I'm weary of using something that doesn't appear to have any automated testing ...
https://github.com/visual-space/visual-editor/actions

Still think that flutter-quill has what we need for the foreseeable future.

[LuchoTurtle]

Nice.
Having seen https://github.com/visual-space/visual-editor#custom-embeds, the examples shown seem to work on the web with images. So it's a good sign that I might now have to deal with the frustration that I'm currently having with image embeds in the web with the original repo.

[adrian-moisa]

Hey guys, I'm the lead dev at Visual Editor. If you have any questions feel free to ask. Current status of the project: slight hiatus because we are working on our own startup's go live preparations. The editor is far from dead. We have a lot more work planned ahead. I'd be happy to have more friends join the repo/effort. If you are interested in getting knees deep in the codebase I can provide the support. I've also made extensive effort to document the Quill codebase. The md's are not complete but it's a far cry from the Quill repo. I've got a discord server where I keep in touch with other followers of the VE project. You'll find the link on our github readme. And I say we because my team has 5 members, all familiar and able to make contributions in Visual Editor. Btw, where can I learn more about your project?

Edit Managed to find the roadmap. Nice work there! https://github.com/dwyl/product-roadmap#why-are-we-building-an-app - You'll be happy to learn that on the VE roadmap we have hashtags, handles, slash commands and typing shortcuts. I guess you'll find them super useful. Also VE has Highlights and Markers. These were added after forking from Quill. You'll need them as well. Plus we have a lot of demo pages to showcase all the features.

[nelsonic]

@LuchoTurtle looks like you've hit a brick wall when it comes to testing with flutter-quill 😢
Please record a quick screencast (30sec - 1min) of the problem you are facing (what you showed me on standup)
and share it on the issue you opened: singerdmx/flutter-quill#1389
Then leave a quick paragraph in the README.md describing why it's difficult to improve test coverage and linking to the issue. Then assign the PR to me and we will merge it ASAP.
Then get straight to work on replacing flutter-quill with visual-editor: #3
Start by adding CI to the repo: visual-space/visual-editor#227
that will give you a chance to familiarise yourself with the codebase and open any follow-up issues.
It should be a straightforward replacement given that one is a fork of the other ...
But if it isn't, please comment liberally on the issue: #3

For the avoidance of any further doubt: We definitely don't want to embed images in an item ever.
We want to always upload to a image hosting service (currently S3) and then link that image using markdown:

![porter-200](https://factorymethod.uk/image.png?mode=fill&width=200&height=200&origin=https://world-celebs.com/public/media/resize/800x-/2019/8/5/porter-robinson-3.jpg)

Embedding images means the data of the image is stored inside the PostgreSQL database.
That costs us 10x* more cash and clogs up the DB making it slower with exactly zero advantage.

Note: Yes, I know that it makes it more "offline friendly" to embed the image. But the cost does not justify that benefit.
Please just follow GitHub example and upload the image and link to the ![img](url) in the body.

[adrian-moisa]

This should help: Migration - A simple guide with instructions to migrate from Flutter Quill. Maybe it's slightly out of date. Overall the process should not be headache inducing.