From 67d7387ae71ceafc3c581f748bbc5a02a54ac222 Mon Sep 17 00:00:00 2001 From: Anna Tomanek Date: Tue, 16 Jul 2019 08:50:12 +0200 Subject: [PATCH 1/3] Docs: Link feature guide corrected. [skip ci] --- docs/features/link.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/features/link.md b/docs/features/link.md index bd636da..a5538b6 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 @@ -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. From dd72ae91d2531842ba36932caa71c9b5e745cbcf Mon Sep 17 00:00:00 2001 From: Anna Tomanek Date: Tue, 16 Jul 2019 11:49:17 +0200 Subject: [PATCH 2/3] Docs: API docs for links and link decorators corrected. [skip ci] --- src/link.js | 59 ++++++++++++++++---------------- src/linkcommand.js | 28 +++++++-------- src/linkediting.js | 20 +++++------ src/linkui.js | 30 ++++++++-------- src/ui/linkactionsview.js | 8 ++--- src/ui/linkformview.js | 30 ++++++++-------- src/unlinkcommand.js | 4 +-- src/utils.js | 18 +++++----- src/utils/automaticdecorators.js | 18 +++++----- src/utils/manualdecorator.js | 24 ++++++------- 10 files changed, 119 insertions(+), 120 deletions(-) diff --git a/src/link.js b/src/link.js index 7ad546a..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 b2275f7..a5733e2 100644 --- a/src/linkediting.js +++ b/src/linkediting.js @@ -95,7 +95,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 @@ -105,7 +105,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', @@ -126,11 +126,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. * @@ -180,13 +180,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 ecee3a7..0c0ee8c 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; @@ -311,19 +311,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 ) { @@ -353,7 +353,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 @@ -428,7 +428,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. * @@ -481,7 +481,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 @@ -492,7 +492,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 @@ -503,7 +503,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 @@ -515,7 +515,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 @@ -526,7 +526,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 @@ -568,7 +568,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 6205d64..226377c 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:link/linkcommand~LinkCommand#manualDecorators} manualDecorators reference to - * collection of manual decorators stored in link's command. - * @returns {module:ui/viewcollection~ViewCollection} of Switch Buttons. + * @param {module:link/linkcommand~LinkCommand#manualDecorators} manualDecorators A reference to the + * 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:link/linkcommand~LinkCommand#manualDecorators} manualDecorators reference to - * collection of manual decorators stored in link's command. - * @returns {module:ui/viewcollection~ViewCollection} children of LinkFormView. + * @param {module:link/linkcommand~LinkCommand#manualDecorators} 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} From 7bdbca0a61f31617e34d86f26da64bb20efa6754 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= Date: Wed, 17 Jul 2019 16:22:11 +0200 Subject: [PATCH 3/3] Docs: Use the right label. Match the predefined decorator's one. --- docs/features/link.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/link.md b/docs/features/link.md index a5538b6..ccf7b55 100644 --- a/docs/features/link.md +++ b/docs/features/link.md @@ -134,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'