Browse Source

Merge pull request #859 from ckeditor/t/ckeditor5-highlight/3

Docs: Introduced the dropdown section in the UI library guide.
Aleksander Nowodzinski 7 years ago
parent
commit
93ce6db3ba
1 changed files with 96 additions and 2 deletions
  1. 96 2
      docs/framework/guides/architecture/ui-library.md

+ 96 - 2
docs/framework/guides/architecture/ui-library.md

@@ -72,7 +72,7 @@ class ParentView extends View {
 		this.setTemplate( {
 			tag: 'div',
 			children: [
-				childA
+				childA,
 				childB
 			]
 		} );
@@ -170,7 +170,7 @@ new Template( {
 	},
 	on: {
 		click: bind.to( 'clicked' )
-	}
+	},
 	children: [
 		'A paragraph.'
 	]
@@ -292,6 +292,100 @@ toolbar.on( 'execute', evt => {
 } );
 ```
 
+### Dropdowns
+
+The framework implements the {@link module:ui/dropdown/dropdownview~DropdownView dropdown} component which can host any sort of UI in its panel. It is composed of a {@link module:ui/dropdown/dropdownview~DropdownView#buttonView button} (to open the dropdown) and a {@link module:ui/dropdown/dropdownview~DropdownView#panelView panel} (the container).
+
+The button can be either:
+- a standard {@link module:ui/button/buttonview~ButtonView},
+- a {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView}, for more complex use–cases.
+
+The dropdown panel exposes its {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView#children children} collection which aggregates the child {@link module:ui/view~View views}. The most common views displayed in the dropdown panel are:
+- {@link module:ui/list/listview~ListView}
+- {@link module:ui/toolbar/toolbarview~ToolbarView}
+
+The framework provides a set of helpers to make the dropdown creation process easier, although it is still possible to compose a custom dropdown from scratch using the base classes.
+
+The {@link module:ui/dropdown/utils#createDropdown} helper creates a {@link module:ui/dropdown/dropdownview~DropdownView} with either a {@link module:ui/button/buttonview~ButtonView} or a {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView}.
+
+```js
+import { createDropdown } from '@ckeditor/ckeditor5-ui/src/dropdown/utils';
+import SplitButtonView from '@ckeditor/ckeditor5-ui/src/dropdown/button/splitbuttonview';
+
+const dropdownView = createDropdown( locale, SplitButtonView );
+```
+
+This kind of (default) dropdown comes with a set of behaviors:
+- It closes the panel when it loses the focus e.g. user moved the focus elsewhere,
+- It closes the panel upon the {@link module:ui/dropdown/dropdownview~DropdownView#execute `execute`} event,
+- It focuses the view hosted in the panel e.g. when navigating the toolbar using the keyboard.
+
+#### Adding a list to a dropdown
+
+The {@link module:ui/list/listview~ListView} can be added to a dropdown using the {@link module:ui/dropdown/utils#addListToDropdown} helper.
+
+```js
+import Model from '@ckeditor/ckeditor5-ui/src/model';
+import Collection from '@ckeditor/ckeditor5-utils/src/collection';
+import { addListToDropdown, createDropdown } from '@ckeditor/ckeditor5-ui/src/dropdown/utils';
+
+// The default dropdown.
+const dropdownView = createDropdown( locale );
+
+// The collection of the list items.
+const items = new Collection();
+
+items.add( new Model( { label: 'Foo' } ) );
+items.add( new Model( { label: 'Bar' } ) );
+
+// Create a dropdown with a list inside the panel.
+addListToDropdown( dropdownView, items );
+```
+
+#### Adding a toolbar to a dropdown
+
+A {@link module:ui/toolbar/toolbarview~ToolbarView} can be added to a dropdown using  the {@link module:ui/dropdown/utils#addToolbarToDropdown} helper.
+
+```js
+import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
+import { addToolbarToDropdown, createDropdown } from '@ckeditor/ckeditor5-ui/src/dropdown/utils';
+import SplitButtonView from '@ckeditor/ckeditor5-ui/src/dropdown/button/splitbuttonview';
+
+const buttons = [];
+
+// Add a simple button to the array of toolbar items.
+buttons.push( new ButtonView() );
+
+// Add another component the array of toolbar items.
+buttons.push( componentFactory.create( 'componentName' ) );
+
+const dropdownView = createDropdown( locale, SplitButtonView );
+
+// Create a dropdown with a toolbar inside the panel.
+addToolbarToDropdown( dropdownView, buttons );
+```
+
+A common practice is making the main dropdown button {@link module:ui/dropdown/dropdownview~DropdownView#isEnabled enabled} when one of the toolbar items is enabled:
+
+```js
+// Enable the dropdown's button when any of the toolbar items is enabled.
+dropdownView.bind( 'isEnabled' ).toMany( buttons, 'isEnabled',
+	( ...areEnabled ) => areEnabled.some( isEnabled => isEnabled )
+);
+```
+
+### Best practices
+
+It is advised that for the best user experience the editing view gets {@link module:engine/view/view~View#focus focused} upon any user action (e.g. executing a command) to make sure the editor retains focus:
+
+```js
+// Execute some action on dropdown#execute event.
+dropdownView.buttonView.on( 'execute', () => {
+	editor.execute( 'command', { value: ... } );
+	editor.editing.view.focus();
+} );
+```
+
 ## Keystrokes and focus management
 
 _Coming soon..._