|
|
@@ -9,6 +9,7 @@ import ConversionHelpers from './conversionhelpers';
|
|
|
|
|
|
import { cloneDeep } from 'lodash-es';
|
|
|
import ModelSelection from '../model/selection';
|
|
|
+import { attachLinkToDocumentation } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
|
|
|
/* global console */
|
|
|
|
|
|
@@ -335,10 +336,20 @@ export default class UpcastHelpers extends ConversionHelpers {
|
|
|
* @returns {module:engine/conversion/upcasthelpers~UpcastHelpers}
|
|
|
*/
|
|
|
elementToMarker( config ) {
|
|
|
+ /**
|
|
|
+ * The {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker `UpcastHelpers#elementToMarker()`}
|
|
|
+ * method has been deprecated and will be removed in the near future.
|
|
|
+ * Please use {@link module:engine/conversion/upcasthelpers~UpcastHelpers#dataToMarker `UpcastHelpers#dataToMarker()`} instead.
|
|
|
+ *
|
|
|
+ * @error upcast-helpers-element-to-marker-deprecated
|
|
|
+ */
|
|
|
console.warn(
|
|
|
- 'upcast-helpers-element-to-marker-deprecated: ' +
|
|
|
- 'The UpcastHelpers#elementToMarker() method has been deprecated and will be removed in the near future. ' +
|
|
|
- 'Please use #dataToMarker() method instead.' );
|
|
|
+ attachLinkToDocumentation(
|
|
|
+ 'upcast-helpers-element-to-marker-deprecated: ' +
|
|
|
+ 'The UpcastHelpers#elementToMarker() method has been deprecated and will be removed in the near future. ' +
|
|
|
+ 'Please use UpcastHelpers#dataToMarker() instead.'
|
|
|
+ )
|
|
|
+ );
|
|
|
|
|
|
return this.add( upcastElementToMarker( config ) );
|
|
|
}
|
|
|
@@ -346,10 +357,12 @@ export default class UpcastHelpers extends ConversionHelpers {
|
|
|
/**
|
|
|
* View to model marker conversion helper.
|
|
|
*
|
|
|
- * Converts view data created by {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} back to a model marker.
|
|
|
+ * Converts view data created by {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`}
|
|
|
+ * back to a model marker.
|
|
|
*
|
|
|
* This converter looks for specific view elements and view attributes that mark marker boundaries. See
|
|
|
- * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} to learn what view data is expected by this converter.
|
|
|
+ * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} to learn what view data
|
|
|
+ * is expected by this converter.
|
|
|
*
|
|
|
* The `config.view` property is equal to the marker group name to convert.
|
|
|
*
|
|
|
@@ -359,11 +372,31 @@ export default class UpcastHelpers extends ConversionHelpers {
|
|
|
* If such function is set as the `config.model` parameter, it is passed the `name` part from the view element or attribute and it is
|
|
|
* expected to return a string with the marker name.
|
|
|
*
|
|
|
+ * Basic usage:
|
|
|
+ *
|
|
|
* // Using the default conversion.
|
|
|
+ * // In this case, all markers from `comment` group will be converted.
|
|
|
+ * // The conversion will look for `<comment-start>` and `<comment-end>` tags and
|
|
|
+ * // `data-comment-start-before`, `data-comment-start-after`,
|
|
|
+ * // `data-comment-end-before` and `data-comment-end-after` attributes.
|
|
|
* editor.conversion.for( 'upcast' ).dataToMarker( {
|
|
|
* view: 'comment'
|
|
|
* } );
|
|
|
*
|
|
|
+ * An example of a model that may be generated by this conversion:
|
|
|
+ *
|
|
|
+ * // View:
|
|
|
+ * <p>Foo<comment-start name="commentId:uid"></comment-start>bar</p>
|
|
|
+ * <figure data-comment-end-after="commentId:uid" class="image"><img src="abc.jpg" /></figure>
|
|
|
+ *
|
|
|
+ * // Model:
|
|
|
+ * <paragraph>Foo[bar</paragraph>
|
|
|
+ * <image src="abc.jpg"></image>]
|
|
|
+ *
|
|
|
+ * Where `[]` are boundaries of a marker that will receive `comment:commentId:uid` name.
|
|
|
+ *
|
|
|
+ * Other examples of usage:
|
|
|
+ *
|
|
|
* // Using custom function which is the same as the default conversion:
|
|
|
* editor.conversion.for( 'upcast' ).dataToMarker( {
|
|
|
* view: 'comment',
|