placeholder.js 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130
  1. /**
  2. * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module engine/view/placeholder
  7. */
  8. import extend from '@ckeditor/ckeditor5-utils/src/lib/lodash/extend';
  9. import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
  10. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  11. import '../../theme/placeholder.css';
  12. const listener = {};
  13. extend( listener, EmitterMixin );
  14. // Each document stores information about its placeholder elements and check functions.
  15. const documentPlaceholders = new WeakMap();
  16. /**
  17. * Attaches placeholder to provided element and updates it's visibility. To change placeholder simply call this method
  18. * once again with new parameters.
  19. *
  20. * @param {module:engine/view/element~Element} element Element to attach placeholder to.
  21. * @param {String} placeholderText Placeholder text to use.
  22. * @param {Function} [checkFunction] If provided it will be called before checking if placeholder should be displayed.
  23. * If function returns `false` placeholder will not be showed.
  24. */
  25. export function attachPlaceholder( element, placeholderText, checkFunction ) {
  26. const document = element.document;
  27. if ( !document ) {
  28. /**
  29. * Provided element is not placed in any {@link module:engine/view/document~Document}.
  30. *
  31. * @error view-placeholder-element-is-detached
  32. */
  33. throw new CKEditorError( 'view-placeholder-element-is-detached: Provided element is not placed in document.' );
  34. }
  35. // Detach placeholder if was used before.
  36. detachPlaceholder( element );
  37. // Single listener per document.
  38. if ( !documentPlaceholders.has( document ) ) {
  39. documentPlaceholders.set( document, new Map() );
  40. listener.listenTo( document, 'change', () => updateAllPlaceholders( document ) );
  41. }
  42. // Store text in element's data attribute.
  43. // This data attribute is used in CSS class to show the placeholder.
  44. element.setAttribute( 'data-placeholder', placeholderText );
  45. // Store information about placeholder.
  46. documentPlaceholders.get( document ).set( element, checkFunction );
  47. // Update right away too.
  48. updateSinglePlaceholder( element, checkFunction );
  49. }
  50. /**
  51. * Removes placeholder functionality from given element.
  52. *
  53. * @param {module:engine/view/element~Element} element
  54. */
  55. export function detachPlaceholder( element ) {
  56. const document = element.document;
  57. element.removeClass( 'ck-placeholder' );
  58. element.removeAttribute( 'data-placeholder' );
  59. if ( documentPlaceholders.has( document ) ) {
  60. documentPlaceholders.get( document ).delete( element );
  61. }
  62. }
  63. // Updates all placeholders of given document.
  64. //
  65. // @private
  66. // @param {module:engine/view/document~Document} document
  67. function updateAllPlaceholders( document ) {
  68. const placeholders = documentPlaceholders.get( document );
  69. for ( const [ element, checkFunction ] of placeholders ) {
  70. updateSinglePlaceholder( element, checkFunction );
  71. }
  72. }
  73. // Updates placeholder class of given element.
  74. //
  75. // @private
  76. // @param {module:engine/view/element~Element} element
  77. // @param {Function} checkFunction
  78. function updateSinglePlaceholder( element, checkFunction ) {
  79. const document = element.document;
  80. // Element was removed from document.
  81. if ( !document ) {
  82. return;
  83. }
  84. const viewSelection = document.selection;
  85. const anchor = viewSelection.anchor;
  86. // If checkFunction is provided and returns false - remove placeholder.
  87. if ( checkFunction && !checkFunction() ) {
  88. element.removeClass( 'ck-placeholder' );
  89. return;
  90. }
  91. // Element is empty for placeholder purposes when it has no children or only ui elements.
  92. // This check is taken from `view.ContainerElement#getFillerOffset`.
  93. const isEmptyish = !Array.from( element.getChildren() ).some( element => !element.is( 'uiElement' ) );
  94. // If element is empty and editor is blurred.
  95. if ( !document.isFocused && isEmptyish ) {
  96. element.addClass( 'ck-placeholder' );
  97. return;
  98. }
  99. // It there are no child elements and selection is not placed inside element.
  100. if ( isEmptyish && anchor && anchor.parent !== element ) {
  101. element.addClass( 'ck-placeholder' );
  102. } else {
  103. element.removeClass( 'ck-placeholder' );
  104. }
  105. }