Explorar el Código

Docs: Improved insertContent() documentation. Step 1.

Piotrek Koszuliński hace 7 años
padre
commit
cf9e220499
Se han modificado 1 ficheros con 59 adiciones y 0 borrados
  1. 59 0
      packages/ckeditor5-engine/src/model/model.js

+ 59 - 0
packages/ckeditor5-engine/src/model/model.js

@@ -220,6 +220,65 @@ export default class Model {
 	 * Inserts content into the editor (specified selection) as one would expect the paste
 	 * functionality to work.
 	 *
+	 * This is a high-level method. It takes the {@link #schema schema} into consideration when inserting
+	 * the content, clears the given selection's content before inserting nodes and moves the selection
+	 * to its target position at the end of the process.
+	 * It can split elements, merge them, wrap bare text nodes in paragraphs, etc. – just like the
+	 * pasting feature should do.
+	 *
+	 * For lower-level methods see {@link module:engine/model/writer~Writer `Writer`}.
+	 *
+	 * This method, unlike {@link module:engine/model/writer~Writer `Writer`}'s methods, does not have to be used
+	 * inside a {@link #change `change()` block}.
+	 *
+	 * # Examples
+	 *
+	 * Using `insertContent()` with a manually created model structure:
+	 *
+	 *		const docFrag = editor.model.change( writer => {
+	 *			const p1 = writer.createElement( 'paragraph' );
+	 *			const p2 = writer.createElement( 'paragraph' );
+	 *			const blockQuote = writer.createElement( 'blockQuote' );
+	 *			const docFrag = writer.createDocumentFragment();
+	 *
+	 *			writer.append( p1, docFrag );
+	 *			writer.append( blockQuote, docFrag );
+	 *			writer.append( p2, blockQuote );
+	 *			writer.insertText( 'foo', p1 );
+	 *			writer.insertText( 'bar', p2 );
+	 *			// <paragrap>foo</paragraph>
+	 *			// <blockQuote>
+	 *			//    <paragraph>bar</paragraph>
+	 *			// </blockQuote>
+	 *
+	 *			return docFrag;
+	 *		} );
+	 *
+	 *		// insertContent() doesn't have to be used in a change() block. It can, though,
+	 *		// so this code could be moved to the callback defined above.
+	 *		editor.model.insertContent( docFrag, editor.model.document.selection );
+	 *
+	 * Using `insertContent()` with HTML string converted to a model document fragment (similar to the pasting mechanism):
+	 *
+	 *		// You can create your own HtmlDataProcessor instance or use editor.data.processor
+	 *		// if you haven't overriden the default one (which is HtmlDataProcessor instance).
+	 *		const htmlDP = new HtmlDataProcessor();
+	 *
+	 *		// Convert an HTML string to a view document fragment.
+	 *		const viewFragment = htmlDP.toView( htmlString );
+	 *
+	 *		// Convert a view document fragment to a model document fragment
+	 *		// in the context of $root. This conversion takes schema into
+	 *		// the account so if e.g. the view document fragment contained a bare text node
+	 *		// then that text node cannot be a child of $root, so it will be automatically
+	 *		// wrapped with a <paragraph>. You can define the context yourself (in the 2nd parameter),
+	 *		// and e.g. convert the content like it would happen in a <paragraph>.
+	 *		// Note: the clipboard feature uses a custom context called $clipboardHolder
+	 *		// which has a loosened schema.
+	 *		const modelFragment = editor.data.toModel( viewFragment );
+	 *
+	 *		editor.model.insertContent( modelFragment, editor.model.document.selection );
+	 *
 	 * @fires insertContent
 	 * @param {module:engine/model/documentfragment~DocumentFragment|module:engine/model/item~Item} content The content to insert.
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection