浏览代码

Docs: Update Table UI plugins docs.

Maciej Gołaszewski 7 年之前
父节点
当前提交
8e78025b0f
共有 1 个文件被更改,包括 32 次插入13 次删除
  1. 32 13
      packages/ckeditor5-table/src/tableui.js

+ 32 - 13
packages/ckeditor5-table/src/tableui.js

@@ -20,7 +20,14 @@ import tableRowIcon from './../theme/icons/table-row.svg';
 import tableMergeCellIcon from './../theme/icons/table-merge-cell.svg';
 
 /**
- * The table UI plugin.
+ * The table UI plugin. It introduces:
+ *
+ * * The `'insertTable'` dropdown,
+ * * The `'tableColumn'` dropdown,
+ * * The `'tableRow'` dropdown,
+ * * The `'mergeCell'` dropdown.
+ *
+ * The `'tableColumn'`, `'tableRow'`, `'mergeCell'` are best to be used in conjunction with {@link module:table/tabletoolbar~TableToolbar}.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -37,13 +44,16 @@ export default class TableUI extends Plugin {
 
 			dropdownView.bind( 'isEnabled' ).to( command );
 
+			// Decorate dropdown's button.
 			dropdownView.buttonView.set( {
 				icon: tableIcon,
 				label: 'Insert table',
 				tooltip: true
 			} );
 
+			// Prepare custom view for dropdown's panel.
 			const insertTableView = new InsertTableView( locale );
+			dropdownView.panelView.children.add( insertTableView );
 
 			insertTableView.delegate( 'execute' ).to( dropdownView );
 
@@ -55,12 +65,9 @@ export default class TableUI extends Plugin {
 
 			dropdownView.on( 'execute', () => {
 				editor.execute( 'insertTable', { rows: insertTableView.rows, columns: insertTableView.columns } );
-
 				editor.editing.view.focus();
 			} );
 
-			dropdownView.panelView.children.add( insertTableView );
-
 			return dropdownView;
 		} );
 
@@ -101,13 +108,13 @@ export default class TableUI extends Plugin {
 	}
 
 	/**
-	 * Common method that prepares dropdown.
+	 * Creates dropdown view from set of options.
 	 *
 	 * @private
-	 * @param {String} buttonName
-	 * @param {String} icon
-	 * @param {Array.<Object>} options
-	 * @param locale
+	 * @param {String} buttonName Dropdown button name.
+	 * @param {String} icon Icon for dropdown button.
+	 * @param {Array.<module:table/tableui~DropdownOption>} options List of options for dropdown.
+	 * @param {module:utils/locale~Locale} locale
 	 * @returns {module:ui/dropdown/dropdownview~DropdownView}
 	 */
 	_prepareDropdown( buttonName, icon, options, locale ) {
@@ -116,6 +123,7 @@ export default class TableUI extends Plugin {
 		const dropdownView = createDropdown( locale );
 		const commands = [];
 
+		// Prepare dropdown list items for list dropdown.
 		const dropdownItems = new Collection();
 
 		for ( const option of options ) {
@@ -124,12 +132,14 @@ export default class TableUI extends Plugin {
 
 		addListToDropdown( dropdownView, dropdownItems );
 
+		// Decorate dropdown's button.
 		dropdownView.buttonView.set( {
 			label: buttonName,
 			icon,
 			tooltip: true
 		} );
 
+		// Make dropdown button disabled when all options are disabled.
 		dropdownView.bind( 'isEnabled' ).toMany( commands, 'isEnabled', ( ...areEnabled ) => {
 			return areEnabled.some( isEnabled => isEnabled );
 		} );
@@ -145,11 +155,10 @@ export default class TableUI extends Plugin {
 
 // Adds an option to a list view.
 //
-// @param {Object} commandName
-// @param {String} label
+// @param {module:table/tableui~DropdownOption} option Configuration option.
 // @param {module:core/editor/editor~Editor} editor
-// @param {Array.<module:core/command~Command>} commands
-// @param {module:utils/collection~Collection} dropdownItems
+// @param {Array.<module:core/command~Command>} commands List of commands to update.
+// @param {module:utils/collection~Collection} dropdownItems Collection of dropdown items to update with given option.
 function addListOption( option, editor, commands, dropdownItems ) {
 	const { commandName, label, bindIsActive } = option;
 	const command = editor.commands.get( commandName );
@@ -169,3 +178,13 @@ function addListOption( option, editor, commands, dropdownItems ) {
 
 	dropdownItems.add( itemModel );
 }
+
+/**
+ * Object describing table dropdowns' items.
+ *
+ * @typedef {Object} module:table/tableui~DropdownOption
+ * @private
+ * @property {String} commandName A command name to execute for that option.
+ * @property {String} label A dropdown item label.
+ * @property {Boolean} bindIsActive If `true` will bind command's value to `isActive` dropdown item property.
+ */