Browse Source

Docs: Improved the API documentation of the link decorators feature.

Aleksander Nowodzinski 6 years ago
parent
commit
924fcf9915
1 changed files with 111 additions and 98 deletions
  1. 111 98
      packages/ckeditor5-link/src/link.js

+ 111 - 98
packages/ckeditor5-link/src/link.js

@@ -58,127 +58,140 @@ export default class Link extends Plugin {
  */
 
 /**
- * Target decorator option solves one of the most popular cases, which is adding automatically `target` attribute to all external links.
- * It activates predefined {@link module:link/link~LinkDecoratorAutomaticOption automatic decorator}, which decorates all
- * external links with `target="blank"` and `rel="noopener noreferrer"` attributes, so there is no need to invent own decorator
- * for such case. As external links are recognized those which starts with: `http`, `https` or `//`.
- * There remains the possibility to add other {@link module:link/link~LinkDecoratorAutomaticOption automatic}
- * or {@link module:link/link~LinkDecoratorManualOption manual} decorators.
+ * When set `true`, the `target="blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links
+ * in the editor. By external are meant all links in the editor content starting with `http`, `https`, or `//`.
  *
- * When there is need to apply target attribute manually, then {@link module:link/link~LinkDecoratorManualOption manual} decorator should
- * be provided with the {@link module:link/link~LinkConfig link configuration} in {@link module:link/link~LinkConfig#decorators} array.
- * In this scenario, `targetDecorator` option should remain `undefined` or `false` to not interfere with a created decorator.
+ * Internally, this option activates a predefined {@link module:link/link~LinkDecoratorAutomaticOption automatic link decorator},
+ * which extends all external links with the `target` and `rel` attributes without additional configuration.
  *
- * More information about decorators might be found in {@link module:link/link~LinkConfig#decorators}.
+ * **Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated
+ * {@link module:link/link~LinkDecoratorManualOption manual} decorator must be defined in the
+ * {@link module:link/link~LinkConfig#decorators `config.link.decodators`} array. In such scenario,
+ * the `config.link.targetDecorator` option should remain `undefined` or `false` to not interfere with the manual decorator.
+ *
+ * **Note**: It is possible to add other {@link module:link/link~LinkDecoratorAutomaticOption automatic}
+ * or {@link module:link/link~LinkDecoratorManualOption manual} link decorators when this option is active.
+ *
+ * More information about decorators can be found in the {@link module:link/link~LinkConfig#decorators decorators configuration}
+ * reference.
  *
  * @member {Boolean} module:link/link~LinkConfig#targetDecorator
  */
 
 /**
- * Decorators are {@link module:link/link~Link link's} plugin feature which can extend anchor with additional attributes.
- * Decorators provide an easy way to configure and manage those attributes automatically or manually with the UI.
- *
- * For example, there is a quite common topic to add the `target="_blank"` attribute to only some of the links in the editor.
- * Decorators help in mentioned case with either: added automatic rules based on link's href (URL),
- * or added a toggleable UI switch for the user.
- *
- * **Warning:** Currently, there is no integration in-between decorators for any mix of decorators' types.
- * For example, configuring `target` attribute through both 'automatic' and 'manual' decorators might result with quirk behavior
- * as well as defining 2 manual or 2 automatic decorators for the same attribute.
- *
- * # Automatic decorators
- * This type of decorators takes an object with key-value pairs of attributes and
- * a {@link module:link/link~LinkDecoratorAutomaticOption callback} function. The function has to return boolean value based on link's href.
- * If a given set of attributes should be applied to the link, then callback has to return the `true` value.
- * For example, if there is a need to add the `target="_blank"` attribute to all links in the editor started with the `http://`,
- * then configuration might look like this:
- *
- * 	const link.decorators = [
- * 		{
- * 			mode: 'automatic',
- * 			callback: url => url.startsWith( 'http://' ),
- * 			attributes: {
- * 				target: '_blank'
- * 			}
- * 		}
- * 	]
- *
- * **Please notice:** As configuring target attribute for external links is a quite common situation,
- * there is predefined automatic decorator, which might be turned on with even simpler option,
- * just by setting {@link #targetDecorator} to `true`. More information might be found in the {@link #targetDecorator} description.
- *
- * # Manual decorators
- * This type of decorators also takes an object with key-value pair of attributes, however, those are applied based on user choice.
- * Manual decorator is defined with a {@link module:link/link~LinkDecoratorManualOption label},
- * which describes the given option for the user. Manual decorators are possible to toggle for the user in editing view of the link plugin.
- * For example, if there is a need to give user full control over this which links should be opened in a new window,
- * then configuration might looks as followed:
- *
- * 	const link.decorators = [
- * 		{
- * 			mode: 'manual',
- * 			label: 'Open in new window',
- * 			attributes: {
- * 				target: '_blank'
- * 			}
- * 		}
- * 	]
+ * Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are
+ * two types of link decorators:
+ *
+ * * **automatic** – they match links against pre–defined rules and manage the attributes based on the results,
+ * * **manual** – they allow users to control link attributes individually using the editor UI.
+ *
+ * The most common use case for decorators is applying the `target="_blank"` attribute to links in the content
+ * (`<a href="..." target="_blank">Link</a>`).
+ *
+ * # {@link module:link/link~LinkDecoratorAutomaticOption Automatic decorators}
+ *
+ * This kind of a decorator matches all links in the editor content against a function which decides whether the link
+ * should gain a pre–defined set of attributes or not.
+ *
+ * It takes an object with key-value pairs of attributes and a {@link module:link/link~LinkDecoratorAutomaticOption `callback`} function
+ * which must return a boolean based on link's `href`. When the callback returns `true`, the `attributes` are applied
+ * to the link.
+ *
+ * For example, to add the `target="_blank"` attribute to all links starting with the `http://` in the content,
+ * the configuration could look as follows:
+ *
+ *		const link.decorators = [
+ *			{
+ *				mode: 'automatic',
+ *				callback: url => url.startsWith( 'http://' ),
+ *				attributes: {
+ *					target: '_blank'
+ *				}
+ *			}
+ *		]
+ *
+ * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
+ * dedicated for that purpose which can be enabled by turning a single option on. Check out the
+ * {@link module:link/link~LinkConfig#targetDecorator `config.link.targetDecorator`} configuration description to learn more.
+ *
+ * # {@link module:link/link~LinkDecoratorManualOption Manual decorators}
+ *
+ * This type of a decorator takes an object with key-value pair of attributes, but those are applied based on the user choice.
+ *
+ * Manual decorators are represented as switch buttons in the {@link module:link/linkui user interface} of the link feature.
+ * This is why each manual decorator requires a {@link module:link/link~LinkDecoratorManualOption label} which describes its purpose
+ * to the users.
+ *
+ * For example, if users are to be allowed to control which particular links should be opened in a new window, the configuration
+ * could look as follows:
+ *
+ *		const link.decorators = [
+ *			{
+ *				mode: 'manual',
+ *				label: 'Open in new window',
+ *				attributes: {
+ *					target: '_blank'
+ *				}
+ *			}
+ *		]
+ *
+ * **Warning:** Currently, link decorators work independently and no conflict resolution mechanism exists.
+ * For example, configuring the `target` attribute using both an automatic and a manual decorator at a time could end up with a
+ * quirky behavior. The same applies if multiple manual or automatic decorators were defined for the same attribute.
  *
  * @member {Array.<module:link/link~LinkDecoratorAutomaticOption|module:link/link~LinkDecoratorManualOption>}
  * module:link/link~LinkConfig#decorators
  */
 
 /**
- * This object describes automatic {@link module:link/link~LinkConfig#decorators} for the links. Based on this option,
- * output data will extend links with proper attributes.
- *
- * For example, if there is need to define a rule that automatically adds attribute `target="_blank"` and `rel="noopener noreferrer"`
- * to the external links, then automatic decorator might looks as follows:
- *
- *	{
- *		mode: 'automatic',
- *		callback: url => /^(https?:)?\/\//.test( url ),
- *		attributes: {
- *			target: '_blank',
- *			rel: 'noopener noreferrer'
+ * Describes an automatic link {@link module:link/link~LinkConfig#decorators decorator}. This kind of a decorator matches
+ * all links in the editor content against a function which decides whether the link should gain a pre–defined set of attributes
+ * or not.
+ *
+ * For example, to add the `target="_blank"` attribute to all links in the editor starting with the `http://`,
+ * then configuration could look like this:
+ *
+ *		{
+ *			mode: 'automatic',
+ *			callback: url => url.startsWith( 'http://' ),
+ *			attributes: {
+ *				target: '_blank'
+ *			}
  *		}
- *	}
  *
- * **Please notice**, there is a {@link module:link/link~LinkConfig#targetDecorator configuration option},
- * which automatically adds attributes: `target="_blank"` and `rel="noopener noreferrer"` for all links started with:
- * `http://`, `https://` or `//`.
+ * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
+ * dedicated for that purpose which can be enabled by turning a single option on. Check out the
+ * {@link module:link/link~LinkConfig#targetDecorator `config.link.targetDecorator`} configuration description to learn more.
  *
  * @typedef {Object} module:link/link~LinkDecoratorAutomaticOption
- * @property {'automatic'} mode should have string value equal 'automatic' for automatic decorators
- * @property {Function} callback takes an `url` as a parameter and returns `true`
- * for urls where given attributes should be applied.
- * @property {Object} attributes key-value pairs used as attributes added to output data during
+ * @property {'automatic'} mode The kind of the decorator. `'automatic'` for all automatic decorators.
+ * @property {Function} callback Takes an `url` as a parameter and returns `true` if the `attributes` should be applied to the link.
+ * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
- * Attributes should have form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+ * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  */
 
 /**
- * This object describes manual {@link module:link/link~LinkConfig#decorators} for the links. Based on this definition,
- * there is added switch button in editing form for the link. This button poses label define here. After toggling and confirming it,
- * preconfigured attributes are added to a selected link.
- *
- * For example, if there is need to define a rule, which adds a switch button to apply `target="_blank"` and
- * `rel="noopener noreferrer"`, then manual decorator might be helpful and can look as follows:
- *
- *	{
- *		mode: 'manual',
- *		label: 'Open link in new window',
- *		attributes: {
- *			target: '_blank',
- *			rel: 'noopener noreferrer'
+ * Describes a manual link {@link module:link/link~LinkConfig#decorators decorator}. This kind of a decorator is represented in
+ * the link feature's {@link module:link/linkui user interface} as a switch the user can use to control the presence
+ * of a pre–defined set of attributes.
+ *
+ * For instance, to allow users to manually control the presence of the `target="_blank"` and
+ * `rel="noopener noreferrer"` attributes on specific links, the decorator could look as follows:
+ *
+ *		{
+ *			mode: 'manual',
+ *			label: 'Open link in new window',
+ *			attributes: {
+ *				target: '_blank',
+ *				rel: 'noopener noreferrer'
+ *			}
  *		}
- *	}
  *
  * @typedef {Object} module:link/link~LinkDecoratorManualOption
- * @property {'manual'} mode should have string value equal 'manual' for manual decorators
- * @property {String} label the label for the UI switch button, which will be responsible for applying defined attributes
- * to a currently edited link.
- * @property {Object} attributes attributes key-value pairs used as attributes added to output data during
+ * @property {'automatic'} 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}.
- * Attributes should have form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+ * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  */