link.js 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module link/link
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import LinkEditing from './linkediting';
  10. import LinkUI from './linkui';
  11. /**
  12. * The link plugin.
  13. *
  14. * This is a "glue" plugin which loads the {@link module:link/linkediting~LinkEditing link editing feature}
  15. * and {@link module:link/linkui~LinkUI link UI feature}.
  16. *
  17. * @extends module:core/plugin~Plugin
  18. */
  19. export default class Link extends Plugin {
  20. /**
  21. * @inheritDoc
  22. */
  23. static get requires() {
  24. return [ LinkEditing, LinkUI ];
  25. }
  26. /**
  27. * @inheritDoc
  28. */
  29. static get pluginName() {
  30. return 'Link';
  31. }
  32. }
  33. /**
  34. * The configuration of the {@link module:link/link~Link} feature.
  35. *
  36. * Read more in {@link module:link/link~LinkConfig}.
  37. *
  38. * @member {module:link/link~LinkConfig} module:core/editor/editorconfig~EditorConfig#link
  39. */
  40. /**
  41. * The configuration of the {@link module:link/link~Link link feature}.
  42. *
  43. * ClassicEditor
  44. * .create( editorElement, {
  45. * link: ... // Link feature configuration.
  46. * } )
  47. * .then( ... )
  48. * .catch( ... );
  49. *
  50. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  51. * @interface LinkConfig
  52. */
  53. /**
  54. * When set `true`, the `target="blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links
  55. * in the editor. By external are meant all links in the editor content starting with `http`, `https`, or `//`.
  56. *
  57. * Internally, this option activates a predefined {@link module:link/link~LinkConfig#decorators automatic link decorator},
  58. * which extends all external links with the `target` and `rel` attributes without additional configuration.
  59. *
  60. * **Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated
  61. * {@link module:link/link~LinkDecoratorManualOption manual} decorator must be defined in the
  62. * {@link module:link/link~LinkConfig#decorators `config.link.decodators`} array. In such scenario,
  63. * the `config.link.targetDecorator` option should remain `undefined` or `false` to not interfere with the manual decorator.
  64. *
  65. * **Note**: It is possible to add other {@link module:link/link~LinkDecoratorAutomaticOption automatic}
  66. * or {@link module:link/link~LinkDecoratorManualOption manual} link decorators when this option is active.
  67. *
  68. * More information about decorators can be found in the {@link module:link/link~LinkConfig#decorators decorators configuration}
  69. * reference.
  70. *
  71. * @member {Boolean} module:link/link~LinkConfig#targetDecorator
  72. */
  73. /**
  74. * Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are
  75. * two types of link decorators:
  76. *
  77. * * {@link module:link/link~LinkDecoratorAutomaticOption automatic} – they match links against pre–defined rules and
  78. * manage their attributes based on the results,
  79. * * {@link module:link/link~LinkDecoratorManualOption manual} – they allow users to control link attributes individually
  80. * using the editor UI.
  81. *
  82. * Link decorators are defined as an array of objects:
  83. *
  84. * const linkConfig = {
  85. * decorators: [
  86. * {
  87. * mode: 'automatic',
  88. * callback: url => url.startsWith( 'http://' ),
  89. * attributes: {
  90. * target: '_blank',
  91. * rel: 'noopener noreferrer'
  92. * }
  93. * },
  94. * {
  95. * mode: 'manual',
  96. * label: 'Downloadable',
  97. * attributes: {
  98. * download: 'file.png',
  99. * }
  100. * },
  101. * // ...
  102. * ]
  103. * }
  104. *
  105. * To learn more about the configuration syntax, check out the {@link module:link/link~LinkDecoratorAutomaticOption automatic}
  106. * and {@link module:link/link~LinkDecoratorManualOption manual} decorator option reference.
  107. *
  108. * **Warning:** Currently, link decorators work independently and no conflict resolution mechanism exists.
  109. * For example, configuring the `target` attribute using both an automatic and a manual decorator at a time could end up with a
  110. * quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
  111. *
  112. * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
  113. * dedicated for that purpose which can be enabled by turning a single option on. Check out the
  114. * {@link module:link/link~LinkConfig#targetDecorator `config.link.targetDecorator`} configuration description to learn more.
  115. *
  116. * @member {Array.<module:link/link~LinkDecoratorAutomaticOption|module:link/link~LinkDecoratorManualOption>}
  117. * module:link/link~LinkConfig#decorators
  118. */
  119. /**
  120. * Describes an automatic link {@link module:link/link~LinkConfig#decorators decorator}. This kind of a decorator matches
  121. * all links in the editor content against a function which decides whether the link should gain a pre–defined set of attributes
  122. * or not.
  123. *
  124. * It takes an object with key-value pairs of attributes and a callback function which must return a boolean based on link's
  125. * `href` (URL). When the callback returns `true`, attributes are applied to the link.
  126. *
  127. * For example, to add the `target="_blank"` attribute to all links in the editor starting with the `http://`,
  128. * then configuration could look like this:
  129. *
  130. * {
  131. * mode: 'automatic',
  132. * callback: url => url.startsWith( 'http://' ),
  133. * attributes: {
  134. * target: '_blank'
  135. * }
  136. * }
  137. *
  138. * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
  139. * dedicated for that purpose which can be enabled by turning a single option on. Check out the
  140. * {@link module:link/link~LinkConfig#targetDecorator `config.link.targetDecorator`} configuration description to learn more.
  141. *
  142. * @typedef {Object} module:link/link~LinkDecoratorAutomaticOption
  143. * @property {'automatic'} mode The kind of the decorator. `'automatic'` for all automatic decorators.
  144. * @property {Function} callback Takes an `url` as a parameter and returns `true` if the `attributes` should be applied to the link.
  145. * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  146. * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  147. * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  148. */
  149. /**
  150. * Describes a manual link {@link module:link/link~LinkConfig#decorators decorator}. This kind of a decorator is represented in
  151. * the link feature's {@link module:link/linkui user interface} as a switch the user can use to control the presence
  152. * of a pre–defined set of attributes.
  153. *
  154. * For instance, to allow users to manually control the presence of the `target="_blank"` and
  155. * `rel="noopener noreferrer"` attributes on specific links, the decorator could look as follows:
  156. *
  157. * {
  158. * mode: 'manual',
  159. * label: 'Open link in new window',
  160. * attributes: {
  161. * target: '_blank',
  162. * rel: 'noopener noreferrer'
  163. * }
  164. * }
  165. *
  166. * @typedef {Object} module:link/link~LinkDecoratorManualOption
  167. * @property {'automatic'} mode The kind of the decorator. `'manual'` for all manual decorators.
  168. * @property {String} label The label of the UI button the user can use to control the presence of link attributes.
  169. * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  170. * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  171. * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  172. */