This repository has been archived by the owner on Jun 26, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 29
/
link.js
225 lines (213 loc) · 9.09 KB
/
link.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
/**
* @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module link/link
*/
import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
import LinkEditing from './linkediting';
import LinkUI from './linkui';
/**
* The link plugin.
*
* This is a "glue" plugin that loads the {@link module:link/linkediting~LinkEditing link editing feature}
* and {@link module:link/linkui~LinkUI link UI feature}.
*
* @extends module:core/plugin~Plugin
*/
export default class Link extends Plugin {
/**
* @inheritDoc
*/
static get requires() {
return [ LinkEditing, LinkUI ];
}
/**
* @inheritDoc
*/
static get pluginName() {
return 'Link';
}
}
/**
* The configuration of the {@link module:link/link~Link} feature.
*
* Read more in {@link module:link/link~LinkConfig}.
*
* @member {module:link/link~LinkConfig} module:core/editor/editorconfig~EditorConfig#link
*/
/**
* The configuration of the {@link module:link/link~Link link feature}.
*
* ClassicEditor
* .create( editorElement, {
* link: ... // Link feature configuration.
* } )
* .then( ... )
* .catch( ... );
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
* @interface LinkConfig
*/
/**
* When set to `true`, the `target="blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links
* in the editor. "External links" are all links in the editor content starting with `http`, `https`, or `//`.
*
* ClassicEditor
* .create( editorElement, {
* link: {
* addTargetToExternalLinks: true
* }
* } )
* .then( ... )
* .catch( ... );
*
* Internally, this option activates a predefined {@link module:link/link~LinkConfig#decorators automatic link decorator}
* that extends all external links with the `target` and `rel` attributes.
*
* **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.decorators`} array. In such scenario,
* the `config.link.addTargetToExternalLinks` option should remain `undefined` or `false` to not interfere with the manual decorator.
*
* It is possible to add other {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
* or {@link module:link/link~LinkDecoratorManualDefinition 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.
*
* @default false
* @member {Boolean} module:link/link~LinkConfig#addTargetToExternalLinks
*/
/**
* Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are
* two types of link decorators:
*
* * {@link module:link/link~LinkDecoratorAutomaticDefinition Automatic} – They match links against pre–defined rules and
* manage their attributes based on the results.
* * {@link module:link/link~LinkDecoratorManualDefinition Manual} – They allow users to control link attributes individually,
* using the editor UI.
*
* Link decorators are defined as objects with key-value pairs, where the key is the name provided for a given decorator and the
* value is the decorator definition.
*
* The name of the decorator also corresponds to the {@glink framework/guides/architecture/editing-engine#text-attributes text attribute}
* in the model. For instance, the `isExternal` decorator below is represented as a `linkIsExternal` attribute in the model.
*
* ClassicEditor
* .create( editorElement, {
* link: {
* decorators: {
* isExternal: {
* mode: 'automatic',
* callback: url => url.startsWith( 'http://' ),
* attributes: {
* target: '_blank',
* rel: 'noopener noreferrer'
* }
* },
* isDownloadable: {
* mode: 'manual',
* label: 'Downloadable',
* attributes: {
* download: 'file.png',
* }
* },
* // ...
* }
* }
* } )
* .then( ... )
* .catch( ... );
*
* To learn more about the configuration syntax, check out the {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
* and {@link module:link/link~LinkDecoratorManualDefinition manual} decorator option reference.
*
* **Warning:** Currently, link decorators work independently of one another and no conflict resolution mechanism exists.
* For example, configuring the `target` attribute using both an automatic and a manual decorator at the same time could end up with
* 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#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
* configuration description to learn more.
*
* See also the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
*
* @member {Object.<String, module:link/link~LinkDecoratorDefinition>} module:link/link~LinkConfig#decorators
*/
/**
* A link decorator definition. Two types implement this defition:
*
* * {@link module:link/link~LinkDecoratorManualDefinition}
* * {@link module:link/link~LinkDecoratorAutomaticDefinition}
*
* Refer to their document for more information about available options or to the
* {@glink features/link#custom-link-attributes-decorators link feature guide} for general information.
*
* @interface LinkDecoratorDefinition
*/
/**
* Link decorator type.
*
* Check out the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
*
* @member {'manual'|'automatic'} module:link/link~LinkDecoratorDefinition#mode
*/
/**
* Describes an automatic {@link module:link/link~LinkConfig#decorators link decorator}. This decorator type matches
* all links in the editor content against a function that decides whether the link should receive a pre–defined set of attributes.
*
* It takes an object with key-value pairs of attributes and a callback function that must return a Boolean value based on the 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 `http://`, the
* configuration could look like this:
*
* {
* 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 that can be enabled by turning a single option on. Check out the
* {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
* configuration description to learn more.
*
* @typedef {Object} module:link/link~LinkDecoratorAutomaticDefinition
* @property {'automatic'} mode Link decorator type. It is `'automatic'` for all automatic decorators.
* @property {Function} callback Takes a `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 follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
*/
/**
* Describes a manual {@link module:link/link~LinkConfig#decorators link decorator}. This decorator type is represented in
* the link feature's {@link module:link/linkui user interface} as a switch that the user can use to control the presence
* of a predefined set of attributes.
*
* For instance, to allow the 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 in a new tab',
* defaultValue: true,
* attributes: {
* target: '_blank',
* rel: 'noopener noreferrer'
* }
* }
*
* @typedef {Object} module:link/link~LinkDecoratorManualDefinition
* @property {'manual'} mode Link decorator type. It is `'manual'` for all manual decorators.
* @property {String} label The label of the UI button that 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 follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
* @property {Boolean} [defaultValue] Controls whether the decorator is "on" by default.
*/