diff --git a/docs/features/link.md b/docs/features/link.md index bd636da..ccf7b55 100644 --- a/docs/features/link.md +++ b/docs/features/link.md @@ -5,7 +5,7 @@ category: features {@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 @@ -27,13 +27,15 @@ CKEditor 5 allows for typing both at inner and outer boundaries of links to make ## 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. - 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. ### Demo @@ -57,7 +59,7 @@ ClassicEditor // Automatically add target="_blank" and rel="noopener noreferrer" to all external links. addTargetToExternalLinks: true, - // Allow users control the "download" attribute of each link. + // Let the users control the "download" attribute of each link. decorators: [ { mode: 'manual', @@ -75,15 +77,17 @@ ClassicEditor ### 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}. - 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. #### 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 ClassicEditor @@ -120,7 +124,7 @@ ClassicEditor .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 ClassicEditor @@ -130,7 +134,7 @@ ClassicEditor decorators: { addTargetToLinks: { mode: 'manual', - label: 'Open link in a new tab', + label: 'Open in a new tab', attributes: { target: '_blank', rel: 'noopener noreferrer' @@ -145,7 +149,7 @@ ClassicEditor #### 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`}: @@ -170,12 +174,12 @@ ClassicEditor ``` - 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. #### 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`}: @@ -246,7 +250,7 @@ editor.execute( 'link', 'http://example.com', { linkIsExternal: true } ); 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`}. 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. diff --git a/src/link.js b/src/link.js index db36123..7d881d3 100644 --- a/src/link.js +++ b/src/link.js @@ -14,7 +14,7 @@ import LinkUI from './linkui'; /** * The link plugin. * - * This is a "glue" plugin which loads the {@link module:link/linkediting~LinkEditing link editing feature} + * 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 @@ -58,8 +58,8 @@ 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 `//`. + * 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, { @@ -70,15 +70,15 @@ export default class Link extends Plugin { * .then( ... ) * .catch( ... ); * - * 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. + * 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. * - * **Note**: It is possible to add other {@link module:link/link~LinkDecoratorAutomaticDefinition automatic} + * 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} @@ -92,12 +92,12 @@ 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: * - * * {@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 + * * {@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 an object with key-value pairs, where the key is a name provided for a given decorator and the + * 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} @@ -132,8 +132,8 @@ export default class Link extends Plugin { * 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 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 + * **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 @@ -141,7 +141,7 @@ export default class Link extends Plugin { * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`} * configuration description to learn more. * - * See also {@glink features/link#custom-link-attributes-decorators link's feature} guide for more information. + * See also the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information. * * @member {Object.} module:link/link~LinkConfig#decorators */ @@ -154,23 +154,22 @@ export default class Link extends Plugin { */ /** - * The kind of the decorator. + * Link decorator type. * - * Check out the {@glink features/link#custom-link-attributes-decorators link feature} guide for more information. + * 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 {@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. + * 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 which must return a boolean based on link's + * 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 the `http://`, - * then configuration could look like this: + * 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', @@ -181,24 +180,24 @@ export default class Link extends Plugin { * } * * **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 + * 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 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 {'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 {@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. + * 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 users to manually control the presence of the `target="_blank"` and + * 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: * * { @@ -211,8 +210,8 @@ export default class Link extends Plugin { * } * * @typedef {Object} module:link/link~LinkDecoratorManualDefinition - * @property {'manual'} 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 {'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. diff --git a/src/linkcommand.js b/src/linkcommand.js index 6334d55..f1d1f14 100644 --- a/src/linkcommand.js +++ b/src/linkcommand.js @@ -33,7 +33,7 @@ export default class LinkCommand extends Command { * A collection of {@link module:link/utils~ManualDecorator manual decorators} * corresponding to the {@link module:link/link~LinkConfig#decorators decorator configuration}. * - * You can consider it a model with states of manual decorators added to currently selected link. + * You can consider it a model with states of manual decorators added to the currently selected link. * * @readonly * @type {module:utils/collection~Collection} @@ -42,7 +42,7 @@ export default class LinkCommand extends Command { } /** - * Synchronize state of {@link #manualDecorators} with actually present elements in the model. + * Synchronizes the state of {@link #manualDecorators} with the currently present elements in the model. */ restoreManualDecoratorStates() { for ( const manualDecorator of this.manualDecorators ) { @@ -72,8 +72,8 @@ export default class LinkCommand extends Command { * When the selection is non-collapsed, the `linkHref` attribute will be applied to nodes inside the selection, but only to * those nodes where the `linkHref` attribute is allowed (disallowed nodes will be omitted). * - * When the selection is collapsed and is not inside the text with the `linkHref` attribute, the - * new {@link module:engine/model/text~Text Text node} with the `linkHref` attribute will be inserted in place of caret, but + * When the selection is collapsed and is not inside the text with the `linkHref` attribute, a + * new {@link module:engine/model/text~Text text node} with the `linkHref` attribute will be inserted in place of the caret, but * only if such element is allowed in this place. The `_data` of the inserted text will equal the `href` parameter. * The selection will be updated to wrap the just inserted text node. * @@ -81,18 +81,18 @@ export default class LinkCommand extends Command { * * # Decorators and model attribute management * - * There is an optional argument to this command, which applies or removes model + * There is an optional argument to this command that applies or removes model * {@glink framework/guides/architecture/editing-engine#text-attributes text attributes} brought by * {@link module:link/utils~ManualDecorator manual link decorators}. * * Text attribute names in the model correspond to the entries in the {@link module:link/link~LinkConfig#decorators configuration}. * For every decorator configured, a model text attribute exists with the "link" prefix. For example, a `'linkMyDecorator'` attribute - * corresponds to the `'myDecorator'` in the configuration. + * corresponds to `'myDecorator'` in the configuration. * * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} * documentation. * - * Here is how to manage decorator attributes via the link command: + * Here is how to manage decorator attributes with the link command: * * const linkCommand = editor.commands.get( 'link' ); * @@ -101,25 +101,25 @@ export default class LinkCommand extends Command { * linkIsExternal: true * } ); * - * // Removing a decorator attribute from a selection. + * // Removing a decorator attribute from the selection. * linkCommand.execute( 'http://example.com', { * linkIsExternal: false * } ); * - * // Adding multiple decorator attributes at a time. + * // Adding multiple decorator attributes at the same time. * linkCommand.execute( 'http://example.com', { * linkIsExternal: true, * linkIsDownloadable: true, * } ); * - * // Removing and adding decorator attributes at a time. + * // Removing and adding decorator attributes at the same time. * linkCommand.execute( 'http://example.com', { * linkIsExternal: false, * linkFoo: true, * linkIsDownloadable: false, * } ); * - * **Note**: If decorator attribute name is not specified its state remains untouched. + * **Note**: If the decorator attribute name is not specified, its state remains untouched. * * **Note**: {@link module:link/unlinkcommand~UnlinkCommand#execute `UnlinkCommand#execute()`} removes all * decorator attributes. @@ -206,11 +206,11 @@ export default class LinkCommand extends Command { } /** - * Method provides the information if a decorator with given name is present in currently processed selection. + * Provides information whether a decorator with a given name is present in the currently processed selection. * * @private - * @param {String} decoratorName name of a manual decorator used in the model - * @returns {Boolean} The information if a given decorator is currently present in a selection + * @param {String} decoratorName The name of the manual decorator used in the model + * @returns {Boolean} The information whether a given decorator is currently present in the selection. */ _getDecoratorStateFromModel( decoratorName ) { const doc = this.editor.model.document; diff --git a/src/linkediting.js b/src/linkediting.js index deec637..19974cf 100644 --- a/src/linkediting.js +++ b/src/linkediting.js @@ -102,7 +102,7 @@ export default class LinkEditing extends Plugin { * for each one of them. Downcast dispatchers are obtained using the * {@link module:link/utils~AutomaticDecorators#getDispatcher} method. * - * **Note**: This method also activates the automatic external link decorator if enabled via + * **Note**: This method also activates the automatic external link decorator if enabled with * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}. * * @private @@ -112,7 +112,7 @@ export default class LinkEditing extends Plugin { const editor = this.editor; const automaticDecorators = new AutomaticDecorators(); - // Adds default decorator for external links. + // Adds a default decorator for external links. if ( editor.config.get( 'link.addTargetToExternalLinks' ) ) { automaticDecorators.add( { id: 'linkIsExternal', @@ -133,11 +133,11 @@ export default class LinkEditing extends Plugin { } /** - * Processes an array of configured {@link module:link/link~LinkDecoratorManualDefinition manual decorators} - * and transforms them into {@link module:link/utils~ManualDecorator} instances and stores them in the + * Processes an array of configured {@link module:link/link~LinkDecoratorManualDefinition manual decorators}, + * transforms them into {@link module:link/utils~ManualDecorator} instances and stores them in the * {@link module:link/linkcommand~LinkCommand#manualDecorators} collection (a model for manual decorators state). * - * Also registers an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attributeToElement} + * Also registers an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attribute-to-element} * converter for each manual decorator and extends the {@link module:engine/model/schema~Schema model's schema} * with adequate model attributes. * @@ -187,13 +187,13 @@ export default class LinkEditing extends Plugin { * Adds a visual highlight style to a link in which the selection is anchored. * Together with two-step caret movement, they indicate that the user is typing inside the link. * - * Highlight is turned on by adding `.ck-link_selected` class to the link in the view: + * Highlight is turned on by adding the `.ck-link_selected` class to the link in the view: * - * * the class is removed before conversion has started, as callbacks added with `'highest'` priority - * to {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} events, - * * the class is added in the view post fixer, after other changes in the model tree were converted to the view. + * * The class is removed before the conversion has started, as callbacks added with the `'highest'` priority + * to {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} events. + * * The class is added in the view post fixer, after other changes in the model tree were converted to the view. * - * This way, adding and removing highlight does not interfere with conversion. + * This way, adding and removing the highlight does not interfere with conversion. * * @private */ diff --git a/src/linkui.js b/src/linkui.js index 391d576..34be89d 100644 --- a/src/linkui.js +++ b/src/linkui.js @@ -138,7 +138,7 @@ export default class LinkUI extends Plugin { * Creates the {@link module:link/ui/linkformview~LinkFormView} instance. * * @private - * @returns {module:link/ui/linkformview~LinkFormView} The link form instance. + * @returns {module:link/ui/linkformview~LinkFormView} The link form view instance. */ _createFormView() { const editor = this.editor; @@ -313,19 +313,19 @@ export default class LinkUI extends Plugin { } /** - * Closes form view. Decides whether the balloon should be hidden completely or if action view should be shown. This is decided upon - * link command value (which has value if the document selection is in link). + * Closes the form view. Decides whether the balloon should be hidden completely or if the action view should be shown. This is + * decided upon the link command value (which has a value if the document selection is in the link). * - * If there are defined {@link module:link/link~LinkConfig#decorators} in editor's config, then there are additionally - * rest switch buttons state responsible for manual decorators handling. + * Additionally, if any {@link module:link/link~LinkConfig#decorators} are defined in the editor configuration, the state of + * switch buttons responsible for manual decorator handling is restored. * * @private */ _closeFormView() { const linkCommand = this.editor.commands.get( 'link' ); - // Reset manual decorator states to represent current model state. This case is important to reset switch buttons, - // when user cancel editing form. + // Restore manual decorator states to represent the current model state. This case is important to reset the switch buttons + // when the user cancels the editing form. linkCommand.restoreManualDecoratorStates(); if ( linkCommand.value !== undefined ) { @@ -355,7 +355,7 @@ export default class LinkUI extends Plugin { } /** - * Shows the right kind of the UI for current state of the command. It's either + * Shows the correct UI type for the current state of the command. It is either * {@link #formView} or {@link #actionsView}. * * @param {Boolean} forceVisible @@ -431,7 +431,7 @@ export default class LinkUI extends Plugin { /** * Makes the UI react to the {@link module:core/editor/editorui~EditorUI#event:update} event to - * reposition itself when the editor ui should be refreshed. + * reposition itself when the editor UI should be refreshed. * * See: {@link #_hideUI} to learn when the UI stops reacting to the `update` event. * @@ -488,7 +488,7 @@ export default class LinkUI extends Plugin { } /** - * Returns true when {@link #formView} is in the {@link #_balloon}. + * Returns `true` when {@link #formView} is in the {@link #_balloon}. * * @readonly * @protected @@ -499,7 +499,7 @@ export default class LinkUI extends Plugin { } /** - * Returns true when {@link #actionsView} is in the {@link #_balloon}. + * Returns `true` when {@link #actionsView} is in the {@link #_balloon}. * * @readonly * @protected @@ -510,7 +510,7 @@ export default class LinkUI extends Plugin { } /** - * Returns true when {@link #actionsView} is in the {@link #_balloon} and it is + * Returns `true` when {@link #actionsView} is in the {@link #_balloon} and it is * currently visible. * * @readonly @@ -522,7 +522,7 @@ export default class LinkUI extends Plugin { } /** - * Returns true when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}. + * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}. * * @readonly * @protected @@ -533,7 +533,7 @@ export default class LinkUI extends Plugin { } /** - * Returns true when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is + * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is * currently visible. * * @readonly @@ -575,7 +575,7 @@ export default class LinkUI extends Plugin { * the {@link module:engine/view/document~Document editing view's} selection or `null` * if there is none. * - * **Note**: For a non–collapsed selection the link element is only returned when **fully** + * **Note**: For a non–collapsed selection, the link element is only returned when **fully** * selected and the **only** element within the selection boundaries. * * @private diff --git a/src/ui/linkactionsview.js b/src/ui/linkactionsview.js index 886b546..cfeeee2 100644 --- a/src/ui/linkactionsview.js +++ b/src/ui/linkactionsview.js @@ -23,7 +23,7 @@ import pencilIcon from '@ckeditor/ckeditor5-core/theme/icons/pencil.svg'; import '../../theme/linkactions.css'; /** - * The link actions view class. This view displays link preview, allows + * The link actions view class. This view displays the link preview, allows * unlinking or editing the link. * * @extends module:ui/view~View @@ -75,7 +75,7 @@ export default class LinkActionsView extends View { this.editButtonView = this._createButton( t( 'Edit link' ), pencilIcon, 'edit' ); /** - * Value of the "href" attribute of the link to use in the {@link #previewButtonView}. + * The value of the "href" attribute of the link to use in the {@link #previewButtonView}. * * @observable * @member {String} @@ -83,7 +83,7 @@ export default class LinkActionsView extends View { this.set( 'href' ); /** - * A collection of views which can be focused in the view. + * A collection of views that can be focused in the view. * * @readonly * @protected @@ -168,7 +168,7 @@ export default class LinkActionsView extends View { * * @private * @param {String} label The button label. - * @param {String} icon The button's icon. + * @param {String} icon The button icon. * @param {String} [eventName] An event name that the `ButtonView#execute` event will be delegated to. * @returns {module:ui/button/buttonview~ButtonView} The button view instance. */ diff --git a/src/ui/linkformview.js b/src/ui/linkformview.js index f1de78e..22a3294 100644 --- a/src/ui/linkformview.js +++ b/src/ui/linkformview.js @@ -96,7 +96,7 @@ export default class LinkFormView extends View { this._manualDecoratorSwitches = this._createManualDecoratorSwitches( manualDecorators ); /** - * Collection of child views in the form. + * A collection of child views in the form. * * @readonly * @type {module:ui/viewcollection~ViewCollection} @@ -104,7 +104,7 @@ export default class LinkFormView extends View { this.children = this._createFormChildren( manualDecorators ); /** - * A collection of views which can be focused in the form. + * A collection of views that can be focused in the form. * * @readonly * @protected @@ -157,7 +157,7 @@ export default class LinkFormView extends View { * {@link module:link/linkcommand~LinkCommand#manualDecorators manual link decorators} * in the {@link module:link/ui/linkformview~LinkFormView}. * - * @returns {Object.} key-value pairs, where the key is the name of the decorator and the value is + * @returns {Object.} Key-value pairs, where the key is the name of the decorator and the value is * its state. */ getDecoratorSwitchesState() { @@ -225,7 +225,7 @@ export default class LinkFormView extends View { * * @private * @param {String} label The button label. - * @param {String} icon The button's icon. + * @param {String} icon The button icon. * @param {String} className The additional button CSS class name. * @param {String} [eventName] An event name that the `ButtonView#execute` event will be delegated to. * @returns {module:ui/button/buttonview~ButtonView} The button view instance. @@ -254,12 +254,12 @@ export default class LinkFormView extends View { /** * Populates {@link module:ui/viewcollection~ViewCollection} of {@link module:ui/button/switchbuttonview~SwitchButtonView} - * made based on {@link module:link/linkcommand~LinkCommand#manualDecorators} + * made based on {@link module:link/linkcommand~LinkCommand#manualDecorators}. * * @private * @param {module:utils/collection~Collection} manualDecorators A reference to the - * collection of manual decorators stored in link's command. - * @returns {module:ui/viewcollection~ViewCollection} of Switch Buttons. + * collection of manual decorators stored in the link command. + * @returns {module:ui/viewcollection~ViewCollection} of switch buttons. */ _createManualDecoratorSwitches( manualDecorators ) { const switches = this.createCollection(); @@ -288,14 +288,14 @@ export default class LinkFormView extends View { /** * Populates the {@link #children} collection of the form. * - * If {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators} are configured in the editor, creates an + * If {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators} are configured in the editor, it creates an * additional `View` wrapping all {@link #_manualDecoratorSwitches} switch buttons corresponding - * to those decorators. + * to these decorators. * * @private - * @param {module:utils/collection~Collection} manualDecorators A reference to the - * collection of manual decorators stored in link's command. - * @returns {module:ui/viewcollection~ViewCollection} children of LinkFormView. + * @param {module:utils/collection~Collection} manualDecorators A reference to + * the collection of manual decorators stored in the link command. + * @returns {module:ui/viewcollection~ViewCollection} The children of link form view. */ _createFormChildren( manualDecorators ) { const children = this.createCollection(); @@ -337,13 +337,13 @@ export default class LinkFormView extends View { /** * Fired when the form view is submitted (when one of the children triggered the submit event), - * e.g. click on {@link #saveButtonView}. + * for example with a click on {@link #saveButtonView}. * * @event submit */ /** - * Fired when the form view is canceled, e.g. click on {@link #cancelButtonView}. + * Fired when the form view is canceled, for example with a click on {@link #cancelButtonView}. * * @event cancel */ diff --git a/src/unlinkcommand.js b/src/unlinkcommand.js index 84f3846..8837415 100644 --- a/src/unlinkcommand.js +++ b/src/unlinkcommand.js @@ -26,8 +26,8 @@ export default class UnlinkCommand extends Command { /** * Executes the command. * - * When the selection is collapsed, removes the `linkHref` attribute from each node with the same `linkHref` attribute value. - * When the selection is non-collapsed, removes the `linkHref` attribute from each node in selected ranges. + * When the selection is collapsed, it removes the `linkHref` attribute from each node with the same `linkHref` attribute value. + * When the selection is non-collapsed, it removes the `linkHref` attribute from each node in selected ranges. * * # Decorators * diff --git a/src/utils.js b/src/utils.js index bed11e9..e209ff8 100644 --- a/src/utils.js +++ b/src/utils.js @@ -23,7 +23,7 @@ export function isLinkElement( node ) { } /** - * Creates link {@link module:engine/view/attributeelement~AttributeElement} with provided `href` attribute. + * Creates link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute. * * @param {String} href * @returns {module:engine/view/attributeelement~AttributeElement} @@ -39,9 +39,9 @@ export function createLinkElement( href, writer ) { /** * Returns a safe URL based on a given value. * - * An URL is considered safe if it is safe for the user (does not contain any malicious code). + * A URL is considered safe if it is safe for the user (does not contain any malicious code). * - * If URL is considered unsafe, a simple `"#"` is returned. + * If a URL is considered unsafe, a simple `"#"` is returned. * * @protected * @param {*} url @@ -63,16 +63,16 @@ function isSafeUrl( url ) { } /** - * Returns {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration processed - * to respect the locale of the editor, i.e. to display {@link module:link/link~LinkDecoratorManualDefinition label} + * Returns the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration processed + * to respect the locale of the editor, i.e. to display the {@link module:link/link~LinkDecoratorManualDefinition label} * in the correct language. * * **Note**: Only the few most commonly used labels are translated automatically. Other labels should be manually * translated in the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration. * * @param {module:utils/locale~Locale#t} t shorthand for {@link module:utils/locale~Locale#t Locale#t} - * @param {Array.} decorators reference - * where labels' values should be localized. + * @param {Array.} The decorator reference + * where the label values should be localized. * @returns {Array.} */ export function getLocalizedDecorators( t, decorators ) { @@ -92,8 +92,8 @@ export function getLocalizedDecorators( t, decorators ) { } /** - * Converts an object with defined decorators to a normalized array of decorators. There is also added `id` key for each decorator, - * which is used as attribute's name in the model. + * Converts an object with defined decorators to a normalized array of decorators. The `id` key is added for each decorator and + * is used as the attribute's name in the model. * * @param {Object.} decorators * @returns {Array.} diff --git a/src/utils/automaticdecorators.js b/src/utils/automaticdecorators.js index d0d4be4..1d18253 100644 --- a/src/utils/automaticdecorators.js +++ b/src/utils/automaticdecorators.js @@ -8,14 +8,14 @@ */ /** - * Helper class which tight together all {@link module:link/link~LinkDecoratorAutomaticDefinition} and provides + * Helper class that ties together all {@link module:link/link~LinkDecoratorAutomaticDefinition} and provides * a {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatcher} for them. */ export default class AutomaticDecorators { constructor() { /** - * Stores definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}. - * Those data are used as source for a downcast dispatcher to make proper conversion to output data. + * Stores the definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}. + * This data is used as a source for a downcast dispatcher to create a proper conversion to output data. * * @private * @type {Set} @@ -24,7 +24,7 @@ export default class AutomaticDecorators { } /** - * Gives information how many decorators is stored in {@link module:link/utils~AutomaticDecorators} instance. + * Gives information about the number of decorators stored in the {@link module:link/utils~AutomaticDecorators} instance. * * @readonly * @protected @@ -35,10 +35,10 @@ export default class AutomaticDecorators { } /** - * Add automatic decorator objects or array with them to be used during downcasting. + * Adds automatic decorator objects or an array with them to be used during downcasting. * * @param {module:link/link~LinkDecoratorAutomaticDefinition|Array.} item - * configuration object of automatic rules for decorating links. It might be also array of such objects. + * A configuration object of automatic rules for decorating links. It might also be an array of such objects. */ add( item ) { if ( Array.isArray( item ) ) { @@ -49,10 +49,10 @@ export default class AutomaticDecorators { } /** - * Provides the conversion helper used in an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method. + * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method. * - * @returns {Function} dispatcher function used as conversion helper - * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} + * @returns {Function} A dispatcher function used as conversion helper + * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}. */ getDispatcher() { return dispatcher => { diff --git a/src/utils/manualdecorator.js b/src/utils/manualdecorator.js index 9d4ef59..8b5baed 100644 --- a/src/utils/manualdecorator.js +++ b/src/utils/manualdecorator.js @@ -11,33 +11,33 @@ import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin'; import mix from '@ckeditor/ckeditor5-utils/src/mix'; /** - * Helper class which stores manual decorators with observable {@link module:link/utils~ManualDecorator#value} - * to support integration with the UI state. An instance of this class is a model with state of single manual decorators. + * Helper class that stores manual decorators with observable {@link module:link/utils~ManualDecorator#value} + * to support integration with the UI state. An instance of this class is a model with the state of individual manual decorators. * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}. * * @mixes module:utils/observablemixin~ObservableMixin */ export default class ManualDecorator { /** - * Creates new instance of {@link module:link/utils~ManualDecorator}. + * Creates a new instance of {@link module:link/utils~ManualDecorator}. * * @param {Object} config - * @param {String} config.id name of attribute used in model, which represents given manual decorator. - * For example `'linkIsExternal'`. - * @param {String} config.label The label used in user interface to toggle manual decorator. - * @param {Object} config.attributes Set of attributes added to output data, when decorator is active for specific link. - * Attributes should keep format of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}. + * @param {String} config.id The name of the attribute used in the model that represents a given manual decorator. + * For example: `'linkIsExternal'`. + * @param {String} config.label The label used in the user interface to toggle the manual decorator. + * @param {Object} config.attributes A set of attributes added to output data when the decorator is active for a specific link. + * Attributes should keep the format of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}. */ constructor( { id, label, attributes } ) { /** - * Id of manual decorator, which is a name of attribute in model, for example 'linkManualDecorator0'. + * An ID of a manual decorator which is the name of the attribute in the model, for example: 'linkManualDecorator0'. * * @type {String} */ this.id = id; /** - * Value of current manual decorator. It reflects its state from UI. + * The value of the current manual decorator. It reflects its state from the UI. * * @observable * @member {Boolean} module:link/utils~ManualDecorator#value @@ -45,14 +45,14 @@ export default class ManualDecorator { this.set( 'value' ); /** - * The label used in user interface to toggle manual decorator. + * The label used in the user interface to toggle the manual decorator. * * @type {String} */ this.label = label; /** - * Set of attributes added to downcasted data, when decorator is activated for specific link. + * A set of attributes added to downcasted data when the decorator is activated for a specific link. * Attributes should be added in a form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}. * * @type {Object}