|
|
@@ -24,6 +24,8 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
* * `dataDowncast`
|
|
|
* * `upcast`
|
|
|
*
|
|
|
+ * # One-way converters
|
|
|
+ *
|
|
|
* To add a converter to a specific group, use the {@link module:engine/conversion/conversion~Conversion#for `for()`}
|
|
|
* method:
|
|
|
*
|
|
|
@@ -36,12 +38,12 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
* // And a slightly different one for the editing pipeline:
|
|
|
* editor.conversion.for( 'editingDowncast' ).elementToElement( editingConversionConfig ) );
|
|
|
*
|
|
|
- * The functions used in `add()` calls are one-way converters (i.e. you need to remember yourself to add
|
|
|
- * a converter in the other direction, if your feature requires that). They are also called "conversion helpers".
|
|
|
- * You can find a set of them in the {@link module:engine/conversion/downcasthelpers} and
|
|
|
- * {@link module:engine/conversion/upcasthelpers} modules.
|
|
|
+ * See {@link module:engine/conversion/conversion~Conversion#for `for()`} method documentation to learn more about
|
|
|
+ * available conversion helpers and how to use your custom ones.
|
|
|
+ *
|
|
|
+ * # Two-way converters
|
|
|
*
|
|
|
- * Besides allowing to register converters to specific dispatchers, you can also use methods available in this
|
|
|
+ * Besides using one-way converters via the `for()` method, you can also use other methods available in this
|
|
|
* class to add two-way converters (upcast and downcast):
|
|
|
*
|
|
|
* * {@link module:engine/conversion/conversion~Conversion#elementToElement `elementToElement()`} –
|
|
|
@@ -88,46 +90,59 @@ export default class Conversion {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Provides chainable API to assign converters to dispatchers registered under a given group name. Converters are added
|
|
|
- * by calling the {@link module:engine/conversion/conversion~ConversionHelpers#add `.add()`} method of an
|
|
|
- * {@link module:engine/conversion/conversion~ConversionHelpers conversion helpers} returned by this function.
|
|
|
+ * Provides a chainable API to assign converters to conversion dispatchers.
|
|
|
+ *
|
|
|
+ * You can use conversion helpers available directly in the `for()` chain or your custom ones via
|
|
|
+ * the {@link module:engine/conversion/conversion~ConversionHelpers#add `add()`} method.
|
|
|
+ *
|
|
|
+ * # Using bulit-in conversion helpers
|
|
|
+ *
|
|
|
+ * The `for()` chain comes with a set of conversion helpers which you can use like this:
|
|
|
*
|
|
|
* editor.conversion.for( 'downcast' )
|
|
|
- * .add( conversionHelperA ) // Adds a custom converter A.
|
|
|
- * .add( conversionHelperB ) // Adds a custom converter B.
|
|
|
- * .elementToElement( config ); // Adds a custom element-to-element downcast converter.
|
|
|
+ * .elementToElement( config1 ) // Adds an element-to-element downcast converter.
|
|
|
+ * .attributeToElement( config2 ); // Adds an attribute-to-element downcast converter.
|
|
|
*
|
|
|
- * In this example `conversionHelperA` and `conversionHelperB` will be called for all dispatchers from the `'model'` group.
|
|
|
+ * editor.conversion.for( 'upcast' )
|
|
|
+ * .elementToAttribute( config3 ); // Adds an element-to-attribute upcast converter.
|
|
|
*
|
|
|
- * The `.add()` method takes exactly one parameter, which is a function. This function should accept one parameter that
|
|
|
- * is a dispatcher instance. The function should add an actual converter to the passed dispatcher instance.
|
|
|
+ * Refer to the documentation of built-in conversion helpers to learn about their configuration options.
|
|
|
*
|
|
|
- * Conversion helpers for most common cases are already provided. They are flexible enough to cover most use cases.
|
|
|
- * See the documentation to learn how they can be configured.
|
|
|
+ * * downcast (model-to-view) conversion helpers:
|
|
|
*
|
|
|
- * For downcast (model-to-view conversion), these are:
|
|
|
+ * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`},
|
|
|
+ * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement `attributeToElement()`},
|
|
|
+ * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToAttribute `attributeToAttribute()`}.
|
|
|
+ * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToElement `markerToElement()`}.
|
|
|
+ * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToHighlight `markerToHighlight()`}.
|
|
|
*
|
|
|
- * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement Downcast element-to-element converter},
|
|
|
- * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement Downcast attribute-to-element converter},
|
|
|
- * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToAttribute Downcast attribute-to-attribute converter}.
|
|
|
- * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToElement Downcast marker-to-element converter}.
|
|
|
- * * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToHighlight Downcast marker-to-highlight converter}.
|
|
|
+ * * upcast (view-to-model) conversion helpers:
|
|
|
*
|
|
|
- * For upcast (view-to-model conversion), these are:
|
|
|
+ * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToElement `elementToElement()`},
|
|
|
+ * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToAttribute `elementToAttribute()`},
|
|
|
+ * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#attributeToAttribute `attributeToAttribute()`}.
|
|
|
+ * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker `elementToMarker()`}.
|
|
|
*
|
|
|
- * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToElement Upcast element-to-element converter},
|
|
|
- * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToAttribute Upcast attribute-to-element converter},
|
|
|
- * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#attributeToAttribute Upcast attribute-to-attribute converter}.
|
|
|
- * * {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker Upcast element-to-marker converter}.
|
|
|
+ * # Using custom conversion helpers
|
|
|
*
|
|
|
- * An example of using conversion helpers to convert the `paragraph` model element to the `p` view element (and back):
|
|
|
+ * If you need to implement a nontypical converter, you can do so by calling:
|
|
|
*
|
|
|
- * // Define conversion configuration - model element 'paragraph' should be converted to view element 'p'.
|
|
|
- * const config = { model: 'paragraph', view: 'p' };
|
|
|
+ * editor.conversion.for( direction ).add( customHelper );
|
|
|
+ *
|
|
|
+ * The `.add()` method takes exactly one parameter, which is a function. This function should accept one parameter that
|
|
|
+ * is a dispatcher instance. The function should add an actual converter to the passed dispatcher instance.
|
|
|
+ *
|
|
|
+ * Example:
|
|
|
+ *
|
|
|
+ * editor.conversion.for( 'upcast' ).add( dispatcher => {
|
|
|
+ * dispatcher.on( 'element:a', ( evt, data, conversionApi ) => {
|
|
|
+ * // Do something with a view <a> element.
|
|
|
+ * } );
|
|
|
+ * } );
|
|
|
*
|
|
|
- * // Add converters to proper dispatchers using conversion helpers.
|
|
|
- * editor.conversion.for( 'downcast' ).elementToElement( config ) );
|
|
|
- * editor.conversion.for( 'upcast' ).elementToElement( config ) );
|
|
|
+ * Refer to the documentation of {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher}
|
|
|
+ * and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} to learn how to write
|
|
|
+ * custom converters.
|
|
|
*
|
|
|
* @param {String} groupName The name of dispatchers group to add the converters to.
|
|
|
* @returns {module:engine/conversion/downcasthelpers~DowncastHelpers|module:engine/conversion/upcasthelpers~UpcastHelpers}
|
|
|
@@ -595,7 +610,7 @@ function* _getUpcastDefinition( model, view, upcastAlso ) {
|
|
|
*/
|
|
|
export class ConversionHelpers {
|
|
|
/**
|
|
|
- * Creates ConversionHelpers instance.
|
|
|
+ * Creates `ConversionHelpers` instance.
|
|
|
*
|
|
|
* @param {Array.<module:engine/conversion/downcastdispatcher~DowncastDispatcher|
|
|
|
* module:engine/conversion/upcastdispatcher~UpcastDispatcher>} dispatcher
|
|
|
@@ -608,7 +623,7 @@ export class ConversionHelpers {
|
|
|
* Registers a conversion helper.
|
|
|
*
|
|
|
* **Note**: See full usage example in the `{@link module:engine/conversion/conversion~Conversion#for conversion.for()}`
|
|
|
- * method description
|
|
|
+ * method description.
|
|
|
*
|
|
|
* @param {Function} conversionHelper The function to be called on event.
|
|
|
* @returns {module:engine/conversion/downcasthelpers~DowncastHelpers|module:engine/conversion/upcasthelpers~UpcastHelpers}
|