浏览代码

Docs: Simplified link decorator configuration docs.

Aleksander Nowodzinski 6 年之前
父节点
当前提交
b2b2c38dff
共有 1 个文件被更改,包括 36 次插入51 次删除
  1. 36 51
      packages/ckeditor5-link/src/link.js

+ 36 - 51
packages/ckeditor5-link/src/link.js

@@ -61,7 +61,7 @@ export default class Link extends Plugin {
  * 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 `//`.
  *
- * Internally, this option activates a predefined {@link module:link/link~LinkDecoratorAutomaticOption automatic link decorator},
+ * Internally, this option activates a predefined {@link module:link/link~LinkConfig#decorators automatic link decorator},
  * which extends all external links with the `target` and `rel` attributes without additional configuration.
  *
  * **Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated
@@ -82,63 +82,45 @@ export default class Link extends Plugin {
  * 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.
+ * * {@link module:link/link~LinkDecoratorAutomaticOption automatic} – they match links against pre–defined rules and
+ * manage their attributes based on the results,
+ * * {@link module:link/link~LinkDecoratorManualOption manual} – they allow users to control link attributes individually
+ *  using the editor UI.
+ *
+ * Link decorators are defined as an array of objects:
+ *
+ *		const linkConfig = {
+ *			decorators: [
+ *				{
+ *					mode: 'automatic',
+ *					callback: url => url.startsWith( 'http://' ),
+ *					attributes: {
+ *						target: '_blank',
+ *						rel: 'noopener noreferrer'
+ *					}
+ *				},
+ *				{
+ *					mode: 'manual',
+ *					label: 'Downloadable',
+ *					attributes: {
+ *						download: 'file.png',
+ *					}
+ *				},
+ *				// ...
+ *			]
+ *		}
  *
- * For example, to add the `target="_blank"` attribute to all links starting with the `http://` in the content,
- * the configuration could look as follows:
+ * To learn more about the configuration syntax, check out the {@link module:link/link~LinkDecoratorAutomaticOption automatic}
+ * and {@link module:link/link~LinkDecoratorManualOption manual} decorator option reference.
  *
- *		const link.decorators = [
- *			{
- *				mode: 'automatic',
- *				callback: url => url.startsWith( 'http://' ),
- *				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 results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
  *
  * **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
  */
@@ -148,6 +130,9 @@ export default class Link extends Plugin {
  * 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 callback function which must return a boolean based on link's
+ * `href` (URL). When the callback returns `true`, attributes are applied to the link.
+ *
  * For example, to add the `target="_blank"` attribute to all links in the editor starting with the `http://`,
  * then configuration could look like this:
  *