瀏覽代碼

Docs: Improved grammar and wording in the UI framework dropdown docs. Extended the dropdown docs with additional content.

Aleksander Nowodzinski 7 年之前
父節點
當前提交
5689fd7a9d
共有 1 個文件被更改,包括 30 次插入31 次删除
  1. 30 31
      docs/framework/guides/architecture/ui-library.md

+ 30 - 31
docs/framework/guides/architecture/ui-library.md

@@ -294,19 +294,19 @@ toolbar.on( 'execute', evt => {
 
 ### Dropdowns
 
-A toolbar dropdown consist a toolbar button that is used to open dropdown and a view that is shown in panel view.
+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 dropdown button might be one of:
-- a standard {@link module:ui/button/buttonview~ButtonView}.
-- a {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView}.
+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 common views that are dedicated for dropdown panel are:
+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 set of helper methods that ease creation of fully functioning toolbar dropdown.
+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 will create 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}.
+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';
@@ -315,40 +315,36 @@ import SplitButtonView from '@ckeditor/ckeditor5-ui/src/dropdown/button/splitbut
 const dropdownView = createDropdown( locale, SplitButtonView );
 ```
 
-Such dropdown will have default dropdown behavior already added:
-- The dropdown will close panel when it loses focus - ie user will click outside the opened panel.
-- The dropdown will close panel on `dropdownView#execute` event.
-- The dropdown will focus panel content view on using arrows in toolbar.
+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 view to a dropdown
+#### Adding a list to a dropdown
 
-A {@link module:ui/list/listview~ListView} can be added to a dropdown using {@link module:ui/dropdown/utils~addListToDropdown} helper.
+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: 'Do Foo',
-	commandName: 'foo'
-} ) );
-
-items.add( new Model( {
-	label: 'Do Bar',
-	commandName: 'bar'
-} ) );
+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 view to a dropdown
+#### Adding a toolbar to a dropdown
 
-A {@link module:ui/list/listview~ListView} can be added to a dropdown using {@link module:ui/dropdown/utils~addListToDropdown} helper.
+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';
@@ -357,19 +353,22 @@ import SplitButtonView from '@ckeditor/ckeditor5-ui/src/dropdown/button/splitbut
 
 const buttons = [];
 
+// Add a simple button to the array of toolbar items.
 buttons.push( new ButtonView() );
-buttons.push( componentFactory.create( 'someExistingButton' ) );
+
+// Add another component the array of toolbar items.
+buttons.push( componentFactory.create( 'componentName' ) );
 
 const dropdownView = createDropdown( locale, SplitButtonView );
 
-// Make this a dropdown with toolbar inside dropdown panel.
+// Create a dropdown with a toolbar inside the panel.
 addToolbarToDropdown( dropdownView, buttons );
 ```
 
-A common behavior is making a main dropdown button enabled when one of buttons from a dropdown panel is enabled:
+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
-// This will enable toolbar button when any of button in dropdown is enabled.
+// Enable the dropdown's button when any of the toolbar items is enabled.
 dropdownView.bind( 'isEnabled' ).toMany( buttons, 'isEnabled',
 	( ...areEnabled ) => areEnabled.some( isEnabled => isEnabled )
 );
@@ -377,12 +376,12 @@ dropdownView.bind( 'isEnabled' ).toMany( buttons, 'isEnabled',
 
 ### Best practices
 
-It is advised to focus editing view upon executing dropdowns action:
+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 current some action on dropdown#execute event.
+// Execute some action on dropdown#execute event.
 dropdownView.buttonView.on( 'execute', () => {
-	editor.execute( 'command', { value: model.commandValue } );
+	editor.execute( 'command', { value: ... } );
 	editor.editing.view.focus();
 } );
 ```