8
0

balloonpanelview.js 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module ui/panel/balloon/balloonpanelview
  7. */
  8. import View from '../../view';
  9. import Template from '../../template';
  10. import { getOptimalPosition } from '@ckeditor/ckeditor5-utils/src/dom/position';
  11. import isRange from '@ckeditor/ckeditor5-utils/src/dom/isrange';
  12. import isElement from '@ckeditor/ckeditor5-utils/src/lib/lodash/isElement';
  13. import toUnit from '@ckeditor/ckeditor5-utils/src/dom/tounit';
  14. import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  15. const toPx = toUnit( 'px' );
  16. const defaultLimiterElement = global.document.body;
  17. /**
  18. * The balloon panel view class.
  19. *
  20. * @extends module:ui/view~View
  21. */
  22. export default class BalloonPanelView extends View {
  23. /**
  24. * @inheritDoc
  25. */
  26. constructor( locale ) {
  27. super( locale );
  28. const bind = this.bindTemplate;
  29. /**
  30. * The absolute top position of the balloon panel in pixels.
  31. *
  32. * @observable
  33. * @default 0
  34. * @member {Number} #top
  35. */
  36. this.set( 'top', 0 );
  37. /**
  38. * The absolute left position of the balloon panel in pixels.
  39. *
  40. * @observable
  41. * @default 0
  42. * @member {Number} #left
  43. */
  44. this.set( 'left', 0 );
  45. /**
  46. * Balloon panel's current position. The position name is reflected in the CSS class set
  47. * to the balloon, i.e. `.ck-balloon-panel_arrow_se` for "arrow_se" position. The class
  48. * controls the minor aspects of the balloon's visual appearance like placement
  49. * of the "arrow". To support a new position, an additional CSS must be created.
  50. *
  51. * Default position names correspond with
  52. * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
  53. *
  54. * See {@link #attachTo} to learn about custom balloon positions.
  55. *
  56. * See {@link #withArrow}.
  57. *
  58. * @observable
  59. * @default 'arrow_se'
  60. * @member {'arrow_se'|'arrow_sw'|'arrow_ne'|'arrow_nw'} #position
  61. */
  62. this.set( 'position', 'arrow_se' );
  63. /**
  64. * Controls whether the balloon panel is visible or not.
  65. *
  66. * @observable
  67. * @default false
  68. * @member {Boolean} #isVisible
  69. */
  70. this.set( 'isVisible', false );
  71. /**
  72. * Controls whether the balloon panel has an arrow. The presence of the arrow
  73. * is reflected in `ck-balloon-panel_with-arrow` CSS class.
  74. *
  75. * @observable
  76. * @default true
  77. * @member {Boolean} #withArrow
  78. */
  79. this.set( 'withArrow', true );
  80. /**
  81. * Max width of the balloon panel, as in CSS.
  82. *
  83. * @observable
  84. * @member {Number} #maxWidth
  85. */
  86. /**
  87. * A callback that starts pining the panel when {@link #isVisible} gets
  88. * `true`. Used by {@link #pin}.
  89. *
  90. * @private
  91. * @member {Function} #_pinWhenIsVisibleCallback
  92. */
  93. /**
  94. * Collection of the child views which creates balloon panel contents.
  95. *
  96. * @readonly
  97. * @member {module:ui/viewcollection~ViewCollection}
  98. */
  99. this.content = this.createCollection();
  100. this.template = new Template( {
  101. tag: 'div',
  102. attributes: {
  103. class: [
  104. 'ck-balloon-panel',
  105. bind.to( 'position', ( value ) => `ck-balloon-panel_${ value }` ),
  106. bind.if( 'isVisible', 'ck-balloon-panel_visible' ),
  107. bind.if( 'withArrow', 'ck-balloon-panel_with-arrow' )
  108. ],
  109. style: {
  110. top: bind.to( 'top', toPx ),
  111. left: bind.to( 'left', toPx ),
  112. maxWidth: bind.to( 'maxWidth', toPx )
  113. },
  114. // Make this element `focusable` to be available for adding to FocusTracker.
  115. tabindex: -1
  116. },
  117. children: this.content
  118. } );
  119. }
  120. /**
  121. * Shows the balloon panel.
  122. *
  123. * See {@link #isVisible}.
  124. */
  125. show() {
  126. this.isVisible = true;
  127. }
  128. /**
  129. * Hides the balloon panel.
  130. *
  131. * See {@link #isVisible}.
  132. */
  133. hide() {
  134. this.isVisible = false;
  135. }
  136. /**
  137. * Attaches the balloon panel to a specified DOM element or range with a smart heuristics.
  138. *
  139. * See {@link @link module:utils/dom/position~getOptimalPosition}.
  140. *
  141. * TODO: More docs and examples.
  142. *
  143. * @param {module:utils/dom/position~Options} options Positioning options compatible with
  144. * {@link module:utils/dom/position~getOptimalPosition}. Default `positions` array is
  145. * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
  146. */
  147. attachTo( options ) {
  148. this.show();
  149. const defaultPositions = BalloonPanelView.defaultPositions;
  150. const positionOptions = Object.assign( {}, {
  151. element: this.element,
  152. positions: [
  153. defaultPositions.se,
  154. defaultPositions.sw,
  155. defaultPositions.ne,
  156. defaultPositions.nw
  157. ],
  158. limiter: defaultLimiterElement,
  159. fitInViewport: true
  160. }, options );
  161. const { top, left, name: position } = getOptimalPosition( positionOptions );
  162. Object.assign( this, { top, left, position } );
  163. }
  164. /**
  165. * Works the same way as {module:ui/panel/balloon/balloonpanelview~BalloonPanelView.attachTo}
  166. * except that the position of the panel is continuously updated when any ancestor of the
  167. * {@link module:utils/dom/position~Options#target} or {@link module:utils/dom/position~Options#limiter}
  168. * is being scrolled or when the browser window is being resized.
  169. *
  170. * Thanks to this, the panel always sticks to the {@link module:utils/dom/position~Options#target}.
  171. *
  172. * See: {@link #unpin}.
  173. *
  174. * @param {module:utils/dom/position~Options} options Positioning options compatible with
  175. * {@link module:utils/dom/position~getOptimalPosition}. Default `positions` array is
  176. * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
  177. */
  178. pin( options ) {
  179. this.unpin();
  180. this._pinWhenIsVisibleCallback = () => {
  181. if ( this.isVisible ) {
  182. this._startPinning( options );
  183. } else {
  184. this._stopPinning();
  185. }
  186. };
  187. this._startPinning( options );
  188. // Control the state of the listeners depending on whether the panel is visible
  189. // or not.
  190. // TODO: Use on() (https://github.com/ckeditor/ckeditor5-utils/issues/144).
  191. this.listenTo( this, 'change:isVisible', this._pinWhenIsVisibleCallback );
  192. }
  193. /**
  194. * Stops pinning the panel, as set up by {@link #pin}.
  195. */
  196. unpin() {
  197. if ( this._pinWhenIsVisibleCallback ) {
  198. // Deactivate listeners attached by pin().
  199. this._stopPinning();
  200. // Deactivate the panel pin() control logic.
  201. // TODO: Use off() (https://github.com/ckeditor/ckeditor5-utils/issues/144).
  202. this.stopListening( this, 'change:isVisible', this._pinWhenIsVisibleCallback );
  203. this._pinWhenIsVisibleCallback = null;
  204. this.hide();
  205. }
  206. }
  207. /**
  208. * Starts managing the pinned state of the panel. See {@link #pin}.
  209. *
  210. * @private
  211. * @param {module:utils/dom/position~Options} options Positioning options compatible with
  212. * {@link module:utils/dom/position~getOptimalPosition}.
  213. */
  214. _startPinning( options ) {
  215. this.attachTo( options );
  216. const limiter = options.limiter || defaultLimiterElement;
  217. let target = null;
  218. // We need to take HTMLElement related to the target if it is possible.
  219. if ( isElement( options.target ) ) {
  220. target = options.target;
  221. } else if ( isRange( options.target ) ) {
  222. target = options.target.commonAncestorContainer;
  223. }
  224. // Then we need to listen on scroll event of eny element in the document.
  225. this.listenTo( global.document, 'scroll', ( evt, domEvt ) => {
  226. // We need to update position if scrolled element contains related to the balloon elements.
  227. if ( ( target && domEvt.target.contains( target ) ) || domEvt.target.contains( limiter ) ) {
  228. this.attachTo( options );
  229. }
  230. }, { useCapture: true } );
  231. // We need to listen on window resize event and update position.
  232. this.listenTo( global.window, 'resize', () => {
  233. this.attachTo( options );
  234. } );
  235. }
  236. /**
  237. * Stops managing the pinned state of the panel. See {@link #pin}.
  238. *
  239. * @private
  240. */
  241. _stopPinning() {
  242. this.stopListening( global.document, 'scroll' );
  243. this.stopListening( global.window, 'resize' );
  244. }
  245. }
  246. /**
  247. * A horizontal offset of the arrow tip from the edge of the balloon. Controlled by CSS.
  248. *
  249. * +-----|---------...
  250. * | |
  251. * | |
  252. * | |
  253. * | |
  254. * +--+ | +------...
  255. * \ | /
  256. * \|/
  257. * >|-----|<---------------- horizontal offset
  258. *
  259. * @default 30
  260. * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowHorizontalOffset
  261. */
  262. BalloonPanelView.arrowHorizontalOffset = 30;
  263. /**
  264. * A vertical offset of the arrow from the edge of the balloon. Controlled by CSS.
  265. *
  266. * +-------------...
  267. * |
  268. * |
  269. * | /-- vertical offset
  270. * | V
  271. * +--+ +-----... ---------
  272. * \ / |
  273. * \/ |
  274. * -------------------------------
  275. * ^
  276. *
  277. * @default 15
  278. * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowVerticalOffset
  279. */
  280. BalloonPanelView.arrowVerticalOffset = 15;
  281. /**
  282. * A default set of positioning functions used by the balloon panel view
  283. * when attaching using {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo} method.
  284. *
  285. * The available positioning functions are as follows:
  286. *
  287. * * South east:
  288. *
  289. * [ Target ]
  290. * ^
  291. * +-----------------+
  292. * | Balloon |
  293. * +-----------------+
  294. *
  295. *
  296. * * South west:
  297. *
  298. * [ Target ]
  299. * ^
  300. * +-----------------+
  301. * | Balloon |
  302. * +-----------------+
  303. *
  304. *
  305. * * North east:
  306. *
  307. * +-----------------+
  308. * | Balloon |
  309. * +-----------------+
  310. * V
  311. * [ Target ]
  312. *
  313. *
  314. * * North west:
  315. *
  316. * +-----------------+
  317. * | Balloon |
  318. * +-----------------+
  319. * V
  320. * [ Target ]
  321. *
  322. * See {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo}.
  323. *
  324. * Positioning functions must be compatible with {@link module:utils/dom/position~Position}.
  325. *
  326. * The name that position function returns will be reflected in balloon panel's class that
  327. * controls the placement of the "arrow". See {@link #position} to learn more.
  328. *
  329. * @member {Object} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions
  330. */
  331. BalloonPanelView.defaultPositions = {
  332. se: ( targetRect ) => ( {
  333. top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
  334. left: targetRect.left + targetRect.width / 2 - BalloonPanelView.arrowHorizontalOffset,
  335. name: 'arrow_se'
  336. } ),
  337. sw: ( targetRect, balloonRect ) => ( {
  338. top: targetRect.bottom + BalloonPanelView.arrowVerticalOffset,
  339. left: targetRect.left + targetRect.width / 2 - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  340. name: 'arrow_sw'
  341. } ),
  342. ne: ( targetRect, balloonRect ) => ( {
  343. top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
  344. left: targetRect.left + targetRect.width / 2 - BalloonPanelView.arrowHorizontalOffset,
  345. name: 'arrow_ne'
  346. } ),
  347. nw: ( targetRect, balloonRect ) => ( {
  348. top: targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset,
  349. left: targetRect.left + targetRect.width / 2 - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  350. name: 'arrow_nw'
  351. } )
  352. };