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: ***@***.***>

[CatKevin]

Thank you very much for your reply!
However, I only see string2string and delta2delta related conversions. But we may copy a string with emojis somewhere (not in quill), such as "Hello[smile]Mike![cheer][cheer][cheer]", and users can copy and paste it on any APP without exposing the emoji protocol in this APP. After we paste this string in quill, we actually hope to parse the strings "[smile]" and "[cheer]" into corresponding emojis and display them in quill.
Therefore, I think we may also need a method to convert strings to Delta. Do you think so?

[EchoEllet]

You can use onClipboardPaste for custom implementation, though you're right, I don't see a strong reason why onPlainTextPaste shouldn't expect Delta? instead of String?.

  /// Callback triggered when pasting plain text into the editor.
  ///
-  /// Returns modified text to override the pasted content, or `null` to use the default.
+  /// Returns a [Delta] to override the pasted content, or `null` to use the default.
  @experimental
-  final Future<String?> Function(String plainText)? onPlainTextPaste;
+  final Future<Delta?> Function(String plainText)? onPlainTextPaste;

The API design needs more consideration.

[EchoEllet]

The Delta data structure is a common data structure in flutter_quill. No matter what kind of data it is,

I do agree with that as stated in my previous comment.

The onClipboardPaste function will change the data in the user's clipboard

The behavior slightly changed in v11 (see breaking changes), it allows to override the default with a custom implementation, it can be used to check if the clipboard as plain text, process the paste and then return true (see example code). I do plan on changing it to return Delta instead.

[EchoEllet]

The issue has already been resolved in the pre-release. See this comment.

The v11 is already stable. We didn't publish it as stable since we have one breaking change, which is removing the magnifier feature (see #2413 for more details).

[xalanq]

Thank you for your reply. But I meant the following one

-  final Future<String?> Function(String plainText)? onPlainTextPaste;
+  final Future<Delta?> Function(String plainText)? onPlainTextPaste;

[EchoEllet]

Function(String plainText)? onPlainTextPaste;

We might need to change plainText to Delta too since the QuillController has an internal clipboard (not the same as the system clipboard) that contains the copied content as rich text. If we always provide plain text, the text attributes might be lost if the user copies rich text inside the editor and then pastes it.

• Changing it to Delta makes it no longer plain text, maybe onTextPaste would be a better name, or perhaps a second callback?
• Currently the onDeltaPaste is used only for the external rich text paste, however using it for the internal rich text paste is also valid.

Note

• The internal rich text paste occurs when the user copies and pastes content inside the editor from the internal clipboard.
• The external rich text paste occurs when content is pasted from other apps while preserving styles using the system clipboard.

Here is an example after introducing the change:

onPlainTextPaste: (String plainText) async {
          return Delta()
            ..insert('The plain text from the clipboard', {'bold': true})
            ..insert(':\n')
            ..insert(plainText);
        },

IssueAfterUnmergedChange.mov

[xalanq]

Hi, thx for your reply! But the latest code is still the old version

flutter-quill/lib/src/controller/clipboard/quill_clipboard_config.dart

Line 79 in 6640579

final Future<String?> Function(String plainText)? onPlainTextPaste;

Is that change still in your local repo? When will it be merged into the master? THX!

[mtallenca]

I'm only interested in altering pasted text when it's coming from the system clipboard (so I can ensure it's only using attributes that the current editor config has). I would like anything copied from the editor then pasted back into the editor to remain unmodified. Need a bool to indicate system clipboard?

[EchoEllet]

Is that change still in your local repo? When will it be merged into the master?

Yes, it needs more consideration before merging.

I'm only interested in altering pasted text

You're right. That is a separate topic and should be in #2156.

I would like anything copied from the editor then pasted back into the editor to remain unmodified.

Currently, the onDeltaPaste is only used when pasting a Delta from the system clipboard, but that's subject to change.
The API is not final.

The onDeltaPaste is generic and might not be very clear.

I'm considering onExternalRichTextPaste and onInternalRichTextPaste to separate them. The external paste is when it's coming from the system clipboard.

Need a bool to indicate system clipboard?

Having onRichTextPaste with a boolean is also valid.