utils.js 8.6 KB

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