CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Module

widget/utils

@ckeditor/ckeditor5-widget/src/utils

module

Filtering

Constants

Functions

  • centeredBalloonPositionForLongWidgets( widgetRect, balloonRect ) → Position | null

    A positioning function passed to the getOptimalPosition helper as a last resort when attaching balloon UI to widgets. It comes in handy when a widget is longer than the visual viewport of the web browser and/or upper/lower boundaries of a widget are off screen because of the web page scroll.

    See source
                                           ┌─┄┄┄┄┄┄┄┄┄Widget┄┄┄┄┄┄┄┄┄┐
                                       ┊                         ┊
┌────────────Viewport───────────┐   ┌──╁─────────Viewport────────╁──┐
│  ┏━━━━━━━━━━Widget━━━━━━━━━┓  │   │  ┃            ^            ┃  │
│  ┃            ^            ┃  │   │  ┃   ╭───────/ \───────╮   ┃  │
│  ┃   ╭───────/ \───────╮   ┃  │   │  ┃   │     Balloon     │   ┃  │
│  ┃   │     Balloon     │   ┃  │   │  ┃   ╰─────────────────╯   ┃  │
│  ┃   ╰─────────────────╯   ┃  │   │  ┃                         ┃  │
│  ┃                         ┃  │   │  ┃                         ┃  │
│  ┃                         ┃  │   │  ┃                         ┃  │
│  ┃                         ┃  │   │  ┃                         ┃  │
│  ┃                         ┃  │   │  ┃                         ┃  │
│  ┃                         ┃  │   │  ┃                         ┃  │
│  ┃                         ┃  │   │  ┃                         ┃  │
└──╀─────────────────────────╀──┘   └──╀─────────────────────────╀──┘
   ┊                         ┊         ┊                         ┊
   ┊                         ┊         └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
   ┊                         ┊
   └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘

    Note: Works best if used together with default BalloonPanelView positions like northArrowSouth and southArrowNorth; the transition between these two and this position is smooth.

    Parameters

    widgetRect : Rect

    A rect of the widget.

    balloonRect : Rect

    A rect of the balloon.

    Returns

    Position | null

  • checkSelectionOnObject( selection, schema ) → Boolean

    Checks if the selection is on an object.

    See source

    Parameters

    selection : Selection | DocumentSelection
    schema : Schema

    Returns

    Boolean

  • findOptimalInsertionPosition( selection, model ) → Position

    Returns a model position which is optimal (in terms of UX) for inserting a widget block.

    See source

    For instance, if a selection is in the middle of a paragraph, the position before this paragraph will be returned so that it is not split. If the selection is at the end of a paragraph, the position after this paragraph will be returned.

    Note: If the selection is placed in an empty block, that block will be returned. If that position is then passed to insertContent, the block will be fully replaced by the image.

    Parameters

    selection : Selection | DocumentSelection

    The selection based on which the insertion position should be calculated.

    model : Model

    Model instance.

    Returns

    Position

    The optimal position.

  • getLabel( element ) → String

    Returns the label of the provided element.

    See source

    Parameters

    element : Element

    Returns

    String

  • isWidget( node ) → Boolean

    Returns true if given Node is an Element and a widget.

    See source

    Parameters

    node : Node

    Returns

    Boolean

  • setHighlightHandling( element, writer, add, remove )

    Sets highlight handling methods. Uses HighlightStack to properly determine which highlight descriptor should be used at given time.

    See source

    Parameters

    element : Element
    writer : DowncastWriter
    add : function
    remove : function

  • setLabel( element, labelOrCreator, writer )

    Sets label for given element. It can be passed as a plain string or a function returning a string. Function will be called each time label is retrieved by getLabel().

    See source

    Parameters

    element : Element
    labelOrCreator : String | function
    writer : DowncastWriter

  • toWidget( element, writer, [ options ] = { [options.label], [options.hasSelectionHandle] } ) → Element

    Converts the given Element to a widget in the following way:

    See source

    This function needs to be used in conjunction with downcast conversion helpers like elementToElement(). Moreover, typically you will want to use toWidget() only for editingDowncast, while keeping the dataDowncast clean.

    For example, in order to convert a <widget> model element to <div class="widget"> in the view, you can define such converters:

    editor.conversion.for( 'editingDowncast' )
	.elementToElement( {
		model: 'widget',
		view: ( modelItem, { writer } ) => {
			const div = writer.createContainerElement( 'div', { class: 'widget' } );

			return toWidget( div, writer, { label: 'some widget' } );
		}
	} );

editor.conversion.for( 'dataDowncast' )
	.elementToElement( {
		model: 'widget',
		view: ( modelItem, { writer } ) => {
			return writer.createContainerElement( 'div', { class: 'widget' } );
		}
	} );

    See the full source code of the widget (with a nested editable) schema definition and converters in this sample.

    Parameters

    element : Element
    writer : DowncastWriter
    [ options ] : Object
    Properties
    [ options.label ] : String | function

    Element's label provided to the setLabel function. It can be passed as a plain string or a function returning a string. It represents the widget for assistive technologies (like screen readers).

    [ options.hasSelectionHandle ] : Boolean

    If true, the widget will have a selection handle added.

    Defaults to false

    Defaults to {}

    Returns

    Element

    Returns the same element.

  • toWidgetEditable( editable, writer ) → EditableElement

    Adds functionality to the provided EditableElement to act as a widget's editable:

    See source
    • sets the contenteditable attribute to true when isReadOnly is false, otherwise sets it to false,
    • adds the ck-editor__editable and ck-editor__nested-editable CSS classes,
    • adds the ck-editor__nested-editable_focused CSS class when the editable is focused and removes it when it is blurred.

    Similarly to toWidget() this function should be used in editingDowncast only and it is usually used together with elementToElement().

    For example, in order to convert a <nested> model element to <div class="nested"> in the view, you can define such converters:

    editor.conversion.for( 'editingDowncast' )
	.elementToElement( {
		model: 'nested',
		view: ( modelItem, { writer } ) => {
			const div = writer.createEditableElement( 'div', { class: 'nested' } );

			return toWidgetEditable( nested, writer );
		}
	} );

editor.conversion.for( 'dataDowncast' )
	.elementToElement( {
		model: 'nested',
		view: ( modelItem, { writer } ) => {
			return writer.createContainerElement( 'div', { class: 'nested' } );
		}
	} );

    See the full source code of the widget (with nested editable) schema definition and converters in this sample.

    Parameters

    editable : EditableElement
    writer : DowncastWriter

    Returns

    EditableElement

    Returns the same element that was provided in the editable parameter

  • viewToModelPositionOutsideModelElement( model, viewElementMatcher ) → function

    A util to be used in order to map view positions to correct model positions when implementing a widget which renders non-empty view element for an empty model element.

    See source

    For example:

    // Model:
<placeholder type="name"></placeholder>

// View:
<span class="placeholder">name</span>

    In such case, view positions inside <span> cannot be correct mapped to the model (because the model element is empty). To handle mapping positions inside <span class="placeholder"> to the model use this util as follows:

    editor.editing.mapper.on(
	'viewToModelPosition',
	viewToModelPositionOutsideModelElement( model, viewElement => viewElement.hasClass( 'placeholder' ) )
);

    The callback will try to map the view offset of selection to an expected model position.

    1. When the position is at the end (or in the middle) of the inline widget:

      // View:
<p>foo <span class="placeholder">name|</span> bar</p>

// Model:
<paragraph>foo <placeholder type="name"></placeholder>| bar</paragraph>

    2. When the position is at the beginning of the inline widget:

      // View:
<p>foo <span class="placeholder">|name</span> bar</p>

// Model:
<paragraph>foo |<placeholder type="name"></placeholder> bar</paragraph>

    Parameters

    model : Model

    Model instance on which the callback operates.

    viewElementMatcher : function

    Function that is passed a view element and should return true if the custom mapping should be applied to the given view element.

    Returns

    function