utils.js 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294
  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 ui/dropdown/utils
  7. */
  8. import DropdownPanelView from './dropdownpanelview';
  9. import DropdownView from './dropdownview';
  10. import DropdownButtonView from './button/dropdownbuttonview';
  11. import ToolbarView from '../toolbar/toolbarview';
  12. import ListView from '../list/listview';
  13. import ListItemView from '../list/listitemview';
  14. import ListSeparatorView from '../list/listseparatorview';
  15. import ButtonView from '../button/buttonview';
  16. import SwitchButtonView from '../button/switchbuttonview';
  17. import clickOutsideHandler from '../bindings/clickoutsidehandler';
  18. import '../../theme/components/dropdown/toolbardropdown.css';
  19. import '../../theme/components/dropdown/listdropdown.css';
  20. /**
  21. * A helper for creating dropdowns. It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown},
  22. * with a {@link module:ui/dropdown/button/dropdownbutton~DropdownButton button},
  23. * {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView panel} and all standard dropdown's behaviors.
  24. *
  25. * # Creating dropdowns
  26. *
  27. * By default, the default {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView} class is used as
  28. * definition of the button:
  29. *
  30. * const dropdown = createDropdown( model );
  31. *
  32. * // Configure dropdown's button properties:
  33. * dropdown.buttonView.set( {
  34. * label: 'A dropdown',
  35. * withText: true
  36. * } );
  37. *
  38. * dropdown.render();
  39. *
  40. * // Will render a dropdown labeled "A dropdown" with an empty panel.
  41. * document.body.appendChild( dropdown.element );
  42. *
  43. * You can also provide other button views (they need to implement the
  44. * {@link module:ui/dropdown/button/dropdownbutton~DropdownButton} interface). For instance, you can use
  45. * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} to create a dropdown with a split button.
  46. *
  47. * const dropdown = createDropdown( model, SplitButtonView );
  48. *
  49. * // Configure dropdown's button properties:
  50. * dropdown.buttonView.set( {
  51. * label: 'A dropdown',
  52. * withText: true
  53. * } );
  54. *
  55. * dropdown.buttonView.on( 'execute', () => {
  56. * // Add the behavior of the "action part" of the split button.
  57. * // Split button consists of the "action part" and "arrow part".
  58. * // The arrow opens the dropdown while the action part can have some other behavior.
  59. * } );
  60. *
  61. * dropdown.render();
  62. *
  63. * // Will render a dropdown labeled "A dropdown" with an empty panel.
  64. * document.body.appendChild( dropdown.element );
  65. *
  66. * # Adding content to the dropdown's panel
  67. *
  68. * The content of the panel can be inserted directly into the `dropdown.panelView.element`:
  69. *
  70. * dropdown.panelView.element.textContent = 'Content of the panel';
  71. *
  72. * However, most of the time you will want to add there either a {@link module:ui/list/listview~ListView list of options}
  73. * or a list of buttons (i.e. a {@link module:ui/toolbar/toolbarview~ToolbarView toolbar}).
  74. * To simplify the task, you can use, respectively, {@link module:ui/dropdown/utils~addListToDropdown} or
  75. * {@link module:ui/dropdown/utils~addToolbarToDropdown} utils.
  76. *
  77. * @param {module:utils/locale~Locale} locale The locale instance.
  78. * @param {Function} ButtonClass The dropdown button view class. Needs to implement the
  79. * {@link module:ui/dropdown/button/dropdownbutton~DropdownButton} interface.
  80. * @returns {module:ui/dropdown/dropdownview~DropdownView} The dropdown view instance.
  81. */
  82. export function createDropdown( locale, ButtonClass = DropdownButtonView ) {
  83. const buttonView = new ButtonClass( locale );
  84. const panelView = new DropdownPanelView( locale );
  85. const dropdownView = new DropdownView( locale, buttonView, panelView );
  86. buttonView.bind( 'isEnabled' ).to( dropdownView );
  87. if ( buttonView instanceof DropdownButtonView ) {
  88. buttonView.bind( 'isOn' ).to( dropdownView, 'isOpen' );
  89. } else {
  90. buttonView.arrowView.bind( 'isOn' ).to( dropdownView, 'isOpen' );
  91. }
  92. addDefaultBehavior( dropdownView );
  93. return dropdownView;
  94. }
  95. /**
  96. * Adds an instance of {@link module:ui/toolbar/toolbarview~ToolbarView} to a dropdown.
  97. *
  98. * const buttons = [];
  99. *
  100. * // Either create a new ButtonView instance or create existing.
  101. * buttons.push( new ButtonView() );
  102. * buttons.push( editor.ui.componentFactory.get( 'someButton' ) );
  103. *
  104. * const dropdown = createDropdown( locale );
  105. *
  106. * addToolbarToDropdown( dropdown, buttons );
  107. *
  108. * dropdown.toolbarView.isVertical = true;
  109. *
  110. * // Will render a vertical button dropdown labeled "A button dropdown"
  111. * // with a button group in the panel containing two buttons.
  112. * dropdown.render()
  113. * document.body.appendChild( dropdown.element );
  114. *
  115. * See {@link module:ui/dropdown/utils~createDropdown} and {@link module:ui/toolbar/toolbarview~ToolbarView}.
  116. *
  117. * @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView A dropdown instance to which `ToolbarView` will be added.
  118. * @param {Iterable.<module:ui/button/buttonview~ButtonView>} buttons
  119. */
  120. export function addToolbarToDropdown( dropdownView, buttons ) {
  121. const locale = dropdownView.locale;
  122. const t = locale.t;
  123. const toolbarView = dropdownView.toolbarView = new ToolbarView( locale );
  124. toolbarView.set( 'ariaLabel', t( 'Dropdown toolbar' ) );
  125. dropdownView.extendTemplate( {
  126. attributes: {
  127. class: [ 'ck-toolbar-dropdown' ]
  128. }
  129. } );
  130. buttons.map( view => toolbarView.items.add( view ) );
  131. dropdownView.panelView.children.add( toolbarView );
  132. toolbarView.items.delegate( 'execute' ).to( dropdownView );
  133. }
  134. /**
  135. * Adds an instance of {@link module:ui/list/listview~ListView} to a dropdown.
  136. *
  137. * const items = new Collection();
  138. *
  139. * items.add( {
  140. * type: 'button',
  141. * model: new Model( {
  142. * withText: true,
  143. * label: 'First item',
  144. * labelStyle: 'color: red'
  145. * } )
  146. * } );
  147. *
  148. * items.add( {
  149. * type: 'button',
  150. * model: new Model( {
  151. * withText: true,
  152. * label: 'Second item',
  153. * labelStyle: 'color: green',
  154. * class: 'foo'
  155. * } )
  156. * } );
  157. *
  158. * const dropdown = createDropdown( locale );
  159. *
  160. * addListToDropdown( dropdown, items );
  161. *
  162. * // Will render a dropdown with a list in the panel containing two items.
  163. * dropdown.render()
  164. * document.body.appendChild( dropdown.element );
  165. *
  166. * The `items` collection passed to this methods controls the presence and attributes of respective
  167. * {@link module:ui/list/listitemview~ListItemView list items}.
  168. *
  169. *
  170. * See {@link module:ui/dropdown/utils~createDropdown} and {@link module:list/list~List}.
  171. *
  172. * @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView A dropdown instance to which `ListVIew` will be added.
  173. * @param {Iterable.<module:ui/dropdown/utils~ListDropdownItemDefinition>} items
  174. * A collection of the list item definitions to populate the list.
  175. */
  176. export function addListToDropdown( dropdownView, items ) {
  177. const locale = dropdownView.locale;
  178. const listView = dropdownView.listView = new ListView( locale );
  179. listView.items.bindTo( items ).using( ( { type, model } ) => {
  180. if ( type === 'separator' ) {
  181. return new ListSeparatorView( locale );
  182. } else if ( type === 'button' || type === 'switchbutton' ) {
  183. const listItemView = new ListItemView( locale );
  184. let buttonView;
  185. if ( type === 'button' ) {
  186. buttonView = new ButtonView( locale );
  187. } else {
  188. buttonView = new SwitchButtonView( locale );
  189. }
  190. // Bind all model properties to the button view.
  191. buttonView.bind( ...Object.keys( model ) ).to( model );
  192. buttonView.delegate( 'execute' ).to( listItemView );
  193. listItemView.children.add( buttonView );
  194. return listItemView;
  195. }
  196. } );
  197. dropdownView.panelView.children.add( listView );
  198. listView.items.delegate( 'execute' ).to( dropdownView );
  199. }
  200. // Add a set of default behaviors to dropdown view.
  201. //
  202. // @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView
  203. function addDefaultBehavior( dropdownView ) {
  204. closeDropdownOnBlur( dropdownView );
  205. closeDropdownOnExecute( dropdownView );
  206. focusDropdownContentsOnArrows( dropdownView );
  207. }
  208. // Adds a behavior to a dropdownView that closes opened dropdown when user clicks outside the dropdown.
  209. //
  210. // @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView
  211. function closeDropdownOnBlur( dropdownView ) {
  212. dropdownView.on( 'render', () => {
  213. clickOutsideHandler( {
  214. emitter: dropdownView,
  215. activator: () => dropdownView.isOpen,
  216. callback: () => {
  217. dropdownView.isOpen = false;
  218. },
  219. contextElements: [ dropdownView.element ]
  220. } );
  221. } );
  222. }
  223. // Adds a behavior to a dropdownView that closes the dropdown view on "execute" event.
  224. //
  225. // @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView
  226. function closeDropdownOnExecute( dropdownView ) {
  227. // Close the dropdown when one of the list items has been executed.
  228. dropdownView.on( 'execute', evt => {
  229. // Toggling a switch button view should not close the dropdown.
  230. if ( evt.source instanceof SwitchButtonView ) {
  231. return;
  232. }
  233. dropdownView.isOpen = false;
  234. } );
  235. }
  236. // Adds a behavior to a dropdownView that focuses the dropdown's panel view contents on keystrokes.
  237. //
  238. // @param {module:ui/dropdown/dropdownview~DropdownView} dropdownView
  239. function focusDropdownContentsOnArrows( dropdownView ) {
  240. // If the dropdown panel is already open, the arrow down key should focus the first child of the #panelView.
  241. dropdownView.keystrokes.set( 'arrowdown', ( data, cancel ) => {
  242. if ( dropdownView.isOpen ) {
  243. dropdownView.panelView.focus();
  244. cancel();
  245. }
  246. } );
  247. // If the dropdown panel is already open, the arrow up key should focus the last child of the #panelView.
  248. dropdownView.keystrokes.set( 'arrowup', ( data, cancel ) => {
  249. if ( dropdownView.isOpen ) {
  250. dropdownView.panelView.focusLast();
  251. cancel();
  252. }
  253. } );
  254. }
  255. /**
  256. * A definition of the list item used by the {@link module:ui/dropdown/utils~addListToDropdown}
  257. * utility.
  258. *
  259. * @typedef {Object} module:ui/dropdown/utils~ListDropdownItemDefinition
  260. *
  261. * @property {String} type Either `'separator'`, `'button'` or `'switchbutton'`.
  262. * @property {module:ui/model~Model} [model] Model of the item (when **not** `'separator'`).
  263. * Its properties fuel the newly created list item (or its children, depending on the `type`).
  264. */