attributeelement.js 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267
  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 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. * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
  33. * @param {String} name Node name.
  34. * @param {Object|Iterable} [attrs] Collection of attributes.
  35. * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
  36. * A list of nodes to be inserted into created element.
  37. */
  38. constructor( document, name, attrs, children ) {
  39. super( document, name, attrs, children );
  40. /**
  41. * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
  42. *
  43. * @method #getFillerOffset
  44. * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
  45. */
  46. this.getFillerOffset = getFillerOffset;
  47. /**
  48. * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
  49. *
  50. * @protected
  51. * @member {Number}
  52. */
  53. this._priority = DEFAULT_PRIORITY;
  54. /**
  55. * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
  56. * and then two elements are considered similar if, and only if they have the same `_id`.
  57. *
  58. * @protected
  59. * @member {String|Number}
  60. */
  61. this._id = null;
  62. /**
  63. * Keeps all the attribute elements that have the same {@link module:engine/view/attributeelement~AttributeElement#id ids}
  64. * and still exist in the view tree.
  65. *
  66. * This property is managed by {@link module:engine/view/downcastwriter~DowncastWriter}.
  67. *
  68. * @protected
  69. * @member {Set.<module:engine/view/attributeelement~AttributeElement>|null}
  70. */
  71. this._clonesGroup = null;
  72. }
  73. /**
  74. * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
  75. *
  76. * @readonly
  77. * @type {Number}
  78. */
  79. get priority() {
  80. return this._priority;
  81. }
  82. /**
  83. * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
  84. * and then two elements are considered similar if, and only if they have the same `id`.
  85. *
  86. * @readonly
  87. * @type {String|Number}
  88. */
  89. get id() {
  90. return this._id;
  91. }
  92. /**
  93. * Returns all {@link module:engine/view/attributeelement~AttributeElement attribute elements} that has the
  94. * same {@link module:engine/view/attributeelement~AttributeElement#id id} and are in the view tree (were not removed).
  95. *
  96. * Note: If this element has been removed from the tree, returned set will not include it.
  97. *
  98. * Throws {@link module:utils/ckeditorerror~CKEditorError attribute-element-get-elements-with-same-id-no-id}
  99. * if this element has no `id`.
  100. *
  101. * @returns {Set.<module:engine/view/attributeelement~AttributeElement>} Set containing all the attribute elements
  102. * with the same `id` that were added and not removed from the view tree.
  103. */
  104. getElementsWithSameId() {
  105. if ( this.id === null ) {
  106. /**
  107. * Cannot get elements with the same id for an attribute element without id.
  108. *
  109. * @error attribute-element-get-elements-with-same-id-no-id
  110. */
  111. throw new CKEditorError(
  112. 'attribute-element-get-elements-with-same-id-no-id: ' +
  113. 'Cannot get elements with the same id for an attribute element without id.',
  114. this
  115. );
  116. }
  117. return new Set( this._clonesGroup );
  118. }
  119. /**
  120. * Checks whether this object is of the given.
  121. *
  122. * attributeElement.is( 'attributeElement' ); // -> true
  123. * attributeElement.is( 'element' ); // -> true
  124. * attributeElement.is( 'node' ); // -> true
  125. * attributeElement.is( 'view:attributeElement' ); // -> true
  126. * attributeElement.is( 'view:element' ); // -> true
  127. * attributeElement.is( 'view:node' ); // -> true
  128. *
  129. * attributeElement.is( 'model:element' ); // -> false
  130. * attributeElement.is( 'documentFragment' ); // -> false
  131. *
  132. * Assuming that the object being checked is an attribute element, you can also check its
  133. * {@link module:engine/view/attributeelement~AttributeElement#name name}:
  134. *
  135. * attributeElement.is( 'b' ); // -> true if this is a bold element
  136. * attributeElement.is( 'attributeElement', 'b' ); // -> same as above
  137. * text.is( 'b' ); -> false
  138. *
  139. * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
  140. *
  141. * @param {String} type Type to check when `name` parameter is present.
  142. * Otherwise, it acts like the `name` parameter.
  143. * @param {String} [name] Element name.
  144. * @returns {Boolean}
  145. */
  146. is( type, name = null ) {
  147. if ( !name ) {
  148. return type === 'attributeElement' || type === 'view:attributeElement' ||
  149. // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
  150. type === this.name || type === 'view:' + this.name ||
  151. type === 'element' || type === 'view:element' ||
  152. type === 'node' || type === 'view:node';
  153. } else {
  154. return name === this.name && (
  155. type === 'attributeElement' || type === 'view:attributeElement' ||
  156. // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
  157. type === 'element' || type === 'view:element'
  158. );
  159. }
  160. }
  161. /**
  162. * Checks if this element is similar to other element.
  163. *
  164. * If none of elements has set {@link module:engine/view/attributeelement~AttributeElement#id}, then both elements
  165. * should have the same name, attributes and priority to be considered as similar. Two similar elements can contain
  166. * different set of children nodes.
  167. *
  168. * If at least one element has {@link module:engine/view/attributeelement~AttributeElement#id} set, then both
  169. * elements have to have the same {@link module:engine/view/attributeelement~AttributeElement#id} value to be
  170. * considered similar.
  171. *
  172. * Similarity is important for {@link module:engine/view/downcastwriter~DowncastWriter}. For example:
  173. *
  174. * * two following similar elements can be merged together into one, longer element,
  175. * * {@link module:engine/view/downcastwriter~DowncastWriter#unwrap} checks similarity of passed element and processed element to
  176. * decide whether processed element should be unwrapped,
  177. * * etc.
  178. *
  179. * @param {module:engine/view/element~Element} otherElement
  180. * @returns {Boolean}
  181. */
  182. isSimilar( otherElement ) {
  183. // If any element has an `id` set, just compare the ids.
  184. if ( this.id !== null || otherElement.id !== null ) {
  185. return this.id === otherElement.id;
  186. }
  187. return super.isSimilar( otherElement ) && this.priority == otherElement.priority;
  188. }
  189. /**
  190. * Clones provided element with priority.
  191. *
  192. * @protected
  193. * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
  194. * element will be cloned without any children.
  195. * @returns {module:engine/view/attributeelement~AttributeElement} Clone of this element.
  196. */
  197. _clone( deep ) {
  198. const cloned = super._clone( deep );
  199. // Clone priority too.
  200. cloned._priority = this._priority;
  201. // And id too.
  202. cloned._id = this._id;
  203. return cloned;
  204. }
  205. }
  206. /**
  207. * Default attribute priority.
  208. *
  209. * @member {Number} module:engine/view/attributeelement~AttributeElement.DEFAULT_PRIORITY
  210. */
  211. AttributeElement.DEFAULT_PRIORITY = DEFAULT_PRIORITY;
  212. // Returns block {@link module:engine/view/filler~Filler filler} offset or `null` if block filler is not needed.
  213. //
  214. // @returns {Number|null} Block filler offset or `null` if block filler is not needed.
  215. function getFillerOffset() {
  216. // <b>foo</b> does not need filler.
  217. if ( nonUiChildrenCount( this ) ) {
  218. return null;
  219. }
  220. let element = this.parent;
  221. // <p><b></b></p> needs filler -> <p><b><br></b></p>
  222. while ( element && element.is( 'attributeElement' ) ) {
  223. if ( nonUiChildrenCount( element ) > 1 ) {
  224. return null;
  225. }
  226. element = element.parent;
  227. }
  228. if ( !element || nonUiChildrenCount( element ) > 1 ) {
  229. return null;
  230. }
  231. // Render block filler at the end of element (after all ui elements).
  232. return this.childCount;
  233. }
  234. // Returns total count of children that are not {@link module:engine/view/uielement~UIElement UIElements}.
  235. //
  236. // @param {module:engine/view/element~Element} element
  237. // @returns {Number}
  238. function nonUiChildrenCount( element ) {
  239. return Array.from( element.getChildren() ).filter( element => !element.is( 'uiElement' ) ).length;
  240. }