balloonpanelview.js 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663
  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 preventDefault from '../../bindings/preventdefault.js';
  15. import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  16. const toPx = toUnit( 'px' );
  17. const defaultLimiterElement = global.document.body;
  18. /**
  19. * The balloon panel view class.
  20. *
  21. * @extends module:ui/view~View
  22. */
  23. export default class BalloonPanelView extends View {
  24. /**
  25. * @inheritDoc
  26. */
  27. constructor( locale ) {
  28. super( locale );
  29. const bind = this.bindTemplate;
  30. /**
  31. * The absolute top position of the balloon panel in pixels.
  32. *
  33. * @observable
  34. * @default 0
  35. * @member {Number} #top
  36. */
  37. this.set( 'top', 0 );
  38. /**
  39. * The absolute left position of the balloon panel in pixels.
  40. *
  41. * @observable
  42. * @default 0
  43. * @member {Number} #left
  44. */
  45. this.set( 'left', 0 );
  46. /**
  47. * Balloon panel's current position. The position name is reflected in the CSS class set
  48. * to the balloon, i.e. `.ck-balloon-panel_arrow_nw` for "arrow_nw" position. The class
  49. * controls the minor aspects of the balloon's visual appearance like placement
  50. * of the "arrow". To support a new position, an additional CSS must be created.
  51. *
  52. * Default position names correspond with
  53. * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
  54. *
  55. * See {@link #attachTo} to learn about custom balloon positions.
  56. *
  57. * See {@link #withArrow}.
  58. *
  59. * @observable
  60. * @default 'arrow_nw'
  61. * @member {'arrow_nw'|'arrow_ne'|'arrow_sw'|'arrow_se'} #position
  62. */
  63. this.set( 'position', 'arrow_nw' );
  64. /**
  65. * Controls whether the balloon panel is visible or not.
  66. *
  67. * @observable
  68. * @default false
  69. * @member {Boolean} #isVisible
  70. */
  71. this.set( 'isVisible', false );
  72. /**
  73. * Controls whether the balloon panel has an arrow. The presence of the arrow
  74. * is reflected in `ck-balloon-panel_with-arrow` CSS class.
  75. *
  76. * @observable
  77. * @default true
  78. * @member {Boolean} #withArrow
  79. */
  80. this.set( 'withArrow', true );
  81. /**
  82. * Additional css class added to the {#element}.
  83. *
  84. * @observable
  85. * @member {String} #className
  86. */
  87. this.set( 'className' );
  88. /**
  89. * A callback that starts pining the panel when {@link #isVisible} gets
  90. * `true`. Used by {@link #pin}.
  91. *
  92. * @private
  93. * @member {Function} #_pinWhenIsVisibleCallback
  94. */
  95. /**
  96. * Collection of the child views which creates balloon panel contents.
  97. *
  98. * @readonly
  99. * @member {module:ui/viewcollection~ViewCollection}
  100. */
  101. this.content = this.createCollection();
  102. this.template = new Template( {
  103. tag: 'div',
  104. attributes: {
  105. class: [
  106. 'ck-balloon-panel',
  107. bind.to( 'position', value => `ck-balloon-panel_${ value }` ),
  108. bind.if( 'isVisible', 'ck-balloon-panel_visible' ),
  109. bind.if( 'withArrow', 'ck-balloon-panel_with-arrow' ),
  110. bind.to( 'className' )
  111. ],
  112. style: {
  113. top: bind.to( 'top', toPx ),
  114. left: bind.to( 'left', toPx )
  115. }
  116. },
  117. children: this.content,
  118. on: {
  119. // https://github.com/ckeditor/ckeditor5-ui/issues/206
  120. mousedown: preventDefault( this ),
  121. // https://github.com/ckeditor/ckeditor5-ui/issues/243
  122. selectstart: bind.to( evt => evt.preventDefault() )
  123. }
  124. } );
  125. }
  126. /**
  127. * Shows the balloon panel.
  128. *
  129. * See {@link #isVisible}.
  130. */
  131. show() {
  132. this.isVisible = true;
  133. }
  134. /**
  135. * Hides the balloon panel.
  136. *
  137. * See {@link #isVisible}.
  138. */
  139. hide() {
  140. this.isVisible = false;
  141. }
  142. /**
  143. * Attaches the balloon panel to a specified DOM element or range with a smart heuristics.
  144. *
  145. * See {@link @link module:utils/dom/position~getOptimalPosition}.
  146. *
  147. * TODO: More docs and examples.
  148. *
  149. * @param {module:utils/dom/position~Options} options Positioning options compatible with
  150. * {@link module:utils/dom/position~getOptimalPosition}. Default `positions` array is
  151. * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
  152. */
  153. attachTo( options ) {
  154. this.show();
  155. const defaultPositions = BalloonPanelView.defaultPositions;
  156. const positionOptions = Object.assign( {}, {
  157. element: this.element,
  158. positions: [
  159. defaultPositions.southArrowNorthWest,
  160. defaultPositions.southArrowNorthEast,
  161. defaultPositions.northArrowSouthWest,
  162. defaultPositions.northArrowSouthEast
  163. ],
  164. limiter: defaultLimiterElement,
  165. fitInViewport: true
  166. }, options );
  167. const { top, left, name: position } = getOptimalPosition( positionOptions );
  168. Object.assign( this, { top, left, position } );
  169. }
  170. /**
  171. * Works the same way as {module:ui/panel/balloon/balloonpanelview~BalloonPanelView.attachTo}
  172. * except that the position of the panel is continuously updated when any ancestor of the
  173. * {@link module:utils/dom/position~Options#target} or {@link module:utils/dom/position~Options#limiter}
  174. * is being scrolled or when the browser window is being resized.
  175. *
  176. * Thanks to this, the panel always sticks to the {@link module:utils/dom/position~Options#target}.
  177. *
  178. * See: {@link #unpin}.
  179. *
  180. * @param {module:utils/dom/position~Options} options Positioning options compatible with
  181. * {@link module:utils/dom/position~getOptimalPosition}. Default `positions` array is
  182. * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
  183. */
  184. pin( options ) {
  185. this.unpin();
  186. this._pinWhenIsVisibleCallback = () => {
  187. if ( this.isVisible ) {
  188. this._startPinning( options );
  189. } else {
  190. this._stopPinning();
  191. }
  192. };
  193. this._startPinning( options );
  194. // Control the state of the listeners depending on whether the panel is visible
  195. // or not.
  196. // TODO: Use on() (https://github.com/ckeditor/ckeditor5-utils/issues/144).
  197. this.listenTo( this, 'change:isVisible', this._pinWhenIsVisibleCallback );
  198. }
  199. /**
  200. * Stops pinning the panel, as set up by {@link #pin}.
  201. */
  202. unpin() {
  203. if ( this._pinWhenIsVisibleCallback ) {
  204. // Deactivate listeners attached by pin().
  205. this._stopPinning();
  206. // Deactivate the panel pin() control logic.
  207. // TODO: Use off() (https://github.com/ckeditor/ckeditor5-utils/issues/144).
  208. this.stopListening( this, 'change:isVisible', this._pinWhenIsVisibleCallback );
  209. this._pinWhenIsVisibleCallback = null;
  210. this.hide();
  211. }
  212. }
  213. /**
  214. * Starts managing the pinned state of the panel. See {@link #pin}.
  215. *
  216. * @private
  217. * @param {module:utils/dom/position~Options} options Positioning options compatible with
  218. * {@link module:utils/dom/position~getOptimalPosition}.
  219. */
  220. _startPinning( options ) {
  221. this.attachTo( options );
  222. const targetElement = getDomElement( options.target );
  223. const limiterElement = options.limiter ? getDomElement( options.limiter ) : defaultLimiterElement;
  224. // Then we need to listen on scroll event of eny element in the document.
  225. this.listenTo( global.document, 'scroll', ( evt, domEvt ) => {
  226. const scrollTarget = domEvt.target;
  227. // The position needs to be updated if the positioning target is within the scrolled element.
  228. const isWithinScrollTarget = targetElement && scrollTarget.contains( targetElement );
  229. // The position needs to be updated if the positioning limiter is within the scrolled element.
  230. const isLimiterWithinScrollTarget = limiterElement && scrollTarget.contains( limiterElement );
  231. // The positioning target and/or limiter can be a Rect, object etc..
  232. // There's no way to optimize the listener then.
  233. if ( isWithinScrollTarget || isLimiterWithinScrollTarget || !targetElement || !limiterElement ) {
  234. this.attachTo( options );
  235. }
  236. }, { useCapture: true } );
  237. // We need to listen on window resize event and update position.
  238. this.listenTo( global.window, 'resize', () => {
  239. this.attachTo( options );
  240. } );
  241. }
  242. /**
  243. * Stops managing the pinned state of the panel. See {@link #pin}.
  244. *
  245. * @private
  246. */
  247. _stopPinning() {
  248. this.stopListening( global.document, 'scroll' );
  249. this.stopListening( global.window, 'resize' );
  250. }
  251. }
  252. // Returns the DOM element for given object or null, if there's none,
  253. // e.g. when passed object is a Rect instance or so.
  254. //
  255. // @private
  256. // @param {*} object
  257. // @returns {HTMLElement|null}
  258. function getDomElement( object ) {
  259. if ( isElement( object ) ) {
  260. return object;
  261. }
  262. if ( isRange( object ) ) {
  263. return object.commonAncestorContainer;
  264. }
  265. if ( typeof object == 'function' ) {
  266. return getDomElement( object() );
  267. }
  268. return null;
  269. }
  270. /**
  271. * A horizontal offset of the arrow tip from the edge of the balloon. Controlled by CSS.
  272. *
  273. * +-----|---------...
  274. * | |
  275. * | |
  276. * | |
  277. * | |
  278. * +--+ | +------...
  279. * \ | /
  280. * \|/
  281. * >|-----|<---------------- horizontal offset
  282. *
  283. * @default 30
  284. * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowHorizontalOffset
  285. */
  286. BalloonPanelView.arrowHorizontalOffset = 30;
  287. /**
  288. * A vertical offset of the arrow from the edge of the balloon. Controlled by CSS.
  289. *
  290. * +-------------...
  291. * |
  292. * |
  293. * | /-- vertical offset
  294. * | V
  295. * +--+ +-----... ---------
  296. * \ / |
  297. * \/ |
  298. * -------------------------------
  299. * ^
  300. *
  301. * @default 15
  302. * @member {Number} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.arrowVerticalOffset
  303. */
  304. BalloonPanelView.arrowVerticalOffset = 15;
  305. /**
  306. * A default set of positioning functions used by the balloon panel view
  307. * when attaching using {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo} method.
  308. *
  309. * The available positioning functions are as follow:
  310. *
  311. * **North**
  312. *
  313. * * `northArrowSouth`
  314. *
  315. * +-----------------+
  316. * | Balloon |
  317. * +-----------------+
  318. * V
  319. * [ Target ]
  320. *
  321. * * `northArrowSouthEast`
  322. *
  323. * +-----------------+
  324. * | Balloon |
  325. * +-----------------+
  326. * V
  327. * [ Target ]
  328. *
  329. * * `northArrowSouthWest`
  330. *
  331. * +-----------------+
  332. * | Balloon |
  333. * +-----------------+
  334. * V
  335. * [ Target ]
  336. *
  337. * **North west**
  338. *
  339. * * `northWestArrowSouth`
  340. *
  341. * +-----------------+
  342. * | Balloon |
  343. * +-----------------+
  344. * V
  345. * [ Target ]
  346. *
  347. * * `northWestArrowSouthWest`
  348. *
  349. * +-----------------+
  350. * | Balloon |
  351. * +-----------------+
  352. * V
  353. * [ Target ]
  354. *
  355. * * `northWestArrowSouthEast`
  356. *
  357. * +-----------------+
  358. * | Balloon |
  359. * +-----------------+
  360. * V
  361. * [ Target ]
  362. *
  363. * **North east**
  364. *
  365. * * `northEastArrowSouth`
  366. *
  367. * +-----------------+
  368. * | Balloon |
  369. * +-----------------+
  370. * V
  371. * [ Target ]
  372. *
  373. * * `northEastArrowSouthEast`
  374. *
  375. * +-----------------+
  376. * | Balloon |
  377. * +-----------------+
  378. * V
  379. * [ Target ]
  380. *
  381. * * `northEastArrowSouthWest`
  382. *
  383. * +-----------------+
  384. * | Balloon |
  385. * +-----------------+
  386. * V
  387. * [ Target ]
  388. *
  389. * **South**
  390. *
  391. * * `southArrowNorth`
  392. *
  393. * [ Target ]
  394. * ^
  395. * +-----------------+
  396. * | Balloon |
  397. * +-----------------+
  398. *
  399. * * `southArrowNorthEast`
  400. *
  401. * [ Target ]
  402. * ^
  403. * +-----------------+
  404. * | Balloon |
  405. * +-----------------+
  406. *
  407. * * `southArrowNorthWest`
  408. *
  409. * [ Target ]
  410. * ^
  411. * +-----------------+
  412. * | Balloon |
  413. * +-----------------+
  414. *
  415. * **South west**
  416. *
  417. * * `southWestArrowNorth`
  418. *
  419. * [ Target ]
  420. * ^
  421. * +-----------------+
  422. * | Balloon |
  423. * +-----------------+
  424. *
  425. * * `southWestArrowNorthWest`
  426. *
  427. * [ Target ]
  428. * ^
  429. * +-----------------+
  430. * | Balloon |
  431. * +-----------------+
  432. *
  433. * * `southWestArrowNorthEast`
  434. *
  435. * [ Target ]
  436. * ^
  437. * +-----------------+
  438. * | Balloon |
  439. * +-----------------+
  440. *
  441. * **South east**
  442. *
  443. * * `southEastArrowNorth`
  444. *
  445. * [ Target ]
  446. * ^
  447. * +-----------------+
  448. * | Balloon |
  449. * +-----------------+
  450. *
  451. * * `southEastArrowNorthEast`
  452. *
  453. * [ Target ]
  454. * ^
  455. * +-----------------+
  456. * | Balloon |
  457. * +-----------------+
  458. *
  459. * * `southEastArrowNorthWest`
  460. *
  461. * [ Target ]
  462. * ^
  463. * +-----------------+
  464. * | Balloon |
  465. * +-----------------+
  466. *
  467. * See {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#attachTo}.
  468. *
  469. * Positioning functions must be compatible with {@link module:utils/dom/position~Position}.
  470. *
  471. * The name that position function returns will be reflected in balloon panel's class that
  472. * controls the placement of the "arrow". See {@link #position} to learn more.
  473. *
  474. * @member {Object} module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions
  475. */
  476. BalloonPanelView.defaultPositions = {
  477. // ------- North
  478. northArrowSouth: ( targetRect, balloonRect ) => ( {
  479. top: getNorthTop( targetRect, balloonRect ),
  480. left: targetRect.left + targetRect.width / 2 - balloonRect.width / 2,
  481. name: 'arrow_s'
  482. } ),
  483. northArrowSouthEast: ( targetRect, balloonRect ) => ( {
  484. top: getNorthTop( targetRect, balloonRect ),
  485. left: targetRect.left + targetRect.width / 2 - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  486. name: 'arrow_se'
  487. } ),
  488. northArrowSouthWest: ( targetRect, balloonRect ) => ( {
  489. top: getNorthTop( targetRect, balloonRect ),
  490. left: targetRect.left + targetRect.width / 2 - BalloonPanelView.arrowHorizontalOffset,
  491. name: 'arrow_sw'
  492. } ),
  493. // ------- North west
  494. northWestArrowSouth: ( targetRect, balloonRect ) => ( {
  495. top: getNorthTop( targetRect, balloonRect ),
  496. left: targetRect.left - balloonRect.width / 2,
  497. name: 'arrow_s'
  498. } ),
  499. northWestArrowSouthWest: ( targetRect, balloonRect ) => ( {
  500. top: getNorthTop( targetRect, balloonRect ),
  501. left: targetRect.left - BalloonPanelView.arrowHorizontalOffset,
  502. name: 'arrow_sw'
  503. } ),
  504. northWestArrowSouthEast: ( targetRect, balloonRect ) => ( {
  505. top: getNorthTop( targetRect, balloonRect ),
  506. left: targetRect.left - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  507. name: 'arrow_se'
  508. } ),
  509. // ------- North east
  510. northEastArrowSouth: ( targetRect, balloonRect ) => ( {
  511. top: getNorthTop( targetRect, balloonRect ),
  512. left: targetRect.right - balloonRect.width / 2,
  513. name: 'arrow_s'
  514. } ),
  515. northEastArrowSouthEast: ( targetRect, balloonRect ) => ( {
  516. top: getNorthTop( targetRect, balloonRect ),
  517. left: targetRect.right - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  518. name: 'arrow_se'
  519. } ),
  520. northEastArrowSouthWest: ( targetRect, balloonRect ) => ( {
  521. top: getNorthTop( targetRect, balloonRect ),
  522. left: targetRect.right - BalloonPanelView.arrowHorizontalOffset,
  523. name: 'arrow_sw'
  524. } ),
  525. // ------- South
  526. southArrowNorth: ( targetRect, balloonRect ) => ( {
  527. top: getSouthTop( targetRect, balloonRect ),
  528. left: targetRect.left + targetRect.width / 2 - balloonRect.width / 2,
  529. name: 'arrow_n'
  530. } ),
  531. southArrowNorthEast: ( targetRect, balloonRect ) => ( {
  532. top: getSouthTop( targetRect, balloonRect ),
  533. left: targetRect.left + targetRect.width / 2 - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  534. name: 'arrow_ne'
  535. } ),
  536. southArrowNorthWest: ( targetRect, balloonRect ) => ( {
  537. top: getSouthTop( targetRect, balloonRect ),
  538. left: targetRect.left + targetRect.width / 2 - BalloonPanelView.arrowHorizontalOffset,
  539. name: 'arrow_nw'
  540. } ),
  541. // ------- South west
  542. southWestArrowNorth: ( targetRect, balloonRect ) => ( {
  543. top: getSouthTop( targetRect, balloonRect ),
  544. left: targetRect.left - balloonRect.width / 2,
  545. name: 'arrow_n'
  546. } ),
  547. southWestArrowNorthWest: ( targetRect, balloonRect ) => ( {
  548. top: getSouthTop( targetRect, balloonRect ),
  549. left: targetRect.left - BalloonPanelView.arrowHorizontalOffset,
  550. name: 'arrow_nw'
  551. } ),
  552. southWestArrowNorthEast: ( targetRect, balloonRect ) => ( {
  553. top: getSouthTop( targetRect, balloonRect ),
  554. left: targetRect.left - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  555. name: 'arrow_ne'
  556. } ),
  557. // ------- South east
  558. southEastArrowNorth: ( targetRect, balloonRect ) => ( {
  559. top: getSouthTop( targetRect, balloonRect ),
  560. left: targetRect.right - balloonRect.width / 2,
  561. name: 'arrow_n'
  562. } ),
  563. southEastArrowNorthEast: ( targetRect, balloonRect ) => ( {
  564. top: getSouthTop( targetRect, balloonRect ),
  565. left: targetRect.right - balloonRect.width + BalloonPanelView.arrowHorizontalOffset,
  566. name: 'arrow_ne'
  567. } ),
  568. southEastArrowNorthWest: ( targetRect, balloonRect ) => ( {
  569. top: getSouthTop( targetRect, balloonRect ),
  570. left: targetRect.right - BalloonPanelView.arrowHorizontalOffset,
  571. name: 'arrow_nw'
  572. } ),
  573. };
  574. // Returns the top coordinate for positions starting with `north*`.
  575. //
  576. // @private
  577. // @param {utils/dom/rect~Rect} targetRect A rect of the target.
  578. // @param {utils/dom/rect~Rect} elementRect A rect of the balloon.
  579. // @returns {Number}
  580. function getNorthTop( targetRect, balloonRect ) {
  581. return targetRect.top - balloonRect.height - BalloonPanelView.arrowVerticalOffset;
  582. }
  583. // Returns the top coordinate for positions starting with `south*`.
  584. //
  585. // @private
  586. // @param {utils/dom/rect~Rect} targetRect A rect of the target.
  587. // @param {utils/dom/rect~Rect} elementRect A rect of the balloon.
  588. // @returns {Number}
  589. function getSouthTop( targetRect ) {
  590. return targetRect.bottom + BalloonPanelView.arrowVerticalOffset;
  591. }