widget/utils

@ckeditor/ckeditor5-widget/src/utils

Constants

• WIDGET_CLASS_NAME : 'ck-widget'module:widget/utils#WIDGET_CLASS_NAME

  See source

  CSS class added to each widget element.

• WIDGET_SELECTED_CLASS_NAME : 'ck-widget_selected'module:widget/utils#WIDGET_SELECTED_CLASS_NAME

  See source

  CSS class added to currently selected widget element.

Functions

• calculateResizeHostAncestorWidth( domResizeHost ) → numbermodule:widget/utils~calculateResizeHostAncestorWidth

  See source

  Starting from a DOM resize host element (an element that receives dimensions as a result of resizing), this helper returns the width of the found ancestor element.

  * It searches up to 5 levels of ancestors only.
  

  Parameters

  domResizeHost : HTMLElement

  Resize host DOM element that receives dimensions as a result of resizing.

  Returns

  number

  Width of ancestor element in pixels or 0 if no ancestor with a computed width has been found.

• calculateResizeHostPercentageWidth( domResizeHost, resizeHostRect ) → numbermodule:widget/utils~calculateResizeHostPercentageWidth

  See source

  Calculates a relative width of a domResizeHost compared to its ancestor in percents.

  Parameters

  domResizeHost : HTMLElement

  Resize host DOM element.

  resizeHostRect : Rect

  Defaults to ...

  Returns

  number

  Percentage value between 0 and 100.

• findOptimalInsertionRange( selection, model ) → Rangemodule:widget/utils~findOptimalInsertionRange

  See source

  Returns a model range 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 collapsed range before this paragraph will be returned so that it is not split. If the selection is at the end of a paragraph, the collapsed range after this paragraph will be returned.

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

  Parameters

  selection : Selection | DocumentSelection

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

  model : Model

  Model instance.

  Returns

  Range

  The optimal range.

• getLabel( element ) → stringmodule:widget/utils~getLabel

  See source

  Returns the label of the provided element.

  Parameters

  element : Element

  Returns

  string

• isWidget( node ) → booleanmodule:widget/utils~isWidget

  See source

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

  Parameters

  node : TypeCheckable

  Returns

  boolean

• setHighlightHandling( element, writer, add, remove ) → voidmodule:widget/utils~setHighlightHandling

  See source

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

  Parameters

  element : Element

  writer : DowncastWriter

  add : ( Element, HighlightDescriptor, DowncastWriter ) => void

  Defaults to addHighlight

  remove : ( Element, HighlightDescriptor, DowncastWriter ) => void

  Defaults to removeHighlight

  Returns

  void

• setLabel( element, labelOrCreator ) → voidmodule:widget/utils~setLabel

  See source

  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 | () => string

  Returns

  void

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

  See source

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

  • sets the contenteditable attribute to "false",
  • 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 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

  Additional options.

  Properties

  [ options.hasSelectionHandle ] : boolean

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

  [ options.label ] : string | () => string

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

  Defaults to {}

  Returns

  Element

  Returns the same element.

• toWidgetEditable( editable, writer, options = { [options.label] } ) → EditableElementmodule:widget/utils~toWidgetEditable

  See source

  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.
  • implements the view highlight on widget's editable.

  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, { label: 'label for editable' } );
  		}
  	} );
  
  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

  options : object

  Additional options.

  Properties

  [ options.label ] : string

  Editable's label used by assistive technologies (e.g. screen readers).

  Defaults to {}

  Returns

  EditableElement

  Returns the same element that was provided in the editable parameter

• viewToModelPositionOutsideModelElement( model, viewElementMatcher ) → GetCallback<MapperViewToModelPositionEvent>module:widget/utils~viewToModelPositionOutsideModelElement

  See source

  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.

  For example:

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

  In such case, view positions inside <span> cannot be correctly 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 : ( Element ) => boolean

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

  Returns

  GetCallback<MapperViewToModelPositionEvent>