From ca21a66541c78c931b6e89b8b25f2f14779996f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= Date: Sun, 20 Jan 2019 17:52:39 +0100 Subject: [PATCH] Docs: Reviewed conversion documentation. --- src/conversion/conversion.js | 85 +++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 35 deletions(-) diff --git a/src/conversion/conversion.js b/src/conversion/conversion.js index 5fd7e2e2f..94b0a1be6 100644 --- a/src/conversion/conversion.js +++ b/src/conversion/conversion.js @@ -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 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.} 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}