8
0

buttonview.js 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module ui/button/buttonview
  7. */
  8. import View from '../view';
  9. import IconView from '../icon/iconview';
  10. import TooltipView from '../tooltip/tooltipview';
  11. import { getEnvKeystrokeText } from '@ckeditor/ckeditor5-utils/src/keyboard';
  12. /**
  13. * The button view class.
  14. *
  15. * const view = new ButtonView();
  16. *
  17. * view.set( {
  18. * label: 'A button',
  19. * keystroke: 'Ctrl+B',
  20. * tooltip: true,
  21. * withText: true
  22. * } );
  23. *
  24. * view.render();
  25. *
  26. * document.body.append( view.element );
  27. *
  28. * @extends module:ui/view~View
  29. */
  30. export default class ButtonView extends View {
  31. /**
  32. * @inheritDoc
  33. */
  34. constructor( locale ) {
  35. super( locale );
  36. const bind = this.bindTemplate;
  37. /**
  38. * The label of the button view visible to the user when {@link #withText} is `true`.
  39. * It can also be used to create a {@link #tooltip}.
  40. *
  41. * @observable
  42. * @member {String} #label
  43. */
  44. this.set( 'label' );
  45. /**
  46. * (Optional) The keystroke associated with the button, i.e. <kbd>CTRL+B</kbd>,
  47. * in the string format compatible with {@link module:utils/keyboard}.
  48. *
  49. * @observable
  50. * @member {Boolean} #keystroke
  51. */
  52. this.set( 'keystroke' );
  53. /**
  54. * (Optional) Tooltip of the button, i.e. displayed when hovering the button with the mouse cursor.
  55. *
  56. * * If defined as a `Boolean` (e.g. `true`), then combination of `label` and `keystroke` will be set as a tooltip.
  57. * * If defined as a `String`, tooltip will equal the exact text of that `String`.
  58. * * If defined as a `Function`, `label` and `keystroke` will be passed to that function, which is to return
  59. * a string with the tooltip text.
  60. *
  61. * const view = new ButtonView( locale );
  62. * view.tooltip = ( label, keystroke ) => `A tooltip for ${ label } and ${ keystroke }.`
  63. *
  64. * @observable
  65. * @default false
  66. * @member {Boolean|String|Function} #tooltip
  67. */
  68. this.set( 'tooltip' );
  69. /**
  70. * (Optional) The position of the tooltip. See {@link module:ui/tooltip/tooltipview~TooltipView#position}
  71. * to learn more about the available position values.
  72. *
  73. * **Note:** It makes sense only when the {@link #tooltip `tooltip` attribute} is defined.
  74. *
  75. * @observable
  76. * @default 's'
  77. * @member {'s'|'n'} #position
  78. */
  79. this.set( 'tooltipPosition', 's' );
  80. /**
  81. * The HTML type of the button. Default `button`.
  82. *
  83. * @observable
  84. * @member {'button'|'submit'|'reset'|'menu'} #type
  85. */
  86. this.set( 'type', 'button' );
  87. /**
  88. * Controls whether the button view is "on". It makes sense when a feature it represents
  89. * is currently active, e.g. a bold button is "on" when the selection is in the bold text.
  90. *
  91. * To disable the button, use {@link #isEnabled} instead.
  92. *
  93. * @observable
  94. * @member {Boolean} #isOn
  95. */
  96. this.set( 'isOn', false );
  97. /**
  98. * Controls whether the button view is enabled, i.e. it can be clicked and execute an action.
  99. *
  100. * To change the "on" state of the button, use {@link #isOn} instead.
  101. *
  102. * @observable
  103. * @member {Boolean} #isEnabled
  104. */
  105. this.set( 'isEnabled', true );
  106. /**
  107. * Controls whether the button view is visible. Visible by default, buttons are hidden
  108. * using a CSS class.
  109. *
  110. * @observable
  111. * @member {Boolean} #isVisible
  112. */
  113. this.set( 'isVisible', true );
  114. /**
  115. * (Optional) Controls whether the label of the button is hidden (e.g. an icon–only button).
  116. *
  117. * @observable
  118. * @member {Boolean} #withText
  119. */
  120. this.set( 'withText', false );
  121. /**
  122. * (Optional) An XML {@link module:ui/icon/iconview~IconView#content content} of the icon.
  123. * When defined, an {@link #iconView} will be added to the button.
  124. *
  125. * @observable
  126. * @member {String} #icon
  127. */
  128. this.set( 'icon' );
  129. /**
  130. * (Optional) Controls the `tabindex` HTML attribute of the button. By default, the button is focusable
  131. * but does not included in the <kbd>Tab</kbd> order.
  132. *
  133. * @observable
  134. * @default -1
  135. * @member {String} #tabindex
  136. */
  137. this.set( 'tabindex', -1 );
  138. /**
  139. * Collection of the child views inside of the button {@link #element}.
  140. *
  141. * @readonly
  142. * @member {module:ui/viewcollection~ViewCollection}
  143. */
  144. this.children = this.createCollection();
  145. /**
  146. * Tooltip of the button view. It is configurable using the {@link #tooltip tooltip attribute}.
  147. *
  148. * @readonly
  149. * @member {module:ui/tooltip/tooltipview~TooltipView} #tooltipView
  150. */
  151. this.tooltipView = this._createTooltipView();
  152. /**
  153. * Label of the button view. It is configurable using the {@link #label label attribute}.
  154. *
  155. * @readonly
  156. * @member {module:ui/view~View} #labelView
  157. */
  158. this.labelView = this._createLabelView();
  159. /**
  160. * Tooltip of the button bound to the template.
  161. *
  162. * @see #tooltip
  163. * @see #_getTooltipString
  164. * @private
  165. * @observable
  166. * @member {Boolean} #_tooltipString
  167. */
  168. this.bind( '_tooltipString' ).to(
  169. this, 'tooltip',
  170. this, 'label',
  171. this, 'keystroke',
  172. this._getTooltipString.bind( this )
  173. );
  174. /**
  175. * (Optional) The icon view of the button. Only present when the {@link #icon icon attribute} is defined.
  176. *
  177. * @readonly
  178. * @member {module:ui/icon/iconview~IconView} #iconView
  179. */
  180. this.setTemplate( {
  181. tag: 'button',
  182. attributes: {
  183. class: [
  184. 'ck-button',
  185. bind.to( 'isEnabled', value => value ? 'ck-enabled' : 'ck-disabled' ),
  186. bind.if( 'isVisible', 'ck-hidden', value => !value ),
  187. bind.to( 'isOn', value => value ? 'ck-on' : 'ck-off' ),
  188. bind.if( 'withText', 'ck-button_with-text' )
  189. ],
  190. type: bind.to( 'type', value => value ? value : 'button' ),
  191. tabindex: bind.to( 'tabindex' )
  192. },
  193. children: this.children,
  194. on: {
  195. mousedown: bind.to( evt => {
  196. evt.preventDefault();
  197. } ),
  198. click: bind.to( evt => {
  199. // We can't make the button disabled using the disabled attribute, because it won't be focusable.
  200. // Though, shouldn't this condition be moved to the button controller?
  201. if ( this.isEnabled ) {
  202. this.fire( 'execute' );
  203. } else {
  204. // Prevent the default when button is disabled, to block e.g.
  205. // automatic form submitting. See ckeditor/ckeditor5-link#74.
  206. evt.preventDefault();
  207. }
  208. } )
  209. }
  210. } );
  211. /**
  212. * Fired when the button view is clicked. It won't be fired when the button {@link #isEnabled}
  213. * is `false`.
  214. *
  215. * @event execute
  216. */
  217. }
  218. /**
  219. * @inheritDoc
  220. */
  221. render() {
  222. super.render();
  223. if ( this.icon ) {
  224. const iconView = this.iconView = new IconView();
  225. iconView.bind( 'content' ).to( this, 'icon' );
  226. this.children.add( iconView );
  227. }
  228. this.children.add( this.tooltipView );
  229. this.children.add( this.labelView );
  230. }
  231. /**
  232. * Focuses the {@link #element} of the button.
  233. */
  234. focus() {
  235. this.element.focus();
  236. }
  237. /**
  238. * Creates a {@link module:ui/tooltip/tooltipview~TooltipView} instance and binds it with button
  239. * attributes.
  240. *
  241. * @private
  242. * @returns {module:ui/tooltip/tooltipview~TooltipView}
  243. */
  244. _createTooltipView() {
  245. const tooltipView = new TooltipView();
  246. tooltipView.bind( 'text' ).to( this, '_tooltipString' );
  247. tooltipView.bind( 'position' ).to( this, 'tooltipPosition' );
  248. return tooltipView;
  249. }
  250. /**
  251. * Creates a label view instance and binds it with button attributes.
  252. *
  253. * @private
  254. * @returns {module:ui/view~View}
  255. */
  256. _createLabelView() {
  257. const labelView = new View();
  258. labelView.setTemplate( {
  259. tag: 'span',
  260. attributes: {
  261. class: [ 'ck-button__label' ]
  262. },
  263. children: [
  264. {
  265. text: this.bindTemplate.to( 'label' )
  266. }
  267. ]
  268. } );
  269. return labelView;
  270. }
  271. /**
  272. * Gets the text for the {@link #tooltipView} from the combination of
  273. * {@link #tooltip}, {@link #label} and {@link #keystroke} attributes.
  274. *
  275. * @private
  276. * @see #tooltip
  277. * @see #_tooltipString
  278. * @param {Boolean|String|Function} tooltip Button tooltip.
  279. * @param {String} label Button label.
  280. * @param {String} keystroke Button keystroke.
  281. * @returns {String}
  282. */
  283. _getTooltipString( tooltip, label, keystroke ) {
  284. if ( tooltip ) {
  285. if ( typeof tooltip == 'string' ) {
  286. return tooltip;
  287. } else {
  288. if ( keystroke ) {
  289. keystroke = getEnvKeystrokeText( keystroke );
  290. }
  291. if ( tooltip instanceof Function ) {
  292. return tooltip( label, keystroke );
  293. } else {
  294. return `${ label }${ keystroke ? ` (${ keystroke })` : '' }`;
  295. }
  296. }
  297. }
  298. return '';
  299. }
  300. }