瀏覽代碼

Improved docs.

Piotrek Koszuliński 7 年之前
父節點
當前提交
c0bc02bc6b

+ 3 - 3
packages/ckeditor5-ui/src/button/buttoninterface.jsdoc

@@ -8,9 +8,9 @@
  */
 
 /**
- * The button interface.
- *
- *		TODO
+ * The button interface. Implemented by, among others, {@link module:ui/button/buttonview~ButtonView},
+ * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} and
+ * {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}.
  *
  * @interface module:ui/button/buttoninterface~ButtonInterface
  */

+ 2 - 2
packages/ckeditor5-ui/src/dropdown/dropdownpanelview.js

@@ -69,7 +69,7 @@ export default class DropdownPanelView extends View {
 	/**
 	 * Focuses the view element or first item in view collection on opening dropdown's panel.
 	 *
-	 * See also {@link module:ui/dropdown/dropdownpanelfocusable}.
+	 * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
 	 */
 	focus() {
 		if ( this.children.length ) {
@@ -80,7 +80,7 @@ export default class DropdownPanelView extends View {
 	/**
 	 * Focuses the view element or last item in view collection on opening dropdown's panel.
 	 *
-	 * See also {@link module:ui/dropdown/dropdownpanelfocusable}.
+	 * See also {@link module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable}.
 	 */
 	focusLast() {
 		if ( this.children.length ) {

+ 39 - 5
packages/ckeditor5-ui/src/dropdown/dropdownview.js

@@ -14,13 +14,36 @@ import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
 import '../../theme/components/dropdown/dropdown.css';
 
 /**
- * The dropdown view class.
+ * The dropdown view class. It manages the dropdown button and dropdown panel.
  *
- *		const button = new ButtonView( locale );
+ * In most cases, the easiest way to create a dropdown is by using the {@link module:ui/dropdown/utils~createDropdown}
+ * util:
+ *
+ *		const dropdown = createDropdown( locale );
+ *
+ *		// Configure dropdown's button properties:
+ *		dropdown.buttonView.set( {
+ *			label: 'A dropdown',
+ *			withText: true
+ *		} );
+ *
+ *		dropdown.render();
+ *
+ *		dropdown.panelView.element.textContent = 'Content of the panel';
+ *
+ *		// Will render a dropdown with a panel containing a "Content of the panel" text.
+ *		document.body.appendChild( dropdown.element );
+ *
+ * If you want to add a richer content to the dropdown panel, you can use the {@link module:ui/dropdown/utils~addListToDropdown}
+ * and {@link module:ui/dropdown/utils~addToolbarToDropdown} helpers. See more examples in
+ * {@link module:ui/dropdown/utils~createDropdown} documentation.
+ *
+ * If you want to create a completely custom dropdown, then you can compose it manually:
+ *
+ *		const button = new DropdownButtonView( locale );
  *		const panel = new DropdownPanelView( locale );
  *		const dropdown = new DropdownView( locale, button, panel );
  *
- *		panel.element.textContent = 'Content of the panel';
  *		button.set( {
  *			label: 'A dropdown',
  *			withText: true
@@ -28,16 +51,27 @@ import '../../theme/components/dropdown/dropdown.css';
  *
  *		dropdown.render();
  *
+ *		panel.element.textContent = 'Content of the panel';
+ *
  *		// Will render a dropdown with a panel containing a "Content of the panel" text.
  *		document.body.appendChild( dropdown.element );
  *
- * Also see {@link module:ui/dropdown/utils~createDropdown} to learn about dropdown creation helper.
+ * However, dropdown created this way will contain little behavior. You will need to implement handlers for actions
+ * such as {@link module:ui/bindings/clickoutsidehandler~clickOutsideHandler clicking outside an open dropdown}
+ * (which should close it) and support for arrow keys inside the panel. Therefore, unless you really know what
+ * you do and you really need to do it, it is recommended to use the {@link module:ui/dropdown/utils~createDropdown} helper.
  *
  * @extends module:ui/view~View
  */
 export default class DropdownView extends View {
 	/**
-	 * @inheritDoc
+	 * Creates an instance of the dropdown.
+	 *
+	 * Also see {@link #render}.
+	 *
+	 * @param {module:utils/locale~Locale} [locale] The localization services instance.
+	 * @param {module:ui/dropdown/button/dropdownbuttoninterface~DropdownButtonInterface} buttonView
+	 * @param {module:ui/dropdown/dropdownpanelview~DropdownPanelView} panelView
 	 */
 	constructor( locale, buttonView, panelView ) {
 		super( locale );

+ 41 - 8
packages/ckeditor5-ui/src/dropdown/utils.js

@@ -19,10 +19,14 @@ import clickOutsideHandler from '../bindings/clickoutsidehandler';
 import '../../theme/components/dropdown/toolbardropdown.css';
 
 /**
- * A helper which creates an instance of {@link module:ui/dropdown/dropdownview~DropdownView} class with an instance of
- * a button class passed as `ButtonClass` parameter.
+ * A helper for creating dropdowns. It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown},
+ * with a {@link module:ui/dropdown/button/dropdownbuttoninterface~DropdownButtonInterface button},
+ * {@link module:ui/dropdown/dropdownpanelview~DropdownPanelView panel} and all standard dropdown's behaviors.
  *
- * The default value of `ButtonClass` is {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView} class.
+ * # Creating dropdowns
+ *
+ * By default, the default {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView} class is used as
+ * definition of the button:
  *
  *		const dropdown = createDropdown( model );
  *
@@ -37,14 +41,43 @@ import '../../theme/components/dropdown/toolbardropdown.css';
  *		// Will render a dropdown labeled "A dropdown" with an empty panel.
  *		document.body.appendChild( dropdown.element );
  *
- * The supported button classes for dropdown are:
- * * {@link module:ui/dropdown/button/dropdownbuttonview~DropdownButtonView}
- * * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView}
+ * You can also provide other button views (they need to implement the
+ * {module:ui/dropdown/button/dropdownbuttoninterface~DropdownButtonInterface} interface). For instance, you can use
+ * {@link module:ui/dropdown/button/splitbuttonview~SplitButtonView} to create a dropdown with a split button.
+ *
+ *		const dropdown = createDropdown( model, SplitButtonView );
+ *
+ *		// Configure dropdown's button properties:
+ *		dropdown.buttonView.set( {
+ *			label: 'A dropdown',
+ *			withText: true
+ *		} );
+ *
+ *		dropdown.buttonView.on( 'execute', () => {
+ *			// Add the behavior of the "action part" of the split button.
+ *			// Split button consists of the "action part" and "arrow part".
+ *			// The arrow opens the dropdown while the action part can have some other behavior.
+ * 		} );
+ *
+ *		dropdown.render();
+ *
+ *		// Will render a dropdown labeled "A dropdown" with an empty panel.
+ *		document.body.appendChild( dropdown.element );
+ *
+ * # Adding content to the dropdown's panel
+ *
+ * The content of the panel can be inserted directly into the `dropdown.panelView.element`:
+ *
+ *		dropdown.panelView.element.textContent = 'Content of the panel';
  *
- * Also see {@link module:ui/dropdown/utils~addListToDropdown} and {@link module:ui/dropdown/utils~addToolbarToDropdown}.
+ * However, most of the time you will want to add there either a {@link module:ui/list/listview~ListView list of options}
+ * or a list of buttons (i.e. a {@link module:ui/toolbar/toolbarview~ToolbarView toolbar}).
+ * To simplify the task, you can use, respectively, {@link module:ui/dropdown/utils~addListToDropdown} or
+ * {@link module:ui/dropdown/utils~addToolbarToDropdown} utils.
  *
  * @param {module:utils/locale~Locale} locale The locale instance.
- * @param {module:ui/dropdown/button/dropdownbuttoninterface~DropdownButtonInterface} ButtonClass The dropdown button view class.
+ * @param {Function} ButtonClass The dropdown button view class. Needs to implement the
+ * {@link module:ui/dropdown/button/dropdownbuttoninterface~DropdownButtonInterface} interface.
  * @returns {module:ui/dropdown/dropdownview~DropdownView} The dropdown view instance.
  */
 export function createDropdown( locale, ButtonClass = DropdownButtonView ) {

+ 1 - 1
packages/ckeditor5-ui/src/view.js

@@ -111,7 +111,7 @@ export default class View {
 		 *
 		 *		const view = new SampleView();
 		 *
-		 *		// Renders the #template
+		 *		// Renders the #template.
 		 *		view.render();
 		 *
 		 *		// Append the HTML element of the view to <body>.

+ 1 - 1
packages/ckeditor5-ui/tests/dropdown/utils.js

@@ -91,7 +91,7 @@ describe( 'utils', () => {
 			} );
 		} );
 
-		describe( 'hasDefaultBehavior', () => {
+		describe( 'has default behavior', () => {
 			describe( 'closeDropdownOnBlur()', () => {
 				beforeEach( () => {
 					dropdownView.render();