@ckeditor/ckeditor5-link

  • Version 41.2.1
  • Published
  • 409 kB
  • 3 dependencies
  • GPL-2.0-or-later license

Install

npm i @ckeditor/ckeditor5-link
yarn add @ckeditor/ckeditor5-link
pnpm add @ckeditor/ckeditor5-link

Overview

Link feature for CKEditor 5.

Index

Classes

class AutoLink extends Plugin {}
  • The autolink plugin.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, typeof LinkEditing];

method afterInit

afterInit: () => void;

method init

init: () => void;
class Link extends Plugin {}
  • The link plugin.

    This is a "glue" plugin that loads the and .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
typeof LinkEditing,
typeof LinkUI,
typeof AutoLink
];

class LinkCommand

class LinkCommand extends Command {}
  • The link command. It is used by the .

property automaticDecorators

readonly automaticDecorators: AutomaticDecorators;
  • An instance of the helper that ties together all that are used by the and the features.

property manualDecorators

readonly manualDecorators: Collection<ManualDecorator>;
  • A collection of corresponding to the .

    You can consider it a model with states of manual decorators added to the currently selected link.

property value

value: string;
  • The value of the 'linkHref' attribute if the start of the selection is located in a node with this attribute.

    Modifiers

    • @readonly

method execute

execute: (href: string, manualDecoratorIds?: Record<string, boolean>) => void;
  • Executes the 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, a new 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.

    When the selection is collapsed and inside the text with the linkHref attribute, the attribute value will be updated.

    # Decorators and model attribute management

    There is an optional argument to this command that applies or removes model brought by .

    Text attribute names in the model correspond to the entries in the . For every decorator configured, a model text attribute exists with the "link" prefix. For example, a 'linkMyDecorator' attribute corresponds to 'myDecorator' in the configuration.

    To learn more about link decorators, check out the documentation.

    Here is how to manage decorator attributes with the link command:

    const linkCommand = editor.commands.get( 'link' );
    // Adding a new decorator attribute.
    linkCommand.execute( 'http://example.com', {
    linkIsExternal: true
    } );
    // Removing a decorator attribute from the selection.
    linkCommand.execute( 'http://example.com', {
    linkIsExternal: false
    } );
    // Adding multiple decorator attributes at the same time.
    linkCommand.execute( 'http://example.com', {
    linkIsExternal: true,
    linkIsDownloadable: true,
    } );
    // Removing and adding decorator attributes at the same time.
    linkCommand.execute( 'http://example.com', {
    linkIsExternal: false,
    linkFoo: true,
    linkIsDownloadable: false,
    } );

    **Note**: If the decorator attribute name is not specified, its state remains untouched.

    **Note**: removes all decorator attributes.

    execute

    Parameter href

    Link destination.

    Parameter manualDecoratorIds

    The information about manual decorator attributes to be applied or removed upon execution.

method refresh

refresh: () => void;

method restoreManualDecoratorStates

restoreManualDecoratorStates: () => void;
  • Synchronizes the state of with the currently present elements in the model.

class LinkEditing

class LinkEditing extends Plugin {}
  • The link engine feature.

    It introduces the linkHref="url" attribute in the model which renders to the view as a <a href="url"> element as well as 'link' and 'unlink' commands.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any, any, any];

method init

init: () => void;

class LinkImage

class LinkImage extends Plugin {}
  • The LinkImage plugin.

    This is a "glue" plugin that loads the and .

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof LinkImageEditing, typeof LinkImageUI];

class LinkImageEditing

class LinkImageEditing extends Plugin {}
  • The link image engine feature.

    It accepts the linkHref="url" attribute in the model for the element which allows linking images.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
'ImageEditing',
'ImageUtils',
typeof LinkEditing
];

method afterInit

afterInit: () => void;

class LinkImageUI

class LinkImageUI extends Plugin {}
  • The link image UI plugin.

    This plugin provides the 'linkImage' button that can be displayed in the . It can be used to wrap images in links.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [
typeof LinkEditing,
typeof LinkUI,
'ImageBlockEditing'
];

method init

init: () => void;

class LinkUI

class LinkUI extends Plugin {}
  • The link UI plugin. It introduces the 'link' and 'unlink' buttons and support for the Ctrl+K keystroke.

    It uses the .

property actionsView

actionsView: LinkActionsView;
  • The actions view displayed inside of the balloon.

property formView

formView: any;
  • The form view displayed inside the balloon.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any];

method destroy

destroy: () => void;

method init

init: () => void;

class UnlinkCommand

class UnlinkCommand extends Command {}
  • The unlink command. It is used by the .

method execute

execute: () => void;
  • Executes the command.

    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

    If is specified, all configured decorators are removed together with the linkHref attribute.

    execute

method refresh

refresh: () => void;

Interfaces

interface LinkConfig

interface LinkConfig {}
  • The configuration of the .

    ClassicEditor
    .create( editorElement, {
    link: ... // Link feature configuration.
    } )
    .then( ... )
    .catch( ... );

    See .

addTargetToExternalLinks?: boolean;
  • When set to true, the target="blank" and rel="noopener noreferrer" attributes are automatically added to all external links in the editor. "External links" are all links in the editor content starting with http, https, or //.

    ClassicEditor
    .create( editorElement, {
    link: {
    addTargetToExternalLinks: true
    }
    } )
    .then( ... )
    .catch( ... );

    Internally, this option activates a predefined 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 decorator must be defined in the array. In such scenario, the config.link.addTargetToExternalLinks option should remain undefined or false to not interfere with the manual decorator.

    It is possible to add other or link decorators when this option is active.

    More information about decorators can be found in the reference.

    false

allowCreatingEmptyLinks?: boolean;
  • When set to true, the form will accept an empty value in the URL field, creating a link with an empty href (<a href="">).

    ClassicEditor
    .create( editorElement, {
    link: {
    allowCreatingEmptyLinks: true
    }
    } )
    .then( ... )
    .catch( ... );

    **NOTE:** This option only adds form validation. If a link with an empty href is loaded into the editor, it will be left as-is.

    false

property allowedProtocols

allowedProtocols?: Array<string>;
  • This is a protocols whitelist that can be used in links, defined as an array of strings. When not set, the editor will use a default list of allowed protocols.

    **Note:** Use this with caution and at your own risk - adding unsafe protocols like javascript: can result in serious security vulnerabilities!

    ClassicEditor
    .create( editorElement, {
    link: {
    allowedProtocols: [ 'http', 'https', 'ftp', 'tel', 'mailto', 'ssh' ]
    }
    } )
    .then( ... )
    .catch( ... );

property decorators

decorators?: Record<string, LinkDecoratorDefinition>;
  • Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are two types of link decorators:

    * &ndash; They match links against pre–defined rules and manage their attributes based on the results. * &ndash; They allow users to control link attributes individually, using the editor UI.

    Link decorators are defined as objects with key-value pairs, where the key is the name provided for a given decorator and the value is the decorator definition.

    The name of the decorator also corresponds to the in the model. For instance, the isExternal decorator below is represented as a linkIsExternal attribute in the model.

    ClassicEditor
    .create( editorElement, {
    link: {
    decorators: {
    isExternal: {
    mode: 'automatic',
    callback: url => url.startsWith( 'http://' ),
    attributes: {
    target: '_blank',
    rel: 'noopener noreferrer'
    }
    },
    isDownloadable: {
    mode: 'manual',
    label: 'Downloadable',
    attributes: {
    download: 'file.png',
    }
    },
    // ...
    }
    }
    } )
    .then( ... )
    .catch( ... );

    To learn more about the configuration syntax, check out the and decorator option reference.

    **Warning:** Currently, link decorators work independently of one another and no conflict resolution mechanism exists. For example, configuring the target attribute using both an automatic and a manual decorator at the same time could end up with quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.

    **Note**: Since the target attribute management for external links is a common use case, there is a predefined automatic decorator dedicated for that purpose which can be enabled by turning a single option on. Check out the configuration description to learn more.

    See also the for more information.

property defaultProtocol

defaultProtocol?: string;
  • When set, the editor will add the given protocol to the link when the user creates a link without one. For example, when the user is creating a link and types ckeditor.com in the link form input, during link submission the editor will automatically add the http:// protocol, so the link will look as follows: http://ckeditor.com.

    The feature also provides email address auto-detection. When you submit hello@example.com, the plugin will automatically change it to mailto:hello@example.com.

    ClassicEditor
    .create( editorElement, {
    link: {
    defaultProtocol: 'http://'
    }
    } )
    .then( ... )
    .catch( ... );

    **NOTE:** If no configuration is provided, the editor will not auto-fix the links.

Type Aliases

type LinkDecoratorDefinition

type LinkDecoratorDefinition =
| LinkDecoratorAutomaticDefinition
| LinkDecoratorManualDefinition;
  • A link decorator definition. Two types implement this definition:

    * *

    Refer to their document for more information about available options or to the for general information.

Package Files (11)

Dependencies (3)

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@ckeditor/ckeditor5-link.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@ckeditor/ckeditor5-link)
  • HTML
    <a href="https://www.jsdocs.io/package/@ckeditor/ckeditor5-link"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>