Add paste options (bool plainTextOnly and a callback to view/modify a delta prior to pasting)

[mtallenca]

Is there an existing issue for this?

• I have searched the existing issues

Use case

Problem: On iOS when pasting HTML, it is converted into a quill delta object and then performs a controller replaceText(). The conversion assumes the full functionality of the editor and keeps all converted attributes. If the QuillEditor implementation isn't using some of the Quill features, it can be inserted into the document and not be editable. i.e. fonts, colors, images, etc.

I propose adding two changes to the controller.

1. Whenever HTML is pasted, pass the converted delta object to a callback that would allow the delta to be edited. The callback would return the edited delta object and that would be used with the replaceText controller method.

2. Provide a bool that would convert any pasted HTML into plain text prior to calling replaceText().

Alternative solutions: Currently in the onReplaceText controller callback, I'm examining the delta, removing any unsupported attributes, and then calling a 2nd replace text with the modified delta.

Proposal

quill_controller_rich_paste.dart

final htmlText = await getHTML();
    if (htmlText != null) {
      final htmlBody = html_parser.parse(htmlText).body?.outerHtml;
      // ignore: deprecated_member_use_from_same_package
      var deltaFromClipboard = DeltaX.fromHtml(htmlBody ?? htmlText);
      
      //Add an optional callback...
      if (verifyPasteDelta != null) {
          deltaFromClipboard = verifyPasteDelta!(deltaFromClipboard);
       }
       // end of add

      _pasteUsingDelta(deltaFromClipboard);

      return true;
    }

[EchoEllet]

This was originally discussed at flutter_quill_delta_from_html #12.

This issue will be addressed in #2338 (release/v11) as there are related changes in there (see migration guide for list of breaking changes).

I'm thinking about moving the QuillControllerConfig.onClipboardPaste to a separate config class related to the clipboard (QuillClipboardConfig) before addressing this issue.

What to address:

• Encapsulating clipboard-related properties such as onClipboardPaste, onPasteDelta (not added yet, same as the suggested verifyPasteDelta), and enableRichTextPaste (not added yet) in one config class (QuillClipboardConfig).
• Whether the QuillClipboardConfig should be in the controller's config (QuillControllerConfig) instead of the editor's config (QuillEditorConfig).
• Based on the current state of the rich text paste, should we disable it by default and provide docs to enable it? In either case, the developer has onClipboardPaste to control the implementation.
• Verify the functionality of the callback onClipboardPaste, see if we should change how it works, or provide some parameters, any possible issues, to avoid possible breaking changes after the release of 11.0.0.

Any suggestions?

[mtallenca]

• Since there are multiple clipboard config options, makes sense to group them into their own config class
• I think clipboard control belongs wherever onReplaceText lives - currently the controller
• I'm not sure how quickly apps update to the latest quill. Whenever possible our team updates quickly. The enabling of rich text paste while not a breaking change, probably should have been classified as one. If most devs aren't already using the latest, it would make sense to disable by default - or make it required.
• For the onClipboardPaste, I'm thinking the clipboard retrieval and processing is beyond most use cases when working with the editor. In the 1st example add a comment // Do something with the clipboardData before the return true i.e. onReplaceText. Maybe flip the order of the examples b/c the difficulty of writing a custom handler for all types of clipboard data is non trivial.
• Maybe change onPasteDelta to onPaste(Object? deltaOrString) so any type of paste can be intercepted / modified. If this was the case, I'm guessing onClipboardPaste would not be used very often if at all

[EchoEllet]

• In the 1st example add a comment // Do something with the clipboardData before the return true

The ClipboardData is a Flutter API that only supports plain text, in this example, it was used to check if the clipboard has plain text and then remove the plain text from the system clipboard to disable plain text pasting. Not a very useful example though.

The enabling of rich text paste while not a breaking change, probably should have been classified as one

I agree, even though I introduced it in 9.0.0 it was buggy at the time, and didn't mention this as a breaking change in CHANGELOG.md.

Maybe change onPasteDelta to onPaste(Object? deltaOrString) so any type of paste can be intercepted / modified. If this was the case

How about adding both onPasteDelta and onPastePlainText for type safety (this name suggestion is not final), it's also a bit more clear.

Object? deltaOrString

It can be an image.

I'm thinking about moving onImagePaste and onGifPaste from the editor's config to the QuillClipboardConfig since v11 is still published as pre-release (dev).

Since the clipboardPaste method is in the controller and pasteText (in QuillRawEditorState) still uses those callbacks.

[EchoEllet]

This might be a good feature (#2354) to add or at least provide a way to customize the copy/cut behavior.

[EchoEllet]

Whenever HTML is pasted, pass the converted delta object to a callback that would allow the delta to be edited. The callback would return the edited delta object and that would be used

Added the onDeltaPaste callback.

To try the latest pre-release version (#2338):

dependencies:
  flutter_quill: ^11.0.0-dev.6

See the migration guide.

Use the QuillClipboardConfig:

QuillController.basic(
  config: QuillControllerConfig(
    clipboardConfig: QuillClipboardConfig(
      onDeltaPaste: (delta) async {
        // TODO: Your custom implementation or return the Delta directly
        return delta;
      },
      onPlainTextPaste: (plainText) async {
        // TODO: Your custom implementation or return the plain text directly
        return plainText;
      },
     enableExternalRichPaste: false, // Currently default to true
    ),
  ),
);

[EchoEllet]

@mtallenca Do the parameters onDeltaPaste, onPlainTextPaste, and enableExternalRichPaste fix the issue?

What is missing is Paste as plain text (for the end-user) in the context menu which is supported by default on native Android, we can add it on all platforms or Android only, it's similar to native Android though not the same.

[mtallenca]

Yes, having these will fix the issue

…

On Mon, Nov 11, 2024, 1:22 AM Ellet ***@***.***> wrote: @mtallenca <https://github.com/mtallenca> Do the parameters onDeltaPaste, onPlainTextPaste, and enableExternalRichPaste fix the issue? What is missing is Paste as plain text (for the end-user) in the context menu which is supported by default on native Android, we can add it on all platforms or Android only, it's similar to native Android though not the same. — Reply to this email directly, view it on GitHub <#2350 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAXMGLNDN5OVAD7MXNZXQFL2ABZNTAVCNFSM6AAAAABRHUH7DSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDINRXGYZTMMJQHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>