8
0
Просмотр исходного кода

Extend description and provide examples for link command.

Mateusz Samsel 6 лет назад
Родитель
Сommit
93d76405d9

+ 1 - 1
packages/ckeditor5-link/src/link.js

@@ -66,7 +66,7 @@ export default class Link extends Plugin {
  *
  * **Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated
  * {@link module:link/link~LinkDecoratorManualDefinition manual} decorator must be defined in the
- * {@link module:link/link~LinkConfig#decorators `config.link.decodators`} array. In such scenario,
+ * {@link module:link/link~LinkConfig#decorators `config.link.decorators`} array. In such scenario,
  * the `config.link.addTargetToExternalLinks` option should remain `undefined` or `false` to not interfere with the manual decorator.
  *
  * **Note**: It is possible to add other {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}

+ 44 - 0
packages/ckeditor5-link/src/linkcommand.js

@@ -80,6 +80,50 @@ export default class LinkCommand extends Command {
 	 * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`}
 	 * documentation.
 	 *
+	 * Usage of `manualDecoratorIds` in link command:
+	 *
+	 *		const linkCommand = editor.commands.get( 'link' );
+	 *
+	 *		// 1. Add new decorator ( empty model )
+	 *		linkCommand.execute( 'http://example.com', {
+	 *			linkDecorator0: true
+	 *		} );
+	 *		// result: <$text href="http://example.com" linkDecorator0="true">http://example.com</$text>
+	 *
+	 *		// 2. Remove decorator over selection:
+	 *		// [<$text href="http://example.com" linkDecorator0="true">http://example.com</$text>]
+	 *		linkCommand.execute( 'http://example.com', {
+	 *			linkDecorator0: false
+	 *		} );
+	 *		// result: <$text href="http://example.com">http://example.com</$text>
+	 *
+	 * There is possibility to modify multiple decorators at the same time:
+	 *
+	 *		const linkCommand = editor.commands.get( 'link' );
+	 *
+	 *		// 1. Add new decorator ( empty model )
+	 *		linkCommand.execute( 'http://example.com', {
+	 *			linkDecorator0: true,
+	 *			linkDecorator2: true,
+	 *		} );
+	 *		// result:
+	 *		// <$text href="http://example.com" linkDecorator0="true" linkDecorator2="true">http://example.com</$text>
+	 *
+	 *		// 2. Remove and add new decorator over selection:
+	 *		// [<$text href="http://example.com" linkDecorator0="true" linkDecorator2="true">http://example.com</$text>]
+	 *		linkCommand.execute( 'http://example.com', {
+	 *			linkDecorator0: false,
+	 *			linkDecorator1: true,
+	 *			linkDecorator2: false,
+	 *		} );
+	 *		// result:
+	 *		// <$text href="http://example.com" linkDecorator1="true">http://example.com</$text>
+	 *
+	 * **Note**: If decorator name is not passed to the command, then its state remains untouched.
+	 *
+	 * **Note**: {@link module:link/unlinkcommand~UnlinkCommand#execute `UnlinkCommand#execute()`} also removes all decorators
+	 * from the link.
+	 *
 	 * @fires execute
 	 * @param {String} href Link destination.
 	 * @param {Object} [manualDecoratorIds={}] The information about manual decorator attributes to be applied or removed upon execution.

+ 1 - 1
packages/ckeditor5-link/src/linkediting.js

@@ -127,7 +127,7 @@ export default class LinkEditing extends Plugin {
 	/**
 	 * Processes an array of configured {@link module:link/link~LinkDecoratorManualDefinition manual decorators}
 	 * and transforms them into {@link module:link/utils~ManualDecorator} instances and stores them in the
-	 * {@link module:link/linkcommand~LinkCommand#manualDecorators} collection (a model for manual decorators state).
+	 * {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection} collection (a model for manual decorators state).
 	 *
 	 * Also registers an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attributeToElement}
 	 * converter for each manual decorator and extends the {@link module:engine/model/schema~Schema model's schema}

+ 14 - 12
packages/ckeditor5-link/src/ui/linkformview.js

@@ -39,7 +39,7 @@ export default class LinkFormView extends View {
 	 *
 	 * @param {module:utils/locale~Locale} [locale] The localization services instance.
 	 * @param {module:utils/collection~Collection} [manualDecoratorCollection] Reference to manual decorators in
-	 * {@link module:link/linkcommand~LinkCommand#manualDecorators}.
+	 * {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection}.
 	 */
 	constructor( locale, manualDecoratorCollection = [] ) {
 		super( locale );
@@ -86,8 +86,8 @@ export default class LinkFormView extends View {
 
 		/**
 		 * A collection of {@link module:ui/button/switchbuttonview~SwitchButtonView},
-		 * which corresponds to {@link #manualDecorators manual decorators} configured in the editor.
-		 * Populated by {@link #_createManualDecoratorsUIView}.
+		 * which corresponds to {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection manual decorators}
+		 * configured in the editor.
 		 *
 		 * @private
 		 * @readonly
@@ -153,9 +153,11 @@ export default class LinkFormView extends View {
 	}
 
 	/**
-	 * Obtain state of the switch buttons in a currently opened {@link module:link/ui/linkformview~LinkFormView}.
+	 * Obtain state of the {@link module:ui/button/switchbuttonview~SwitchButtonView switch buttons} representing
+	 * {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection manual decorators}
+	 * in a currently opened {@link module:link/ui/linkformview~LinkFormView}.
 	 *
-	 * @returns {Object} key-value pairs, where key is the name of the decorator and value is its state.
+	 * @returns {Object} key-value pairs, where the key is the name of the decorator and the value is its state.
 	 */
 	getDecoratorSwitchesState() {
 		return Array.from( this._manualDecoratorSwitches ).reduce( ( accumulator, switchButton ) => {
@@ -251,11 +253,11 @@ export default class LinkFormView extends View {
 
 	/**
 	 * Populates {@link module:ui/viewcollection~ViewCollection} of {@link module:ui/button/switchbuttonview~SwitchButtonView}
-	 * made based on {@link #manualDecorators}
+	 * made based on {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection}
 	 *
 	 * @private
-	 * @param {module:link/linkcommand~LinkCommand#manualDecorators} manualDecoratorCollection reference to collection of manual decorators
-	 * stored in link's command.
+	 * @param {module:link/linkcommand~LinkCommand#manualDecoratorCollection} manualDecoratorCollection reference to
+	 * collection of manual decorators stored in link's command.
 	 * @returns {module:ui/viewcollection~ViewCollection} of Switch Buttons.
 	 */
 	_createManualDecoratorSwitches( manualDecoratorCollection ) {
@@ -285,13 +287,13 @@ export default class LinkFormView extends View {
 	/**
 	 * Populates the {@link #children} collection of the form.
 	 *
-	 * If {@link #manualDecorators manual decorators} are configured in the editor, creates an
-	 * additional `View` wrapping all {@link #manualDecoratorsUIView} switch buttons corresponding
+	 * If {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection manual decorators} are configured in the editor, creates an
+	 * additional `View` wrapping all {@link #_manualDecoratorSwitches} switch buttons corresponding
 	 * to those decorators.
 	 *
 	 * @private
-	 * @param {module:link/linkcommand~LinkCommand#manualDecorators} manualDecoratorCollection reference to collection of manual decorators
-	 * stored in link's command.
+	 * @param {module:link/linkcommand~LinkCommand#manualDecoratorCollection} manualDecoratorCollection reference to
+	 * collection of manual decorators stored in link's command.
 	 * @returns {module:ui/viewcollection~ViewCollection} children of LinkFormView.
 	 */
 	_createFormChildren( manualDecoratorCollection ) {

+ 10 - 0
packages/ckeditor5-link/src/unlinkcommand.js

@@ -29,6 +29,16 @@ export default class UnlinkCommand extends Command {
 	 * When the selection is collapsed, removes the `linkHref` attribute from each node with the same `linkHref` attribute value.
 	 * When the selection is non-collapsed, removes the `linkHref` attribute from each node in selected ranges.
 	 *
+	 * # Decorators
+	 * If there are defined {@link module:link/link~LinkConfig#decorators decorators} in the editor's configuration,
+	 * then all decorators are removed together with `linkHref` attribute.
+	 *
+	 *		const unlinkCommand = editor.commands.get( 'unlink' )'
+	 *
+	 *		// model: [<$text href="example.com" linkDecorator0="true">Foo bar</$text>]
+	 *		unlinkCommand.execute();
+	 *		// model: [Foo bar]
+	 *
 	 * @fires execute
 	 */
 	execute() {

+ 1 - 1
packages/ckeditor5-link/src/utils/manualdecorator.js

@@ -13,7 +13,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 /**
  * Helper class which stores manual decorators with observable {@link module:link/utils~ManualDecorator#value}
  * to support integration with the UI state. An instance of this class is a model with state of single manual decorators.
- * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}.
+ * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecoratorCollection}.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */