8
0

attributeelement.js 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
  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/attributeelement
  7. */
  8. import Element from './element';
  9. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  10. // Default attribute priority.
  11. const DEFAULT_PRIORITY = 10;
  12. /**
  13. * Attribute elements are used to represent formatting elements in the view (think – `<b>`, `<span style="font-size: 2em">`, etc.).
  14. * Most often they are created when downcasting model text attributes.
  15. *
  16. * Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various
  17. * types (container element, {@link module:engine/view/attributeelement~AttributeElement attribute element},
  18. * {@link module:engine/view/emptyelement~EmptyElement empty element}, etc) when developing a feature.
  19. *
  20. * To create a new attribute element instance use the
  21. * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `DowncastWriter#createAttributeElement()`} method.
  22. *
  23. * @extends module:engine/view/element~Element
  24. */
  25. export default class AttributeElement extends Element {
  26. /**
  27. * Creates an attribute element.
  28. *
  29. * @see module:engine/view/downcastwriter~DowncastWriter#createAttributeElement
  30. * @see module:engine/view/element~Element
  31. * @protected
  32. */
  33. constructor( name, attrs, children ) {
  34. super( name, attrs, children );
  35. /**
  36. * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
  37. *
  38. * @method #getFillerOffset
  39. * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
  40. */
  41. this.getFillerOffset = getFillerOffset;
  42. /**
  43. * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
  44. *
  45. * @protected
  46. * @member {Number}
  47. */
  48. this._priority = DEFAULT_PRIORITY;
  49. /**
  50. * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
  51. * and then two elements are considered similar if, and only if they have the same `_id`.
  52. *
  53. * @protected
  54. * @member {String|Number}
  55. */
  56. this._id = null;
  57. /**
  58. * Keeps all the attribute elements that have the same {@link module:engine/view/attributeelement~AttributeElement#id ids}
  59. * and still exist in the view tree.
  60. *
  61. * This property is managed by {@link module:engine/view/downcastwriter~DowncastWriter}.
  62. *
  63. * @protected
  64. * @member {Set.<module:engine/view/attributeelement~AttributeElement>|null}
  65. */
  66. this._clonesGroup = null;
  67. }
  68. /**
  69. * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
  70. *
  71. * @readonly
  72. * @type {Number}
  73. */
  74. get priority() {
  75. return this._priority;
  76. }
  77. /**
  78. * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
  79. * and then two elements are considered similar if, and only if they have the same `id`.
  80. *
  81. * @readonly
  82. * @type {String|Number}
  83. */
  84. get id() {
  85. return this._id;
  86. }
  87. /**
  88. * Returns all {@link module:engine/view/attributeelement~AttributeElement attribute elements} that has the
  89. * same {@link module:engine/view/attributeelement~AttributeElement#id id} and are in the view tree (were not removed).
  90. *
  91. * Note: If this element has been removed from the tree, returned set will not include it.
  92. *
  93. * Throws {@link module:utils/ckeditorerror~CKEditorError attribute-element-get-elements-with-same-id-no-id}
  94. * if this element has no `id`.
  95. *
  96. * @returns {Set.<module:engine/view/attributeelement~AttributeElement>} Set containing all the attribute elements
  97. * with the same `id` that were added and not removed from the view tree.
  98. */
  99. getElementsWithSameId() {
  100. if ( this.id === null ) {
  101. /**
  102. * Cannot get elements with the same id for an attribute element without id.
  103. *
  104. * @error attribute-element-get-elements-with-same-id-no-id
  105. */
  106. throw new CKEditorError(
  107. 'attribute-element-get-elements-with-same-id-no-id: ' +
  108. 'Cannot get elements with the same id for an attribute element without id.'
  109. );
  110. }
  111. return new Set( this._clonesGroup );
  112. }
  113. /**
  114. * @inheritDoc
  115. */
  116. is( type, name = null ) {
  117. if ( !name ) {
  118. return type == 'attributeElement' || super.is( type );
  119. } else {
  120. return ( type == 'attributeElement' && name == this.name ) || super.is( type, name );
  121. }
  122. }
  123. /**
  124. * Checks if this element is similar to other element.
  125. *
  126. * If none of elements has set {@link module:engine/view/attributeelement~AttributeElement#id}, then both elements
  127. * should have the same name, attributes and priority to be considered as similar. Two similar elements can contain
  128. * different set of children nodes.
  129. *
  130. * If at least one element has {@link module:engine/view/attributeelement~AttributeElement#id} set, then both
  131. * elements have to have the same {@link module:engine/view/attributeelement~AttributeElement#id} value to be
  132. * considered similar.
  133. *
  134. * Similarity is important for {@link module:engine/view/downcastwriter~DowncastWriter}. For example:
  135. *
  136. * * two following similar elements can be merged together into one, longer element,
  137. * * {@link module:engine/view/downcastwriter~DowncastWriter#unwrap} checks similarity of passed element and processed element to
  138. * decide whether processed element should be unwrapped,
  139. * * etc.
  140. *
  141. * @param {module:engine/view/element~Element} otherElement
  142. * @returns {Boolean}
  143. */
  144. isSimilar( otherElement ) {
  145. // If any element has an `id` set, just compare the ids.
  146. if ( this.id !== null || otherElement.id !== null ) {
  147. return this.id === otherElement.id;
  148. }
  149. return super.isSimilar( otherElement ) && this.priority == otherElement.priority;
  150. }
  151. /**
  152. * Clones provided element with priority.
  153. *
  154. * @protected
  155. * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
  156. * element will be cloned without any children.
  157. * @returns {module:engine/view/attributeelement~AttributeElement} Clone of this element.
  158. */
  159. _clone( deep ) {
  160. const cloned = super._clone( deep );
  161. // Clone priority too.
  162. cloned._priority = this._priority;
  163. // And id too.
  164. cloned._id = this._id;
  165. return cloned;
  166. }
  167. }
  168. /**
  169. * Default attribute priority.
  170. *
  171. * @member {Number} module:engine/view/attributeelement~AttributeElement.DEFAULT_PRIORITY
  172. */
  173. AttributeElement.DEFAULT_PRIORITY = DEFAULT_PRIORITY;
  174. // Returns block {@link module:engine/view/filler~Filler filler} offset or `null` if block filler is not needed.
  175. //
  176. // @returns {Number|null} Block filler offset or `null` if block filler is not needed.
  177. function getFillerOffset() {
  178. // <b>foo</b> does not need filler.
  179. if ( nonUiChildrenCount( this ) ) {
  180. return null;
  181. }
  182. let element = this.parent;
  183. // <p><b></b></p> needs filler -> <p><b><br></b></p>
  184. while ( element && element.is( 'attributeElement' ) ) {
  185. if ( nonUiChildrenCount( element ) > 1 ) {
  186. return null;
  187. }
  188. element = element.parent;
  189. }
  190. if ( !element || nonUiChildrenCount( element ) > 1 ) {
  191. return null;
  192. }
  193. // Render block filler at the end of element (after all ui elements).
  194. return this.childCount;
  195. }
  196. // Returns total count of children that are not {@link module:engine/view/uielement~UIElement UIElements}.
  197. //
  198. // @param {module:engine/view/element~Element} element
  199. // @returns {Number}
  200. function nonUiChildrenCount( element ) {
  201. return Array.from( element.getChildren() ).filter( element => !element.is( 'uiElement' ) ).length;
  202. }