瀏覽代碼

Other: Refactor Highlight UI methods and add more documentation.

Maciej Gołaszewski 8 年之前
父節點
當前提交
dc28123254

+ 11 - 9
packages/ckeditor5-highlight/src/highlightcommand.js

@@ -19,7 +19,18 @@ export default class HighlightCommand extends Command {
 	constructor( editor, className ) {
 		super( editor );
 
+		/**
+		 * Name of marker class that is used by associated highlighter.
+		 */
 		this.className = className;
+
+		/**
+		 * A flag indicating whether the command is active, which means that the selection has highlight attribute set.
+		 *
+		 * @observable
+		 * @readonly
+		 * @member {undefined|String} module:highlight/highlightcommand~HighlightCommand#value
+		 */
 	}
 
 	/**
@@ -37,7 +48,6 @@ export default class HighlightCommand extends Command {
 	 *
 	 * @protected
 	 * @param {Object} [options] Options for the executed command.
-	 * @param {String} options.class Name of highlighter class.
 	 * @param {module:engine/model/batch~Batch} [options.batch] A batch to collect all the change steps.
 	 * A new batch will be created if this option is not set.
 	 */
@@ -60,11 +70,3 @@ export default class HighlightCommand extends Command {
 		} );
 	}
 }
-
-/**
- * Holds current highlight class. If there is no highlight in selection then value will be undefined.
- *
- * @observable
- * @readonly
- * @member {undefined|String} module:highlight/highlightcommand~HighlightCommand#value
- */

+ 2 - 2
packages/ckeditor5-highlight/src/highlightediting.js

@@ -82,7 +82,7 @@ export default class HighlightEditing extends Plugin {
 /**
  * Highlight option descriptor.
  *
- * @typedef {Object} module:highlight/highlightediting~HeadingOption
+ * @typedef {Object} module:highlight/highlightediting~HighlightOption
  * @property {String} class The class which is used to differentiate highlighters.
  * @property {String} title The user-readable title of the option.
  * @property {String} color Color used for highlighter. Should be coherent with CSS class definition.
@@ -124,5 +124,5 @@ export default class HighlightEditing extends Plugin {
  * Note: Each highlighter must have it's own CSS class defined to properly match content data. Also it is advised
  * that color value should match the values defined in content CSS stylesheet.
  *
- * @member {Array.<module:heading/heading~HeadingOption>} module:heading/heading~HeadingConfig#options
+ * @member {Array.<module:heading/heading~HighlightOption>} module:heading/heading~HeadingConfig#options
  */

+ 83 - 46
packages/ckeditor5-highlight/src/highlightui.js

@@ -55,12 +55,23 @@ export default class HighlightUI extends Plugin {
 		this._addDropdown( highlighters );
 	}
 
+	/**
+	 * Creates remove highlight button.
+	 *
+	 * @private
+	 */
 	_addRemoveHighlightButton() {
 		const t = this.editor.t;
 
 		this._addButton( 'removeHighlight', t( 'Remove highlighting' ), highlightRemoveIcon );
 	}
 
+	/**
+	 * Creates toolbar button from provided highlight option.
+	 *
+	 * @param {module:highlight/highlightediting~HighlightOption} highlighter
+	 * @private
+	 */
 	_addHighlighterButton( highlighter ) {
 		const name = highlighter.name;
 		const command = this.editor.commands.get( name );
@@ -78,6 +89,15 @@ export default class HighlightUI extends Plugin {
 		}
 	}
 
+	/**
+	 * Internal method for creating highlight buttons.
+	 *
+	 * @param {String} name Name of a button.
+	 * @param {String} label Label for button.
+	 * @param {String} icon Button's icon.
+	 * @param {Function} [decorateButton=()=>{}] Additional method for extending button.
+	 * @private
+	 */
 	_addButton( name, label, icon, decorateButton = () => {} ) {
 		const editor = this.editor;
 
@@ -95,85 +115,76 @@ export default class HighlightUI extends Plugin {
 				editor.editing.view.focus();
 			} );
 
+			// Add additional behavior for buttonView.
 			decorateButton( buttonView );
 
 			return buttonView;
 		} );
 	}
 
+	/**
+	 * Creates split button drop down UI from provided highlight options.
+	 *
+	 * @param {Array.<module:highlight/highlightediting~HighlightOption>} highlighters
+	 * @private
+	 */
 	_addDropdown( highlighters ) {
 		const editor = this.editor;
 		const t = editor.t;
 		const componentFactory = editor.ui.componentFactory;
 
-		const firstHighlighter = highlighters[ 0 ];
+		const startingHighlighter = highlighters[ 0 ];
 
 		componentFactory.add( 'highlightDropdown', locale => {
+			const commandName = startingHighlighter.name;
+
 			const model = new Model( {
 				label: t( 'Highlight' ),
 				withText: false,
-				selected: firstHighlighter.name,
 				icon: highlightIcon,
-				type: firstHighlighter.type,
-				color: firstHighlighter.color,
-				command: firstHighlighter.name
+				type: startingHighlighter.type,
+				color: startingHighlighter.color,
+				command: commandName
 			} );
 
-			model.bind( 'isOn' ).to( editor.commands.get( firstHighlighter.name ), 'value' );
+			bindModelToCommand( model, editor, commandName );
 
-			// TODO: bind this in model
 			const dropdownView = createSplitButtonDropdown( model, locale );
 
-			// Extend split button icon style to reflect last used button style
-			const iconView = dropdownView.buttonView.buttonView.iconView;
-			const bind = iconView.bindTemplate;
+			bindIconStyle( dropdownView, model );
 
-			iconView.extendTemplate( {
-				attributes: {
-					style: bind.to( 'style' )
-				}
-			} );
-
-			iconView.bind( 'style' ).to( model, 'type', model, 'color', getIconStyleForHighlighter );
-
-			// TODO: forward event ?:
-			// TODO: lame names buttonView/buttonView
 			dropdownView.buttonView.on( 'execute', () => {
 				editor.execute( model.command );
 				editor.editing.view.focus();
 			} );
 
+			// Add highlighters buttons to dropdown
 			const buttons = highlighters.map( highlighter => {
 				const buttonView = componentFactory.create( highlighter.name );
+				const commandName = highlighter.name;
 
-				this.listenTo( buttonView, 'execute', () => {
-					model.set( {
-						type: highlighter.type,
-						color: highlighter.color,
-						command: highlighter.name,
-						icon: highlightIcon
-					} );
-
-					model.unbind( 'isOn' );
-					model.bind( 'isOn' ).to( editor.commands.get( highlighter.name ), 'value' );
-				} );
+				this.listenTo( buttonView, 'execute', () => changeToolbarButton( editor, model, {
+					type: highlighter.type,
+					color: highlighter.color,
+					command: commandName,
+					icon: highlightIcon
+				} ) );
 
 				return buttonView;
 			} );
 
-			const removeButton = componentFactory.create( 'removeHighlight' );
-			buttons.push( removeButton );
+			// Add rubber button to dropdown.
+			const rubberButton = componentFactory.create( 'removeHighlight' );
+			buttons.push( rubberButton );
 
-			this.listenTo( removeButton, 'execute', () => {
-				model.type = 'remove';
-				model.color = undefined;
-				model.command = 'removeHighlight';
-				model.icon = highlightRemoveIcon;
-
-				model.unbind( 'isOn' );
-				model.bind( 'isOn' ).to( editor.commands.get( 'removeHighlight' ), 'value' );
-			} );
+			this.listenTo( rubberButton, 'execute', () => changeToolbarButton( editor, model, {
+				type: 'remove',
+				color: undefined,
+				command: 'removeHighlight',
+				icon: highlightRemoveIcon
+			} ) );
 
+			// Make toolbar button enabled when any button in dropdown is enabled.
 			model.bind( 'isEnabled' ).to(
 				// Bind to #isEnabled of each command...
 				...getBindingTargets( buttons, 'isEnabled' ),
@@ -181,7 +192,7 @@ export default class HighlightUI extends Plugin {
 				( ...areEnabled ) => areEnabled.some( isEnabled => isEnabled )
 			);
 
-			// TODO: This duplicates buttonDropdown
+			// TODO: Temporary group as UI not fully defined yet. Also duplicates button dropdown
 			// Group buttons for dropdown.
 			const buttonGroupView = dropdownView.buttonGroupView = new ButtonGroupView( { isVertical: false } );
 			buttons.map( buttonView => buttonGroupView.items.add( buttonView ) );
@@ -198,13 +209,11 @@ export default class HighlightUI extends Plugin {
 					buttonGroupView.focus();
 				}
 			}, { priority: 'low' } );
-
-			return dropdownView;
 		} );
 	}
 }
 
-// TODO: this is duplicated
+// TODO: this is duplicated in various places (dropdowns)
 function getBindingTargets( buttons, attribute ) {
 	return Array.prototype.concat( ...buttons.map( button => [ button, attribute ] ) );
 }
@@ -220,3 +229,31 @@ function getIconStyleForHighlighter( type, color ) {
 		return 'background-color:' + color;
 	}
 }
+
+// Rebinds model values to a new command.
+function bindModelToCommand( model, editor, commandName ) {
+	model.unbind( 'isOn' );
+	model.bind( 'isOn' ).to( editor.commands.get( commandName ), 'value' );
+}
+
+// Updates toolbar dropdown button with last selected highlighter.
+function changeToolbarButton( editor, model, iconData ) {
+	model.set( iconData );
+
+	bindModelToCommand( model, editor, iconData.command );
+}
+
+// Extends split button icon style to reflect last used button style.
+function bindIconStyle( dropdownView, model ) {
+	const iconView = dropdownView.buttonView.buttonView.iconView;
+
+	const bind = iconView.bindTemplate;
+
+	iconView.extendTemplate( {
+		attributes: {
+			style: bind.to( 'style' )
+		}
+	} );
+
+	iconView.bind( 'style' ).to( model, 'type', model, 'color', getIconStyleForHighlighter );
+}

+ 2 - 10
packages/ckeditor5-highlight/src/removehighlightcommand.js

@@ -10,8 +10,8 @@
 import Command from '@ckeditor/ckeditor5-core/src/command';
 
 /**
- * The highlight command. It is used by the {@link module:highlight/highlightediting~HighlightEditing highlight feature}
- * to apply text highlighting.
+ * The remove highlight command. It is used by the {@link module:highlight/highlightediting~HighlightEditing highlight feature}
+ * to remove text highlighting.
  *
  * @extends module:core/command~Command
  */
@@ -54,11 +54,3 @@ export default class RemoveHighlightCommand extends Command {
 		} );
 	}
 }
-
-/**
- * Holds current highlight class. If there is no highlight in selection then value will be undefined.
- *
- * @observable
- * @readonly
- * @member {undefined|String} module:highlight/highlightcommand~HighlightCommand#value
- */