|
@@ -5,7 +5,7 @@ category: features
|
|
|
|
|
|
|
|
{@snippet features/build-link-source}
|
|
{@snippet features/build-link-source}
|
|
|
|
|
|
|
|
-The {@link module:link/link~Link} feature brings support for link editing to the editor. It allows for inserting hyperlinks into the edited content and offers the UI to create and edit them.
|
|
|
|
|
|
|
+The {@link module:link/link~Link} feature brings support for link editing to the rich-text editor. It allows for inserting hyperlinks into the edited content and offers the UI to create and edit them.
|
|
|
|
|
|
|
|
## Demo
|
|
## Demo
|
|
|
|
|
|
|
@@ -27,13 +27,15 @@ CKEditor 5 allows for typing both at inner and outer boundaries of links to make
|
|
|
|
|
|
|
|
## Custom link attributes (decorators)
|
|
## Custom link attributes (decorators)
|
|
|
|
|
|
|
|
-By default, all links created in the editor have the `href="..."` attribute in the {@link builds/guides/integration/basic-api#getting-the-editor-data editor data}. If you want your links to have additional link attributes, {@link module:link/link~LinkConfig#decorators link decorators} provide an easy way to configure and manage them. There are two types of link decorators you can make use of:
|
|
|
|
|
|
|
+By default, all links created in the editor have the `href="..."` attribute in the {@link builds/guides/integration/basic-api#getting-the-editor-data editor data}. If you want your links to have additional link attributes, {@link module:link/link~LinkConfig#decorators link decorators} provide an easy way to configure and manage them.
|
|
|
|
|
|
|
|
-* [**automatic**](#adding-attributes-to-links-based-on-predefined-rules-automatic-decorators) – they match links against pre–defined rules and manage their attributes based on the results,
|
|
|
|
|
-* [**manual**](#adding-attributes-to-links-using-the-ui-manual-decorators) – they allow users to control link attributes individually using the editor UI.
|
|
|
|
|
|
|
+There are two types of link decorators you can use:
|
|
|
|
|
+
|
|
|
|
|
+* [**Automatic**](#adding-attributes-to-links-based-on-predefined-rules-automatic-decorators) – They match links against pre–defined rules and manage their attributes based on the results.
|
|
|
|
|
+* [**Manual**](#adding-attributes-to-links-using-the-ui-manual-decorators) – They allow users to control link attributes individually using the editor UI.
|
|
|
|
|
|
|
|
<info-box>
|
|
<info-box>
|
|
|
- Link decorators are disabled by default and it takes a proper [configuration](#configuration) to enable them in your editor. If you do not want to use them in your application, you do not need to do anything.
|
|
|
|
|
|
|
+ Link decorators are disabled by default and it takes a proper [configuration](#configuration) to enable them in your rich-text editor.
|
|
|
</info-box>
|
|
</info-box>
|
|
|
|
|
|
|
|
### Demo
|
|
### Demo
|
|
@@ -57,7 +59,7 @@ ClassicEditor
|
|
|
// Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
|
|
// Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
|
|
|
addTargetToExternalLinks: true,
|
|
addTargetToExternalLinks: true,
|
|
|
|
|
|
|
|
- // Allow users control the "download" attribute of each link.
|
|
|
|
|
|
|
+ // Let the users control the "download" attribute of each link.
|
|
|
decorators: [
|
|
decorators: [
|
|
|
{
|
|
{
|
|
|
mode: 'manual',
|
|
mode: 'manual',
|
|
@@ -75,15 +77,17 @@ ClassicEditor
|
|
|
|
|
|
|
|
### Configuration
|
|
### Configuration
|
|
|
|
|
|
|
|
-Decorators are configured via definitions in {@link module:link/link~LinkConfig#decorators `config.link.decorators`}. Each decorator definition must have its own unique name. In case of [manual decorators](#adding-attributes-to-links-using-the-ui-manual-decorators), that name also represents the decorator in the {@link framework/guides/architecture/editing-engine#text-attributes document model}.
|
|
|
|
|
|
|
+Decorators are configured through definitions provided in the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration option.
|
|
|
|
|
+
|
|
|
|
|
+Each decorator definition must have its own unique name. In case of [manual decorators](#adding-attributes-to-links-using-the-ui-manual-decorators), that name also represents the decorator in the {@link framework/guides/architecture/editing-engine#text-attributes document model}.
|
|
|
|
|
|
|
|
<info-box warning>
|
|
<info-box warning>
|
|
|
- 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 quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
|
|
|
|
|
|
|
+ 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.
|
|
|
</info-box>
|
|
</info-box>
|
|
|
|
|
|
|
|
#### Adding `target` and `rel` attributes to external links
|
|
#### Adding `target` and `rel` attributes to external links
|
|
|
|
|
|
|
|
-A very common use case for (automatic) link decorators is adding `target="_blank"` and `rel="noopener noreferrer"` attributes to all external links in the document. A dedicated {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`} configuration has been created for that purpose. When this option is set `true`, all links starting with `http://`, `https://` or `//` are "decorated" with `target` and `rel` attributes.
|
|
|
|
|
|
|
+A very common use case for (automatic) link decorators is adding `target="_blank"` and `rel="noopener noreferrer"` attributes to all external links in the document. A dedicated {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`} configuration has been created for that purpose. When this option is set to `true`, all links starting with `http://`, `https://` or `//` are "decorated" with `target` and `rel` attributes.
|
|
|
|
|
|
|
|
```js
|
|
```js
|
|
|
ClassicEditor
|
|
ClassicEditor
|
|
@@ -120,7 +124,7 @@ ClassicEditor
|
|
|
.catch( ... );
|
|
.catch( ... );
|
|
|
```
|
|
```
|
|
|
|
|
|
|
|
-**Note**: If you want to leave the decision whether a link should open in new tab to the users, do not use the `config.link.addTargetToExternalLinks` configuration but define a new [manual decorator](#adding-attributes-to-links-using-the-ui-manual-decorators) with the proper definition:
|
|
|
|
|
|
|
+If you want to leave the decision whether a link should open in a new tab to the users, do not use the `config.link.addTargetToExternalLinks` configuration but define a new [manual decorator](#adding-attributes-to-links-using-the-ui-manual-decorators) with the following definition instead:
|
|
|
|
|
|
|
|
```js
|
|
```js
|
|
|
ClassicEditor
|
|
ClassicEditor
|
|
@@ -145,7 +149,7 @@ ClassicEditor
|
|
|
|
|
|
|
|
#### Adding attributes to links based on pre–defined rules (automatic decorators)
|
|
#### Adding attributes to links based on pre–defined rules (automatic decorators)
|
|
|
|
|
|
|
|
-Automatic link decorators match all links in the editor content against a {@link module:link/link~LinkDecoratorAutomaticDefinition function} which decides whether the link should gain some set of attributes or not, considering the URL (`href`) of the link. These decorators work silently being applied during {@link framework/guides/architecture/editing-engine#conversion data downcast} only.
|
|
|
|
|
|
|
+Automatic link decorators match all links in the editor content against a {@link module:link/link~LinkDecoratorAutomaticDefinition function} which decides whether the link should receive some set of attributes, considering the URL (`href`) of the link. These decorators work silently and are being applied during the {@link framework/guides/architecture/editing-engine#conversion data downcast} only.
|
|
|
|
|
|
|
|
For instance, to create an automatic decorator that adds the `download="file.pdf"` attribute to all links ending with the `".pdf"` extension, you should add the following {@link module:link/link~LinkDecoratorAutomaticDefinition definition} to {@link module:link/link~LinkConfig#decorators `config.link.decorators`}:
|
|
For instance, to create an automatic decorator that adds the `download="file.pdf"` attribute to all links ending with the `".pdf"` extension, you should add the following {@link module:link/link~LinkDecoratorAutomaticDefinition definition} to {@link module:link/link~LinkConfig#decorators `config.link.decorators`}:
|
|
|
|
|
|
|
@@ -170,12 +174,12 @@ ClassicEditor
|
|
|
```
|
|
```
|
|
|
|
|
|
|
|
<info-box>
|
|
<info-box>
|
|
|
- If you want `target` and `rel` attributes to be added to all external links in your content, we prepared a [dedicated configuration](#adding-target-and-rel-attributes-to-external-links) exactly for that purpose so you do not have to define the automatic decorator by yourself.
|
|
|
|
|
|
|
+ If you want the `target` and `rel` attributes to be added to all external links in your content, we prepared a [dedicated configuration](#adding-target-and-rel-attributes-to-external-links) exactly for that purpose so you do not have to define the automatic decorator by yourself.
|
|
|
</info-box>
|
|
</info-box>
|
|
|
|
|
|
|
|
#### Adding attributes to links using the UI (manual decorators)
|
|
#### Adding attributes to links using the UI (manual decorators)
|
|
|
|
|
|
|
|
-Manual link decorators are represented in the link editing balloon as switch buttons users can use to control the presence of attributes of a particular link (check out the [demo](#demo) to learn more). Each manual decorator {@link module:link/link~LinkDecoratorManualDefinition definition} contains a human–readable label displayed next to the switch button in the link editing balloon. Make sure it is compact and precise for the convenience of the users.
|
|
|
|
|
|
|
+Manual link decorators are represented in the link editing balloon as switch buttons that the users can use to control the presence of attributes of a particular link (check out the [demo](#demo) to learn more). Each manual decorator {@link module:link/link~LinkDecoratorManualDefinition definition} contains a human–readable label displayed next to the switch button in the link editing balloon. Make sure it is compact and precise for the convenience of the users.
|
|
|
|
|
|
|
|
To configure a "Downloadable" switch button in the link editing balloon that adds the `download="file"` attribute to the link when turned on, add the following definition to {@link module:link/link~LinkConfig#decorators `config.link.decorators`}:
|
|
To configure a "Downloadable" switch button in the link editing balloon that adds the `download="file"` attribute to the link when turned on, add the following definition to {@link module:link/link~LinkConfig#decorators `config.link.decorators`}:
|
|
|
|
|
|
|
@@ -246,7 +250,7 @@ editor.execute( 'link', 'http://example.com', { linkIsExternal: true } );
|
|
|
editor.execute( 'unlink' );
|
|
editor.execute( 'unlink' );
|
|
|
```
|
|
```
|
|
|
|
|
|
|
|
-Links are represented in the {@link module:engine/model/model~Model model} using the `linkHref` attribute. [Manual link decorators](#adding-attributes-to-links-using-the-ui-manual-decorators) are represented in the model using text attributes corresponding to their names as configured in {@link module:link/link~LinkConfig#decorators `config.link.decorators`}.
|
|
|
|
|
|
|
+Links are represented in the {@link module:engine/model/model~Model model} using the `linkHref` attribute. [Manual link decorators](#adding-attributes-to-links-using-the-ui-manual-decorators) are represented in the model using text attributes corresponding to their names, as configured in {@link module:link/link~LinkConfig#decorators `config.link.decorators`}.
|
|
|
|
|
|
|
|
<info-box>
|
|
<info-box>
|
|
|
We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
|
|
We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
|