Przeglądaj źródła

Docs and code refactoring.

Aleksander Nowodzinski 5 lat temu
rodzic
commit
27fee04c9a

+ 27 - 17
packages/ckeditor5-image/src/imageresize.js

@@ -58,18 +58,21 @@ export default class ImageResize extends Plugin {
  */
 
 /**
- * The resize options.
+ * The image resize options.
+ *
+ * Each option should have at least these two properties:
  *
- * Each option should have 2 properties:
  * * name: The name of the UI component registered in the global
  * {@link module:core/editor/editorui~EditorUI#componentFactory component factory} of the editor,
  * representing the button a user can click to change the size of an image,
  * * value: An actual image width applied when a user clicks the mentioned button
  * ({@link module:image/imageresize/imageresizecommand~ImageResizeCommand} gets executed).
- * The value property is combined with the {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`} (`%` by default),
- * e.g.: `value: '50'` and `resizeUnit: '%'` give `50%`.
+ * The value property is combined with the {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`} (`%` by default).
+ * For instance: `value: '50'` and `resizeUnit: '%'` will render as `'50%'` in the UI.
+ *
+ * **Resetting the image size**
  *
- * **Reset size option:** If you want to set an option that will reset image to its original size, you need to pass a `null` value
+ * If you want to set an option that will reset image to its original size, you need to pass a `null` value
  * to one of the options. The `:original` token is not mandatory, you can call it anything you wish, but it must reflect
  * in the standalone buttons configuration for the image toolbar.
  *
@@ -94,11 +97,13 @@ export default class ImageResize extends Plugin {
  *			.then( ... )
  *			.catch( ... );
  *
+ * **Resizing images using a dropdown**
+ *
  * With resize options defined, you can decide whether you want to display them as a dropdown or as standalone buttons.
- * For the dropdown, you need to pass only the `imageResize` token to the `image.toolbar`.
- * The dropdown contains all defined options by default:
+ * For the dropdown, you need to pass only the `imageResize` token to the
+{@link module:image/image~ImageConfig#toolbar `config.image.toolbar`}. The dropdown contains all defined options by default:
  *
- *			ClassicEditor
+ *		ClassicEditor
  *			.create( editorElement, {
  *				image: {
  *					resizeUnit: "%",
@@ -120,10 +125,13 @@ export default class ImageResize extends Plugin {
  *			.then( ... )
  *			.catch( ... );
  *
+ * **Resizing images using individual buttons**
+ *
  * If you want to have separate buttons for {@link module:image/imageresize/imageresizeui~ImageResizeOption each option},
- * pass their names to the `image.toolbar` instead. Please keep in mind that this time **you should define additional `icon` property**:
+ * pass their names to the {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`} instead. Please keep in mind
+ * that this time **you must define the additional `icon` property**:
  *
- *			ClassicEditor
+ *		ClassicEditor
  *			.create( editorElement, {
  *				image: {
  *					resizeUnit: "%",
@@ -153,9 +161,12 @@ export default class ImageResize extends Plugin {
  *			.then( ... )
  *			.catch( ... );
  *
- * **User-defined labels**: You can also set your own labels for each option. To do that, please add `label` property like
- * in the example below. With the **dropdown**, the labels will be shown on the list of all options when you open the dropdown.
- * With the **standalone buttons**, the labels will be shown only in tooltips when you hover over the icons.
+ * **Customizing resize button labels**
+ *
+ * You can set your own label for each resize button. To do that, add the `label` property like in the example below.
+ *
+ * * When using the **dropdown**, the labels are displayed on the list of all options when you open the dropdown.
+ * * When using **standalone buttons**, the labels will are displayed as tooltips when a user hovers over the button.
  *
  *		ClassicEditor
  *			.create( editorElement, {
@@ -165,25 +176,24 @@ export default class ImageResize extends Plugin {
  *						name: 'imageResize:original',
  *						value: null,
  *						label: 'Original size'
- *						// you should add `icon` property if you're configuring the standalone buttons.
+ *						// Note: add the "icon" property if you're configuring a standalone button.
  *					},
  *					{
  *						name: 'imageResize:50',
  *						value: '50',
  *						label: 'Medium size'
- *						// you should add `icon` property if you're configuring the standalone buttons.
+ *						// Note: add the "icon" property if you're configuring a standalone button.
  *					},
  *					{
  *						name: 'imageResize:75',
  *						value: '75',
  *						label: 'Large size'
- *						// you should add `icon` property if you're configuring the standalone buttons.
+ *						// Note: add the "icon" property if you're configuring a standalone button.
  *					} ]
  *				}
  *			} )
  *			.then( ... )
  *			.catch( ... );
  *
- *
  * @member {Array.<module:image/imageresize/imageresizeui~ImageResizeOption>} module:image/image~ImageConfig#resizeOptions
  */

+ 41 - 38
packages/ckeditor5-image/src/imageresize/imageresizeui.js

@@ -33,7 +33,7 @@ const RESIZE_ICONS = {
 /**
  * The `ImageResizeUI` plugin.
  *
- * It adds a possibility to resize each image using toolbar dropdown or separate buttons, depends on the plugin configuration.
+ * It adds a possibility to resize images using the toolbar dropdown or individual buttons, depending on the plugin configuration.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -99,48 +99,47 @@ export default class ImageResizeUI extends Plugin {
 	_registerImageResizeButton( option ) {
 		const editor = this.editor;
 		const { name, value, icon } = option;
-		const parsedValue = value ? value + this._resizeUnit : null;
+		const optionValueWithUnit = value ? value + this._resizeUnit : null;
 
 		editor.ui.componentFactory.add( name, locale => {
 			const button = new ButtonView( locale );
 			const command = editor.commands.get( 'imageResize' );
-			const commandCallback = setOptionOn( parsedValue );
-			const labelText = this._createLabel( option, true );
+			const labelText = this._getOptionLabelValue( option, true );
 
 			if ( !RESIZE_ICONS[ icon ] ) {
 				/**
-				 * Setting {@link module:image/image~ImageConfig#resizeOptions `config.image.resizeOptions`} for the standalone buttons,
-				 * you have to choose a valid icon token for each option.
+				 * When configuring {@link module:image/image~ImageConfig#resizeOptions `config.image.resizeOptions`} for standalone
+				 * buttons, a valid `icon` token must be set for each option.
 				 *
 				 * See all valid options described in the
 				 * {@link module:image/imageresize/imageresizeui~ImageResizeOption plugin configuration}.
+				 *
 				 * @error imageresizeui-missing-icon
 				 * @param {module:image/imageresize/imageresizeui~ImageResizeOption} option Invalid image resize option.
 				*/
 				throw new CKEditorError(
 					'imageresizeui-missing-icon: ' +
-					'The resize option "' + name + '" misses an `icon` property ' +
-					'or its value doesn\'t match the available options.',
+					'The resize option "' + name + '" misses the "icon" property ' +
+					'or the property value doesn\'t match any of available icons.',
 					editor,
 					option
 				);
 			}
 
 			button.set( {
-				// Use the `label` property for a verbose description for ARIA purposes.
+				// Use the `label` property for a verbose description (because of ARIA).
 				label: labelText,
 				icon: RESIZE_ICONS[ icon ],
 				tooltip: labelText,
-				isToggleable: true,
-				commandValue: parsedValue
+				isToggleable: true
 			} );
 
 			// Bind button to the command.
 			button.bind( 'isEnabled' ).to( this );
-			button.bind( 'isOn' ).to( command, 'value', commandCallback );
+			button.bind( 'isOn' ).to( command, 'value', getIsOnButtonCallback( optionValueWithUnit ) );
 
-			this.listenTo( button, 'execute', evt => {
-				editor.execute( 'imageResize', { width: evt.source.commandValue } );
+			this.listenTo( button, 'execute', () => {
+				editor.execute( 'imageResize', { width: optionValueWithUnit } );
 			} );
 
 			return button;
@@ -148,11 +147,11 @@ export default class ImageResizeUI extends Plugin {
 	}
 
 	/**
-	 * A helper function that creates a dropdown component for the plugin containing all resize options created through the
-	 * plugin configuration settings.
+	 * A helper function that creates a dropdown component for the plugin containing all resize options defined in
+	 * the editor configuration.
 	 *
 	 * @private
-	 * @param {Array.<module:image/imageresize/imageresizeui~ImageResizeOption>} options An array of the configured options.
+	 * @param {Array.<module:image/imageresize/imageresizeui~ImageResizeOption>} options An array of configured options.
 	 */
 	_registerImageResizeDropdown( options ) {
 		const editor = this.editor;
@@ -170,7 +169,7 @@ export default class ImageResizeUI extends Plugin {
 				commandValue: originalSizeOption.value,
 				icon: iconMedium,
 				isToggleable: true,
-				label: this._createLabel( originalSizeOption ),
+				label: this._getOptionLabelValue( originalSizeOption ),
 				withText: true,
 				class: 'ck-resize-image-button'
 			} );
@@ -179,7 +178,7 @@ export default class ImageResizeUI extends Plugin {
 				if ( commandValue && commandValue.width ) {
 					return commandValue.width;
 				} else {
-					return this._createLabel( originalSizeOption );
+					return this._getOptionLabelValue( originalSizeOption );
 				}
 			} );
 			dropdownView.bind( 'isOn' ).to( command );
@@ -200,7 +199,7 @@ export default class ImageResizeUI extends Plugin {
 	}
 
 	/**
-	 * A helper function for creating an option label.
+	 * A helper function for creating an option label value string.
 	 *
 	 * @private
 	 * @param {module:image/imageresize/imageresizeui~ImageResizeOption} option A resize option object.
@@ -208,7 +207,7 @@ export default class ImageResizeUI extends Plugin {
 	 * @returns {String} A user-defined label, a label combined from the value and resize unit or the default label
 	 * for reset options (`Original`).
 	 */
-	_createLabel( option, forTooltip ) {
+	_getOptionLabelValue( option, forTooltip ) {
 		const t = this.editor.t;
 
 		if ( option.label ) {
@@ -229,7 +228,7 @@ export default class ImageResizeUI extends Plugin {
 	}
 
 	/**
-	 * A helper function that parses resize options and returns definitions ready for use in a dropdown.
+	 * A helper function that parses resize options and returns list item definitions ready for use in a dropdown.
 	 *
 	 * @private
 	 * @param {Array.<module:image/imageresize/imageresizeui~ImageResizeOption>} options The resize options.
@@ -240,21 +239,19 @@ export default class ImageResizeUI extends Plugin {
 		const itemDefinitions = new Collection();
 
 		options.map( option => {
-			const parsedValue = option.value ? option.value + this._resizeUnit : null;
+			const optionValueWithUnit = option.value ? option.value + this._resizeUnit : null;
 			const definition = {
 				type: 'button',
 				model: new Model( {
 					commandName: 'imageResize',
-					commandValue: parsedValue,
-					label: this._createLabel( option ),
+					commandValue: optionValueWithUnit,
+					label: this._getOptionLabelValue( option ),
 					withText: true,
 					icon: null
 				} )
 			};
 
-			const commandCallback = setOptionOn( parsedValue );
-
-			definition.model.bind( 'isOn' ).to( command, 'value', commandCallback );
+			definition.model.bind( 'isOn' ).to( command, 'value', getIsOnButtonCallback( optionValueWithUnit ) );
 
 			itemDefinitions.add( definition );
 		} );
@@ -263,11 +260,10 @@ export default class ImageResizeUI extends Plugin {
 	}
 }
 
-// A helper function for setting the `isOn` state used for creating a callback function in a value binding.
-function setOptionOn( value ) {
+// A helper function for setting the `isOn` state of buttons in value bindings.
+function getIsOnButtonCallback( value ) {
 	return commandValue => {
-		// Set reseting option on when command equals `null`.
-		if ( commandValue === value ) {
+		if ( value === null && commandValue === value ) {
 			return true;
 		}
 
@@ -276,12 +272,19 @@ function setOptionOn( value ) {
 }
 
 /**
- * A resize option type.
+ * An image resize option used in the {@link module:image/image~ImageConfig#resizeOptions image resize configuration}.
  *
  * @typedef {Object} module:image/imageresize/imageresizeui~ImageResizeOption
- * @property {String} resizeOption.name A name of the option used for creating a component.
- * You refer to that name later in the {@link module:image/image~ImageConfig#toolbar}.
- * @property {String} resizeOption.value A value of a resize option. `null` value is for resetting an image to its original size.
- * @property {String} [resizeOptions.icon] A value of the available icon sizes (`small`, `medium`, `large`, `original`).
- * @property {String} [resizeOption.label] A label to be displayed with a button.
+ * @property {String} resizeOption.name A name of the UI component that changes the image size.
+ * * If you configure the feature using individual resize buttons, you can refer to this name in the
+ * {@link module:image/image~ImageConfig#toolbar image toolbar configuration}.
+ * * If you configure the feature using the resize dropdown, this name will be used for a list item in the dropdown.
+ * @property {String} resizeOption.value A value of a resize option without the unit
+ * ({@link module:image/image~ImageConfig#resizeUnit configured separately}). `null` resets an image to its original size.
+ * @property {String} [resizeOptions.icon] An icon used by an individual resize button (see the `name` property to learn more).
+ * Available icons are: `'small'`, `'medium'`, `'large'`, `'original'`.
+ * @property {String} [resizeOption.label] A label of the option displayed in the dropdown or, if the feature is configured using
+ * individual buttons, a {@link module:ui/button/buttonview~ButtonView#tooltip} and an ARIA attribute of a button.
+ * If not specified, the label is generated automatically based on the option `value` and the
+ * {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`}.
  */

+ 2 - 8
packages/ckeditor5-image/tests/imageresize/imageresizeui.js

@@ -271,12 +271,6 @@ describe( 'ImageResizeUI', () => {
 			expect( buttonView50.tooltip ).to.equal( 'Resize image to 50%' );
 		} );
 
-		it( 'should have `commandValue` equal "50%"', () => {
-			const buttonView = editor.ui.componentFactory.create( 'imageResize:50' );
-
-			expect( buttonView.commandValue ).to.equal( '50%' );
-		} );
-
 		it( 'should execute `imageResize` command with "50%" value', () => {
 			const buttonView = editor.ui.componentFactory.create( 'imageResize:50' );
 			const command = editor.commands.get( 'imageResize' );
@@ -316,8 +310,8 @@ describe( 'ImageResizeUI', () => {
 					}
 				} );
 
-			const errMsg = 'The resize option "imageResize:noicon" misses an `icon` property ' +
-				'or its value doesn\'t match the available options.';
+			const errMsg = 'The resize option "imageResize:noicon" misses the "icon" property ' +
+				'or the property value doesn\'t match any of available icons.';
 
 			expectToThrowCKEditorError( () => {
 				editor.ui.componentFactory.create( 'imageResize:noicon' );