widget/utils

@ckeditor/ckeditor5-widget/src/utils

Constants

• WIDGET_CLASS_NAME : Stringmodule:widget/utils.WIDGET_CLASS_NAME

  static

  CSS class added to each widget element.

• WIDGET_SELECTED_CLASS_NAME : Stringmodule:widget/utils.WIDGET_SELECTED_CLASS_NAME

  static

  CSS class added to currently selected widget element.

Functions

• findOptimalInsertionPosition( selection ) → Positionmodule:widget/utils.findOptimalInsertionPosition

  static

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

  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.

  Returns

  Position

  The optimal position.

• getLabel( element ) → Stringmodule:widget/utils.getLabel

  static

  Returns the label of the provided element.

  Parameters

  element : Element

  Returns

  String

• isWidget( element ) → Booleanmodule:widget/utils.isWidget

  static

  Returns true if given Element is a widget.

  Parameters

  element : Element

  Returns

  Boolean

• setHighlightHandling( element, writer, add, remove )module:widget/utils.setHighlightHandling

  static

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

  Parameters

  element : Element

  writer : DowncastWriter

  add : function

  remove : function

• setLabel( element, labelOrCreator, writer )module:widget/utils.setLabel

  static

  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().

  Parameters

  element : Element

  labelOrCreator : String | function

  writer : DowncastWriter

• toWidget( element, writer, [ options ] = { [options.label], [options.hasSelectionHandler] } ) → Elementmodule:widget/utils.toWidget

  static

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

  • sets the contenteditable attribute to "true",
  • adds the ck-widget CSS class,
  • adds a custom getFillerOffset() method returning null,
  • adds a custom property allowing to recognize widget elements by using isWidget(),
  • implements the view highlight on widgets.

  This function needs to be used in conjuction with downcast converters like downcastElementToElement(). 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' )
      .add( downcastElementToElement( {
          model: 'widget',
          view: ( modelItem, writer ) => {
              const div = writer.createContainerElement( 'div', { class: 'widget' } );
  
              return toWidget( div, writer, { label: 'some widget' } );
          }
      } ) );
  
  editor.conversion.for( 'dataDowncast' )
      .add( downcastElementToElement( {
          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.hasSelectionHandler ] : Boolean

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

  Defaults to false

  Defaults to {}

  Returns

  Element

  Returns the same element.

• toWidgetEditable( editable, writer ) → EditableElementmodule:widget/utils.toWidgetEditable

  static

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

  • 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 dataDowncast only and it is usually used together with downcastElementToElement().

  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' )
      .add( downcastElementToElement( {
          model: 'nested',
          view: ( modelItem, writer ) => {
              const div = writer.createEditableElement( 'div', { class: 'nested' } );
  
              return toWidgetEditable( nested, writer );
          }
      } ) );
  
  editor.conversion.for( 'dataDowncast' )
      .add( downcastElementToElement( {
          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