placeholder.js 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  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 '../../theme/placeholder.css';
  11. const listener = {};
  12. extend( listener, EmitterMixin );
  13. // Each document stores information about its placeholder elements and check functions.
  14. const documentPlaceholders = new WeakMap();
  15. /**
  16. * Attaches placeholder to provided element and updates it's visibility. To change placeholder simply call this method
  17. * once again with new parameters.
  18. *
  19. * @param {module:engine/view/element~Element} element Element to attach placeholder to.
  20. * @param {String} placeholderText Placeholder text to use.
  21. * @param {Function} [checkFunction] If provided it will be called before checking if placeholder should be displayed.
  22. * If function returns `false` placeholder will not be showed.
  23. */
  24. export function attachPlaceholder( view, element, placeholderText, checkFunction ) {
  25. const document = view.document;
  26. // Detach placeholder if was used before.
  27. detachPlaceholder( view, element );
  28. // Single listener per document.
  29. if ( !documentPlaceholders.has( document ) ) {
  30. documentPlaceholders.set( document, new Map() );
  31. // Attach listener just before rendering and update placeholders.
  32. listener.listenTo( view, 'render', () => updateAllPlaceholders( view ) );
  33. }
  34. // Store text in element's data attribute.
  35. // This data attribute is used in CSS class to show the placeholder.
  36. view.change( writer => {
  37. writer.setAttribute( 'data-placeholder', placeholderText, element );
  38. } );
  39. // Store information about placeholder.
  40. documentPlaceholders.get( document ).set( element, checkFunction );
  41. // Update right away too.
  42. updateSinglePlaceholder( view, element, checkFunction );
  43. }
  44. /**
  45. * Removes placeholder functionality from given element.
  46. *
  47. * @param {module:engine/view/view~View} view
  48. * @param {module:engine/view/element~Element} element
  49. */
  50. export function detachPlaceholder( view, element ) {
  51. const document = element.document;
  52. if ( documentPlaceholders.has( document ) ) {
  53. documentPlaceholders.get( document ).delete( element );
  54. }
  55. view.change( writer => {
  56. writer.removeClass( 'ck-placeholder', element );
  57. writer.removeAttribute( 'data-placeholder', element );
  58. } );
  59. }
  60. // Updates all placeholders of given document.
  61. //
  62. // @private
  63. // @param {module:engine/view/view~View} view
  64. function updateAllPlaceholders( view ) {
  65. const placeholders = documentPlaceholders.get( view.document );
  66. for ( const [ element, checkFunction ] of placeholders ) {
  67. updateSinglePlaceholder( view, element, checkFunction );
  68. }
  69. }
  70. // Updates placeholder class of given element.
  71. //
  72. // @private
  73. // @param {module:engine/view/view~View} view
  74. // @param {module:engine/view/element~Element} element
  75. // @param {Function} checkFunction
  76. function updateSinglePlaceholder( view, element, checkFunction ) {
  77. const document = element.document;
  78. // Element was removed from document.
  79. if ( !document ) {
  80. return;
  81. }
  82. const viewSelection = document.selection;
  83. const anchor = viewSelection.anchor;
  84. // If checkFunction is provided and returns false - remove placeholder.
  85. if ( checkFunction && !checkFunction() ) {
  86. if ( element.hasClass( 'ck-placeholder' ) ) {
  87. view.change( writer => {
  88. writer.removeClass( 'ck-placeholder', element );
  89. } );
  90. }
  91. return;
  92. }
  93. // Element is empty for placeholder purposes when it has no children or only ui elements.
  94. // This check is taken from `view.ContainerElement#getFillerOffset`.
  95. const isEmptyish = !Array.from( element.getChildren() ).some( element => !element.is( 'uiElement' ) );
  96. // If element is empty and editor is blurred.
  97. if ( !document.isFocused && isEmptyish ) {
  98. if ( !element.hasClass( 'ck-placeholder' ) ) {
  99. view.change( writer => {
  100. writer.addClass( 'ck-placeholder', element );
  101. } );
  102. }
  103. return;
  104. }
  105. // It there are no child elements and selection is not placed inside element.
  106. if ( isEmptyish && anchor && anchor.parent !== element ) {
  107. if ( !element.hasClass( 'ck-placeholder' ) ) {
  108. view.change( writer => {
  109. writer.addClass( 'ck-placeholder', element );
  110. } );
  111. }
  112. } else {
  113. if ( element.hasClass( 'ck-placeholder' ) ) {
  114. view.change( writer => {
  115. writer.removeClass( 'ck-placeholder', element );
  116. } );
  117. }
  118. }
  119. }