|
|
@@ -17,45 +17,82 @@ import viewToPlainText from './utils/viewtoplaintext.js';
|
|
|
|
|
|
import HtmlDataProcessor from '@ckeditor/ckeditor5-engine/src/dataprocessor/htmldataprocessor';
|
|
|
|
|
|
+/* eslint-disable max-len */
|
|
|
/**
|
|
|
- * The clipboard feature. Currently, it's responsible for intercepting the `paste` and `drop` events and
|
|
|
- * passing the pasted content through the clipboard pipeline.
|
|
|
+ * The clipboard feature. Currently, it is responsible for intercepting the `paste` and `drop` events and
|
|
|
+ * passing the pasted content through the clipboard pipeline. It also handles the `cut` and `copy` events
|
|
|
+ * to fill the native clipboard with serialized editor's data.
|
|
|
*
|
|
|
* # Clipboard input pipeline
|
|
|
*
|
|
|
- * The feature creates the clipboard input pipeline which allows processing clipboard content
|
|
|
- * before it gets inserted into the editor. The pipeline consists of two events on which
|
|
|
- * the features can listen in order to modify or totally override the default behavior.
|
|
|
+ * The feature creates the clipboard input pipeline which allows to process clipboard content
|
|
|
+ * before it gets inserted into the editor. The pipeline consists of three events on which
|
|
|
+ * a feature can listen in order to modify or totally override the default behavior.
|
|
|
*
|
|
|
- * ## On {@link module:engine/view/document~Document#event:paste} and {@link module:engine/view/document~Document#event:drop}
|
|
|
+ * ## 1. On {@link module:engine/view/document~Document#event:paste `view.Document#paste`} and {@link module:engine/view/document~Document#event:drop `view.Document#drop`}
|
|
|
*
|
|
|
* The default action is to:
|
|
|
*
|
|
|
* 1. get HTML or plain text from the clipboard,
|
|
|
* 2. prevent the default action of the native `paste` or `drop` event,
|
|
|
- * 3. fire {@link module:engine/view/document~Document#event:clipboardInput} with a
|
|
|
+ * 3. fire {@link module:engine/view/document~Document#event:clipboardInput `view.Document#clipboardInput`} with a
|
|
|
* {@link module:clipboard/datatransfer~DataTransfer `dataTransfer`} property.
|
|
|
- * 4. fire {@link module:clipboard/clipboard~Clipboard#event:inputTransformation} with a `data` containing the clipboard data parsed to
|
|
|
+ * 4. fire {@link module:clipboard/clipboard~Clipboard#event:inputTransformation `view.Document#inputTransformation`}
|
|
|
+ * with a `data` containing the clipboard data parsed to
|
|
|
* a {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
|
|
|
*
|
|
|
- * These action are performed by a low priority listeners, so they can be overridden by a normal ones
|
|
|
+ * These actions are performed by low priority listeners, so they can be overridden by normal ones
|
|
|
* when a deeper change in pasting behavior is needed. For example, a feature which wants to differently read
|
|
|
* data from the clipboard (the {@link module:clipboard/datatransfer~DataTransfer `DataTransfer`}).
|
|
|
* should plug a listener at this stage.
|
|
|
*
|
|
|
- * ## On {@link module:engine/view/document~Document#event:clipboardInput}
|
|
|
+ * ## 2. On {@link module:engine/view/document~Document#event:clipboardInput `view.Document#clipboardInput`}
|
|
|
*
|
|
|
- * This action is performed by a low priority listener, so it can be overridden by a normal one.
|
|
|
+ * This action is performed by a low priority listener, so it can be overridden by a normal one. Typically, you will
|
|
|
+ * want to call {@link module:utils/eventinfo~EventInfo#stop `evt.stop()`} and implement your desired behavior:
|
|
|
+ *
|
|
|
+ * editor.editing.view.document.on( 'clipboardInput', ( evt, data ) => {
|
|
|
+ * const dataTransfer = data.dataTransfer;
|
|
|
+ * const htmlContent = dataTransfer.getData( 'text/html' );
|
|
|
+ * const viewContent = htmlDataProcessor.toView( content );
|
|
|
*
|
|
|
- * At this stage the dataTransfer object can be processed by the features, which want to transform the original dataTransform.
|
|
|
+ * this.fire( 'inputTransformation', { content } );
|
|
|
*
|
|
|
- * this.listenTo( editor.editing.view.document, 'clipboardInput', ( evt, data ) => {
|
|
|
- * const content = customTransform( data.dataTransfer.getData( 'text/html' ) );
|
|
|
- * const transformedContent = transform( content );
|
|
|
- * data.dataTransfer.setData( 'text/html', transformedContent );
|
|
|
+ * view.scrollToTheSelection();
|
|
|
+ * evt.stop();
|
|
|
* } );
|
|
|
*
|
|
|
- * ## On {@link module:clipboard/clipboard~Clipboard#event:inputTransformation}
|
|
|
+ * The above is a very raw implementation of handling incoming HTML. A complete HTML + plain text + quirks handling is implemented
|
|
|
+ * by the [clipboard plugin](https://github.com/ckeditor/ckeditor5-clipboard/blob/master/src/clipboard.js)
|
|
|
+ * and it is not recommended to override it, unless you really know what you do.
|
|
|
+ *
|
|
|
+ * This event is useful, however, if you want to handle other kinds of files and ignore the HTML payload at all:
|
|
|
+ *
|
|
|
+ * editor.editing.view.document.on( 'clipboardInput', ( evt, data ) => {
|
|
|
+ * const dataTransfer = data.dataTransfer;
|
|
|
+ *
|
|
|
+ * if ( !hasOnlyFiles( dataTransfer ) ) {
|
|
|
+ * return;
|
|
|
+ * }
|
|
|
+ *
|
|
|
+ * for ( const file of dataTransfer.files ) {
|
|
|
+ * editor.model.change( writer => {
|
|
|
+ * // Do something with that file...
|
|
|
+ * // For instance, create a widget with a preview of it.
|
|
|
+ * // PS. For that you'll also need to upload that file.
|
|
|
+ * // See the FileRepository class.
|
|
|
+ *
|
|
|
+ * editor.model.insertContent( fileWidget, editor.model.document.selection );
|
|
|
+ * } );
|
|
|
+ *
|
|
|
+ * }
|
|
|
+ *
|
|
|
+ * evt.stop();
|
|
|
+ * } );
|
|
|
+ *
|
|
|
+ * In other cases, when you want to transform the pasted HTML, see the event described below.
|
|
|
+ *
|
|
|
+ * ## 3. On {@link module:clipboard/clipboard~Clipboard#event:inputTransformation `view.Document#inputTransformation`}
|
|
|
*
|
|
|
* The default action is to insert the content (`data.content`, represented by a
|
|
|
* {@link module:engine/view/documentfragment~DocumentFragment}) to an editor if the data is not empty.
|
|
|
@@ -65,7 +102,7 @@ import HtmlDataProcessor from '@ckeditor/ckeditor5-engine/src/dataprocessor/html
|
|
|
* At this stage the pasted content can be processed by the features. E.g. a feature which wants to transform
|
|
|
* a pasted text into a link can be implemented in this way:
|
|
|
*
|
|
|
- * this.listenTo( editor.plugins.get( 'Clipboard' ), 'inputTransformation', ( evt, data ) => {
|
|
|
+ * editor.plugins.get( 'Clipboard' ).on( 'inputTransformation', ( evt, data ) => {
|
|
|
* if ( data.content.childCount == 1 && isUrlText( data.content.getChild( 0 ) ) ) {
|
|
|
* const linkUrl = data.content.getChild( 0 ).data;
|
|
|
*
|
|
|
@@ -84,16 +121,16 @@ import HtmlDataProcessor from '@ckeditor/ckeditor5-engine/src/dataprocessor/html
|
|
|
* The output pipeline is the equivalent of the input pipeline but for the copy and cut operations.
|
|
|
* It allows to process the content which will be then put into the clipboard or to override the whole process.
|
|
|
*
|
|
|
- * ## On {@link module:engine/view/document~Document#event:copy} and {@link module:engine/view/document~Document#event:cut}
|
|
|
+ * ## 1. On {@link module:engine/view/document~Document#event:copy `view.Document#copy`} and {@link module:engine/view/document~Document#event:cut `view.Document#cut`}
|
|
|
*
|
|
|
* The default action is to:
|
|
|
*
|
|
|
* 1. {@link module:engine/model/model~Model#getSelectedContent get selected content} from the editor,
|
|
|
* 2. prevent the default action of the native `copy` or `cut` event,
|
|
|
- * 3. fire {@link module:engine/view/document~Document#event:clipboardOutput} with a clone of the selected content
|
|
|
- * converted to a {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
|
|
|
+ * 3. fire {@link module:engine/view/document~Document#event:clipboardOutput `view.Document#clipboardInput`} with
|
|
|
+ * a clone of the selected content converted to a {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
|
|
|
*
|
|
|
- * ## On {@link module:engine/view/document~Document#event:clipboardOutput}
|
|
|
+ * ## 2. On {@link module:engine/view/document~Document#event:clipboardOutput `view.Document#clipboardOutput`}
|
|
|
*
|
|
|
* The default action is to put the content (`data.content`, represented by a
|
|
|
* {@link module:engine/view/documentfragment~DocumentFragment}) to the clipboard as HTML. In case of the cut operation,
|
|
|
@@ -106,6 +143,8 @@ import HtmlDataProcessor from '@ckeditor/ckeditor5-engine/src/dataprocessor/html
|
|
|
* @extends module:core/plugin~Plugin
|
|
|
*/
|
|
|
export default class Clipboard extends Plugin {
|
|
|
+/* eslint-enable max-len */
|
|
|
+
|
|
|
/**
|
|
|
* @inheritDoc
|
|
|
*/
|