浏览代码

Update documentation of the downcast dispatcher and downcast helpers.

Maciej Gołaszewski 5 年之前
父节点
当前提交
64d11de081

+ 27 - 1
packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -209,7 +209,22 @@ export default class DowncastDispatcher {
 		}
 	}
 
-	mapRefreshEvents( modelName, events = [] ) {
+	/**
+	 * Maps model element "insert" reconversion for given event names. The event names must be fully specified:
+	 *
+	 * * For "attribute" change event it should include main element name, ie: `'attribute:attributeName:main'`.
+	 * * For child nodes change events, those should use child event name as well, ie:
+	 *     * For adding a node: `'insert:child'`.
+	 *     * For removing a node: `'remove:child'`.
+	 *
+	 * **Note**: This method should not be used directly. A reconversion is defined by `triggerBy` attribute of the `elementToElement()`
+	 * conversion helper.
+	 *
+	 * @protected
+	 * @param {String} modelName Main model element name for which events will trigger reconversion.
+	 * @param {Array<String>} events Array of inner events that would trigger conversion for this model.
+	 */
+	mapRefreshEvents( modelName, events ) {
 		for ( const eventName of events ) {
 			this._refreshEventMap.set( eventName, modelName );
 		}
@@ -310,6 +325,17 @@ export default class DowncastDispatcher {
 		this._clearConversionApi();
 	}
 
+	/**
+	 * Starts a refresh conversion - depending on a configuration it would:
+	 *
+	 * - fire a {@link #event:insert `insert` event} for the element to refresh.
+	 * - handle conversion of a range insert for nodes under the refreshed item which are not bound as slots.
+	 *
+	 * @fires insert
+	 * @param {module:engine/model/range~Range} range The inserted range.
+	 * @param {String} name Name of main item to refresh. TODO - a whole item might be enough here.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer The view writer that should be used to modify the view document.
+	 */
 	convertRefresh( range, name, writer ) {
 		this.conversionApi.writer = writer;
 

+ 16 - 1
packages/ckeditor5-engine/src/conversion/downcasthelpers.js

@@ -59,6 +59,21 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *			}
 	 *		} );
 	 *
+	 * The element-to-element conversion supports a reconversion mechanism. This is helpful in conversion to complex view structures where
+	 * multiple atomic element-to-element and attribute-to-attribute or attribute-to-element could be used. By specifying `triggerBy`
+	 * events you can trigger reconverting model to a full view tree structures at once.
+	 *
+	 *		editor.conversion.for( 'downcast' ).elementToElement( {
+	 *			model: 'complex',
+	 *			view: ( modelElement, conversionApi ) => createComplexViewFromModel( modelElement, conversionApi ),
+	 *			triggerBy: [
+	 *				'attribute:foo:complex',
+	 *				'attribute:bar:complex',
+	 *				'insert:slot',
+	 *				'remove:slot'
+	 *			]
+	 *		} );
+	 *
 	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
 	 * to the conversion process.
 	 *
@@ -1386,7 +1401,7 @@ function downcastElementToElement( config ) {
 	return dispatcher => {
 		dispatcher.on( 'insert:' + config.model, insertElement( config.view ), { priority: config.converterPriority || 'normal' } );
 
-		if ( config.triggerBy ) {
+		if ( Array.isArray( config.triggerBy ) ) {
 			dispatcher.mapRefreshEvents( config.model, config.triggerBy );
 		}
 	};