CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Badge (ui/badge)

@ckeditor/ckeditor5-ui/src/badge/badge

class
See source

A helper that enables the badge feature in the editor and renders a custom view next to the bottom of the editable element (editor root, source editing area, etc.) when the editor is focused.

Filtering

Properties

  • protected readonly

    editor : Editor

    See source

    Editor instance the helper was created for.

  • private readonly

    _balloonClass : undefined | string

    See source

    An additional CSS class added to the BalloonView.

  • private

    _balloonView : null | BalloonPanelView

    See source

    A reference to the balloon panel hosting and positioning the badge content.

  • private

    _lastFocusedEditableElement : null | HTMLElement

    See source

    A reference to the last editable element (root, source editing area, etc.) focused by the user. Since the focus can move to other focusable elements in the UI, this reference allows positioning the balloon over the right element whether the user is typing or using the UI.

  • private

    _showBalloonThrottled : DebouncedFuncLeading<() => void>

    See source

    A throttled version of the _showBalloon method meant for frequent use to avoid performance loss.

Methods

  • protected

    constructor( editor, options = { [options.balloonClass] } )

    See source

    Creates a badge for a given editor. The feature is initialized on Editor#ready event.

    Parameters

    editor : Editor
    options : object
    Properties
    [ options.balloonClass ] : string

    Defaults to {}

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • destroy() → void

    See source

    Destroys the badge along with its view.

    Returns

    void

  • inherited

    fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]

    See source

    Fires an event, executing all callbacks registered for it.

    The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    eventOrInfo : GetNameOrEventInfo<TEvent>

    The name of the event or EventInfo object if event is delegated.

    args : TEvent[ 'args' ]

    Additional arguments to be passed to the callbacks.

    Returns

    GetEventInfo<TEvent>[ 'return' ]

    By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

    // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );

    An event callback can stop the event and set the return value of the fire method.

    Type parameters

    TEvent : extends BaseEvent

    The type describing the event. See BaseEvent.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : CallbackOptions

    Additional options.

    Returns

    void

  • inherited

    listenTo( emitter, event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node. It is backwards compatible with listenTo.

    Type parameters

    K : extends keyof DomEventMap

    Parameters

    emitter : Window | Node

    The object that fires the event.

    event : K

    The name of the event.

    callback : ( Badge, EventInfo<string, unknown>, DomEventMap[ K ] ) => void

    The function to be called on event.

    [ options ] : object

    Additional options.

    Returns

    void

  • inherited

    off( event, callback ) → void

    See source

    Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

    on( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed when an event is fired.

    Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    once( event, callback, [ options ] ) → void

    See source

    Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

    Type parameters

    TEvent : extends BaseEvent

    The type descibing the event. See BaseEvent.

    Parameters

    event : TEvent[ 'name' ]

    The name of the event.

    callback : GetCallback<TEvent>

    The function to be called on event.

    [ options ] : GetCallbackOptions<TEvent>

    Additional options.

    Returns

    void

  • inherited

    stopDelegating( [ event ], [ emitter ] ) → void

    See source

    Stops delegating events. It can be used at different levels:

    • To stop delegating all events.
    • To stop delegating a specific event to all emitters.
    • To stop delegating a specific event to a specific emitter.

    Parameters

    [ event ] : string

    The name of the event to stop delegating. If omitted, stops it all delegations.

    [ emitter ] : Emitter

    (requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

    Returns

    void

  • inherited

    stopListening( [ emitter ], [ event ], [ callback ] ) → void

    See source

    Stops listening for events. It can be used at different levels: It is backwards compatible with listenTo.

    • To stop listening to a specific callback.
    • To stop listening to a specific event.
    • To stop listening to all events fired by a specific object.
    • To stop listening to all events fired by all objects.

    Parameters

    [ emitter ] : Window | Node | Emitter

    The object to stop listening to. If omitted, stops it for all objects.

    [ event ] : string

    (Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

    [ callback ] : Function

    (Requires the event) The function to be removed from the call list for the given event.

    Returns

    void

  • protected

    _createBadgeContent() → View<HTMLElement>

    See source

    Creates the badge content.

    Returns

    View<HTMLElement>

  • protected

    _getNormalizedConfig() → BadgeConfig

    See source

    Returns normalized configuration for the badge.

    Returns

    BadgeConfig

  • protected

    _handleEditorReady() → void

    See source

    Enables badge label once the editor (ui) is ready.

    Returns

    void

  • protected

    _isEnabled() → boolean

    See source

    Enables the badge feature.

    Returns

    boolean

  • private

    _createBalloonView() → BalloonPanelView

    See source

    Creates an instance of the balloon panel with the badge view inside ready for positioning.

    Returns

    BalloonPanelView

  • private

    _getBalloonAttachOptions() → null | Partial<Options>

    See source

    Returns the options for attaching the balloon to the focused editable element.

    Returns

    null | Partial<Options>

  • private

    _hideBalloon() → void

    See source

    Hides the badge balloon if already visible.

    Returns

    void

  • private

    _showBalloon() → void

    See source

    Attempts to display the balloon with the badge view.

    Returns

    void

  • private

    _updateLastFocusedEditableElement() → void

    See source

    Updates the _lastFocusedEditableElement based on the state of the global focus tracker.

    Returns

    void