utils.js 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module media-embed/utils
  7. */
  8. import { isWidget, toWidget } from '@ckeditor/ckeditor5-widget/src/utils';
  9. /**
  10. * Converts a given {@link module:engine/view/element~Element} to a media embed widget:
  11. * * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the media widget element.
  12. * * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
  13. *
  14. * @param {module:engine/view/element~Element} viewElement
  15. * @param {module:engine/view/downcastwriter~DowncastWriter} writer An instance of the view writer.
  16. * @param {String} label The element's label.
  17. * @returns {module:engine/view/element~Element}
  18. */
  19. export function toMediaWidget( viewElement, writer, label ) {
  20. writer.setCustomProperty( 'media', true, viewElement );
  21. return toWidget( viewElement, writer, { label } );
  22. }
  23. /**
  24. * Returns a media widget editing view element if one is selected.
  25. *
  26. * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} selection
  27. * @returns {module:engine/view/element~Element|null}
  28. */
  29. export function getSelectedMediaViewWidget( selection ) {
  30. const viewElement = selection.getSelectedElement();
  31. if ( viewElement && isMediaWidget( viewElement ) ) {
  32. return viewElement;
  33. }
  34. return null;
  35. }
  36. /**
  37. * Checks if a given view element is a media widget.
  38. *
  39. * @param {module:engine/view/element~Element} viewElement
  40. * @returns {Boolean}
  41. */
  42. export function isMediaWidget( viewElement ) {
  43. return !!viewElement.getCustomProperty( 'media' ) && isWidget( viewElement );
  44. }
  45. /**
  46. * Creates a view element representing the media. Either "semantic" one for the data pipeline:
  47. *
  48. * <figure class="media">
  49. * <oembed url="foo"></oembed>
  50. * </figure>
  51. *
  52. * or "non-semantic" (for the editing view pipeline):
  53. *
  54. * <figure class="media">
  55. * <div data-oembed-url="foo">[ non-semantic media preview for "foo" ]</div>
  56. * </figure>
  57. *
  58. * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  59. * @param {module:media-embed/mediaregistry~MediaRegistry} registry
  60. * @param {String} url
  61. * @param {Object} options
  62. * @param {String} [options.useSemanticWrapper]
  63. * @param {String} [options.renderForEditingView]
  64. * @returns {module:engine/view/containerelement~ContainerElement}
  65. */
  66. export function createMediaFigureElement( writer, registry, url, options ) {
  67. const figure = writer.createContainerElement( 'figure', { class: 'media' } );
  68. // TODO: This is a hack. Without it, the figure in the data pipeline will contain &nbsp; because
  69. // its only child is the UIElement (wrapper).
  70. //
  71. // Note: The hack is a copy&paste from widget utils; it makes the figure act like it's a widget.
  72. figure.getFillerOffset = getFillerOffset;
  73. writer.insert( writer.createPositionAt( figure, 0 ), registry.getMediaViewElement( writer, url, options ) );
  74. return figure;
  75. }
  76. /**
  77. * Returns a selected media element in the model, if any.
  78. *
  79. * @param {module:engine/model/selection~Selection} selection
  80. * @returns {module:engine/model/element~Element|null}
  81. */
  82. export function getSelectedMediaModelWidget( selection ) {
  83. const selectedElement = selection.getSelectedElement();
  84. if ( selectedElement && selectedElement.is( 'media' ) ) {
  85. return selectedElement;
  86. }
  87. return null;
  88. }
  89. /**
  90. * Creates a media element and inserts it into the model.
  91. *
  92. * **Note**: This method will use {@link module:engine/model/model~Model#insertContent `model.insertContent()`} logic of inserting content
  93. * if no `insertPosition` is passed.
  94. *
  95. * @param {module:engine/model/model~Model} model
  96. * @param {String} url An URL of an embeddable media.
  97. * @param {module:engine/model/position~Position} [insertPosition] Position to insert media. If not specified,
  98. * the default behavior of {@link module:engine/model/model~Model#insertContent `model.insertContent()`} will
  99. * be applied.
  100. */
  101. export function insertMedia( model, url, insertPosition ) {
  102. model.change( writer => {
  103. const mediaElement = writer.createElement( 'media', { url } );
  104. model.insertContent( mediaElement, insertPosition );
  105. writer.setSelection( mediaElement, 'on' );
  106. } );
  107. }
  108. function getFillerOffset() {
  109. return null;
  110. }