瀏覽代碼

Fix docuemntation after introduced changes in decoratorrs.

Mateusz Samsel 6 年之前
父節點
當前提交
d29141e39a

+ 21 - 8
packages/ckeditor5-link/src/link.js

@@ -88,11 +88,12 @@ export default class Link extends Plugin {
  * * {@link module:link/link~LinkDecoratorManualDefinition manual} – they allow users to control link attributes individually
  *  using the editor UI.
  *
- * Link decorators are defined as an array of objects:
+ * Link decorators are defined as an object with key-value pair, where key is a name provided for given decorator and value is decorator
+ * definition.
  *
  *		const linkConfig = {
- *			decorators: [
- *				{
+ *			decorators: {
+ *				isExternal: {
  *					mode: 'automatic',
  *					callback: url => url.startsWith( 'http://' ),
  *					attributes: {
@@ -100,7 +101,7 @@ export default class Link extends Plugin {
  *						rel: 'noopener noreferrer'
  *					}
  *				},
- *				{
+ *				isDownloadable: {
  *					mode: 'manual',
  *					label: 'Downloadable',
  *					attributes: {
@@ -108,7 +109,7 @@ export default class Link extends Plugin {
  *					}
  *				},
  *				// ...
- *			]
+ *			}
  *		}
  *
  * To learn more about the configuration syntax, check out the {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
@@ -123,8 +124,20 @@ export default class Link extends Plugin {
  * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
  * configuration description to learn more.
  *
- * @member {Array.<module:link/link~LinkDecoratorAutomaticDefinition|module:link/link~LinkDecoratorManualDefinition>}
- * module:link/link~LinkConfig#decorators
+ * @member {Object.<String, module:link/link~LinkDecoratorDefinition>} module:link/link~LinkConfig#decorators
+ */
+
+/**
+ * Represents a link decorator definition {@link module:link/link~LinkDecoratorManualDefinition `'manual'`} or
+ * {@link module:link/link~LinkDecoratorAutomaticDefinition `'automatic'`}.
+ *
+ * @interface LinkDecoratorDefinition
+ */
+
+/**
+ * The kind of the decorator. `'manual'` for all manual decorators and `'automatic'` for all automatic decorators.
+ *
+ * @member {'manual'|'automatic'} module:link/link~LinkDecoratorDefinition#mode
  */
 
 /**
@@ -177,7 +190,7 @@ export default class Link extends Plugin {
  *		}
  *
  * @typedef {Object} module:link/link~LinkDecoratorManualDefinition
- * @property {'automatic'} mode The kind of the decorator. `'manual'` for all manual decorators.
+ * @property {'manual'} mode The kind of the decorator. `'manual'` for all manual decorators.
  * @property {String} label The label of the UI button the user can use to control the presence of link attributes.
  * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.

+ 15 - 14
packages/ckeditor5-link/src/linkcommand.js

@@ -36,13 +36,13 @@ export default class LinkCommand extends Command {
 		 * You can consider it a model with states of manual decorators added to currently selected link.
 		 *
 		 * @readonly
-		 * @type {module:utils/collection~Collection.<module:link/utils~ManualDecorator>}
+		 * @type {module:utils/collection~Collection}
 		 */
 		this.manualDecorators = new Collection();
 	}
 
 	/**
-	 * Synchronize state of the decorator with actually present elements in the model.
+	 * Synchronize state of {@link #manualDecorators} with actually present elements in the model.
 	 */
 	restoreManualDecoratorStates() {
 		for ( const manualDecorator of this.manualDecorators ) {
@@ -83,8 +83,9 @@ export default class LinkCommand extends Command {
 	 *
 	 * This command has an optional argument, which applies or removes model attributes brought by
 	 * {@link module:link/utils~ManualDecorator manual decorators}. Model attribute names correspond to
-	 * decorator {@link module:link/utils~ManualDecorator#id ids} and follow the incremental pattern:
-	 * `'linkManualDecorator0'`, `'linkManualDecorator1'`, `'linkManualDecorator2'`, etc..
+	 * decorator {@link module:link/utils~ManualDecorator#id ids} and and they are created based on decorator's entry in configuration.
+	 * Attribute name is combination of `link` prefix with object's key used to define given decorator. For example,
+	 * `'linkIsExternal'`, `'linkIsDownloadable'`, `'linkFoo'`, etc..
 	 *
 	 * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`}
 	 * documentation.
@@ -95,25 +96,25 @@ export default class LinkCommand extends Command {
 	 *
 	 *		// Adding a new decorator attribute.
 	 *		linkCommand.execute( 'http://example.com', {
-	 *			linkDecorator0: true
+	 *			linkIsExternal: true
 	 *		} );
 	 *
 	 *		// Removing a decorator attribute from a selection.
 	 *		linkCommand.execute( 'http://example.com', {
-	 *			linkDecorator0: false
+	 *			linkIsExternal: false
 	 *		} );
 	 *
 	 *		// Adding multiple decorator attributes at a time.
 	 *		linkCommand.execute( 'http://example.com', {
-	 *			linkDecorator0: true,
-	 *			linkDecorator2: true,
+	 *			linkIsExternal: true,
+	 *			linkIsDownloadable: true,
 	 *		} );
 	 *
 	 *		// Removing and adding decorator attributes at a time.
 	 *		linkCommand.execute( 'http://example.com', {
-	 *			linkDecorator0: false,
-	 *			linkDecorator1: true,
-	 *			linkDecorator2: false,
+	 *			linkIsExternal: false,
+	 *			linkFoo: true,
+	 *			linkIsDownloadable: false,
 	 *		} );
 	 *
 	 * **Note**: If decorator attribute name is not specified its state remains untouched.
@@ -203,11 +204,11 @@ export default class LinkCommand extends Command {
 	}
 
 	/**
-	 * Method provides information if given decorator is present in currently processed selection.
+	 * Method provides the information if a decorator with given name is present in currently processed selection.
 	 *
 	 * @private
-	 * @param {String} decoratorName name of a link decorator used in the model
-	 * @returns {Boolean} Information if a given decorator is currently present in a selection
+	 * @param {String} decoratorName name of a manual decorator used in the model
+	 * @returns {Boolean} The information if a given decorator is currently present in a selection
 	 */
 	_getDecoratorStateFromModel( decoratorName ) {
 		const doc = this.editor.model.document;

+ 3 - 0
packages/ckeditor5-link/src/linkui.js

@@ -314,6 +314,9 @@ export default class LinkUI extends Plugin {
 	 * Closes form view. Decides whether the balloon should be hidden completely or if action view should be shown. This is decided upon
 	 * link command value (which has value if the document selection is in link).
 	 *
+	 * If there are defined {@link module:link/link~LinkConfig#decorators} in editor's config, then there are additionally
+	 * rest switch buttons state responsible for manual decorators handling.
+	 *
 	 * @private
 	 */
 	_closeFormView() {

+ 4 - 2
packages/ckeditor5-link/src/utils.js

@@ -92,9 +92,11 @@ export function getLocalizedDecorators( t, decorators ) {
 }
 
 /**
- * Converts Obj of decorators to Array of decorators with nice identifiers.
+ * Converts an object with defined decorators to a normalized array of decorators. There is also added `id` key for each decorator,
+ * which is used as attribute's name in the model.
  *
- * @param {Object} decorators
+ * @param {Object.<String, module:link/link~LinkDecoratorDefinition>} decorators
+ * @returns {Array.<module:link/link~LinkDecoratorAutomaticDefinition|module:link/link~LinkDecoratorManualDefinition>}
  */
 export function normalizeDecorators( decorators ) {
 	const retArray = [];