utils.js 8.7 KB

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