Merge pull request #140 from ckeditor/t/134

Feature: Allowed customization of default image styles. Defined formatting–oriented styles. Simplified `config.image.styles` syntax. Closes #134. Closes #135.

BREAKING CHANGE: From now on, the `imageStyleFull` uses `object-full-width.svg` icon.

docs/_snippets/features/image-style-custom.js

@@ -7,42 +7,21 @@
 
 import './image-style-custom.scss';
 
-import fullSizeIcon from '@ckeditor/ckeditor5-core/theme/icons/object-center.svg';
-import alignLeftIcon from '@ckeditor/ckeditor5-core/theme/icons/object-left.svg';
-import alignRightIcon from '@ckeditor/ckeditor5-core/theme/icons/object-right.svg';
-
 ClassicEditor
 	.create( document.querySelector( '#snippet-image-style-custom' ), {
 		image: {
 			styles: [
 				// This option is equal to a situation where no style is applied.
-				{
-					name: 'imageStyleFull',
-					title: 'Full size image',
-					icon: fullSizeIcon,
-					value: null
-				},
+				'imageStyleFull',
 
 				// This represents an image aligned to left.
-				{
-					name: 'imageStyleLeft',
-					title: 'Left aligned image',
-					icon: alignLeftIcon,
-					value: 'left',
-					className: 'image-style-left'
-				},
+				'imageStyleAlignLeft',
 
 				// This represents an image aligned to right.
-				{
-					name: 'imageStyleRight',
-					title: 'Right aligned image',
-					icon: alignRightIcon,
-					value: 'right',
-					className: 'image-style-right'
-				}
+				'imageStyleAlignRight'
 			],
 
-			toolbar: [ 'imageTextAlternative', '|', 'imageStyleLeft', 'imageStyleFull', 'imageStyleRight' ]
+			toolbar: [ 'imageTextAlternative', '|', 'imageStyleAlignLeft', 'imageStyleFull', 'imageStyleAlignRight' ]
 		}
 	} )
 	.then( editor => {

docs/_snippets/features/image-style-custom.scss

@@ -1,13 +1,13 @@
 // Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
 // For licensing, see LICENSE.md or http://ckeditor.com/license
 
-.image-style-left {
+.image-style-align-left {
     float: left;
     width: 50%;
     margin: 1em 1em 1em 0;
 }
 
-.image-style-right {
+.image-style-align-right {
     float: right;
     width: 50%;
     margin: 1em 0 1em 1em;

docs/features/image.md

@@ -111,45 +111,24 @@ Below you can see a demo of the editor with the image styles feature enabled. Th
 
 The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `image.styles`} option.
 
-The following editor supports the default style plus left- and right-aligned images:
+The following editor supports the default full style plus left- and right-aligned images:
 
 ```js
-import fullSizeIcon from '@ckeditor/ckeditor5-core/theme/icons/object-center.svg';
-import alignLeftIcon from '@ckeditor/ckeditor5-core/theme/icons/object-left.svg';
-import alignRightIcon from '@ckeditor/ckeditor5-core/theme/icons/object-right.svg';
-
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		image: {
 			// You need to configure the image toolbar too, so it uses the new style buttons.
-			toolbar: [ 'imageTextAlternative', '|', 'imageStyleLeft', 'imageStyleFull', 'imageStyleRight' ],
+			toolbar: [ 'imageTextAlternative', '|', 'imageStyleAlignLeft', 'imageStyleFull', 'imageStyleAlignRight' ],
 
 			styles: [
 				// This option is equal to a situation where no style is applied.
-				{
-					name: 'imageStyleFull',
-					title: 'Full size image',
-					icon: fullSizeIcon,
-					value: null
-				},
+				'imageStyleFull',
 
 				// This represents an image aligned to left.
-				{
-					name: 'imageStyleLeft',
-					title: 'Left aligned image',
-					icon: alignLeftIcon,
-					value: 'left',
-					className: 'image-style-left'
-				},
+				'imageStyleAlignLeft',
 
 				// This represents an image aligned to right.
-				{
-					name: 'imageStyleRight',
-					title: 'Right aligned image',
-					icon: alignRightIcon,
-					value: 'right',
-					className: 'image-style-right'
-				}
+				'imageStyleAlignRight'
 			]
 		}
 	} )
@@ -158,13 +137,13 @@ ClassicEditor
 ```
 
 ```css
-.image-style-left {
+.image-style-align-left {
     float: left;
     width: 50%;
     margin: 1em 1em 1em 0;
 }
 
-.image-style-right {
+.image-style-align-right {
     float: right;
     width: 50%;
     margin: 1em 0 1em 1em;

src/imagestyle.js

@@ -37,7 +37,8 @@ export default class ImageStyle extends Plugin {
 	 * @inheritDoc
 	 */
 	init() {
-		const styles = this.editor.config.get( 'image.styles' );
+		const editor = this.editor;
+		const styles = editor.plugins.get( ImageStyleEngine ).imageStyles;
 
 		for ( const style of styles ) {
 			this._createButton( style );
@@ -79,22 +80,56 @@ export default class ImageStyle extends Plugin {
  *
  * The default value is:
  *
+ * 		const imageConfig = {
+ *			styles: [ 'imageStyleFull', 'imageStyleSide' ]
+ *		};
+ *
+ * which configures two default styles:
+ *
+ *  * the "full" style which doesn't apply any class, e.g. for images styled to span 100% width of the content,
+ *  * the "side" style with the `.image-style-side` CSS class.
+ *
+ * See {@link module:image/imagestyle/imagestyleengine~ImageStyleEngine.defaultStyles} to learn more about default
+ * styles provided by the image feature.
+ *
+ * The {@link module:image/imagestyle/imagestyleengine~ImageStyleEngine.defaultStyles default styles} can be customized,
+ * e.g. to change the icon, title or CSS class of the style. The feature also provides several
+ * {@link module:image/imagestyle/imagestyleengine~ImageStyleEngine.defaultIcons default icons} to chose from.
+ *
+ *		import customIcon from 'custom-icon.svg';
+ *
+ *		// ...
+ *
+ *		const imageConfig = {
+ *			styles: [
+ *				// This will only customize the icon of the "full" style.
+ *				// Note: 'right' is one of default icons provided by the feature.
+ *				{ name: 'imageStyleFull', icon: 'right' },
+ *
+ *				// This will customize the icon, title and CSS class of the default "side" style.
+ *				{ name: 'imageStyleSide', icon: customIcon, title: 'My side style', class: 'custom-side-image' }
+ *			]
+ *		};
+ *
+ * If none of the default styles is good enough, it is possible to define independent custom styles too:
+ *
  *		import fullSizeIcon from '@ckeditor/ckeditor5-core/theme/icons/object-center.svg';
  *		import sideIcon from '@ckeditor/ckeditor5-core/theme/icons/object-right.svg';
  *
  *		// ...
  *
  *		const imageConfig = {
  *			styles: [
- *				// Option which defines a style which doesn't apply any class.
- *				// The style is titled "full" because such images are often styled to take 100% width of the content.
- *				{ name: 'imageStyleFull', title: t( 'Full size image' ), icon: fullSizeIcon, value: null },
+ *				// A completely custom full size style with no class, used as a default.
+ *				{ name: 'fullSize', title: 'Full size', icon: fullSizeIcon, isDefault: true },
  *
- *				// Option which represents a side image.
- *				{ name: 'imageStyleSide', title: t( 'Side image' ), icon: sideIcon, value: 'side', className: 'image-style-side' }
+ *				{ name: 'side', title: 'To the side', icon: sideIcon, className: 'side-image' }
  *			]
  *		};
  *
+ * Note: Setting `title` to one of {@link module:image/imagestyle/imagestyleengine~ImageStyleEngine#localizedDefaultStylesTitles}
+ * will automatically translate it to the language of the editor.
+ *
  * Read more about styling images in the {@linkTODO Image styles guide}.
  *
  * The feature creates commands based on defined styles, so you can change the style of a selected image by executing

src/imagestyle/converters.js

@@ -26,8 +26,8 @@ export function modelToViewStyleAttribute( styles ) {
 		}
 
 		// Check if there is class name associated with given value.
-		const newStyle = getStyleByValue( data.attributeNewValue, styles );
-		const oldStyle = getStyleByValue( data.attributeOldValue, styles );
+		const newStyle = getStyleByName( data.attributeNewValue, styles );
+		const oldStyle = getStyleByName( data.attributeOldValue, styles );
 		const viewElement = conversionApi.mapper.toViewElement( data.item );
 
 		const isRemovalHandled = handleRemoval( eventType, oldStyle, viewElement );
@@ -47,8 +47,8 @@ export function modelToViewStyleAttribute( styles ) {
  * @returns {Function} A view-to-model converter.
  */
 export function viewToModelStyleAttribute( styles ) {
-	// Convert only styles without `null` value.
-	const filteredStyles = styles.filter( style => style.value !== null );
+	// Convert only non–default styles.
+	const filteredStyles = styles.filter( style => !style.isDefault );
 
 	return ( evt, data, consumable, conversionApi ) => {
 		for ( const style of filteredStyles ) {
@@ -88,17 +88,17 @@ function viewToModelImageStyle( style, data, consumable, conversionApi ) {
 
 	// *** Step2: Convert to model.
 	consumable.consume( viewFigureElement, { class: style.className } );
-	modelImageElement.setAttribute( 'imageStyle', style.value );
+	modelImageElement.setAttribute( 'imageStyle', style.name );
 }
 
-// Returns style with given `value` from array of styles.
+// Returns style with given `name` from array of styles.
 //
-// @param {String} value
+// @param {String} name
 // @param {Array.<module:image/imagestyle/imagestyleengine~ImageStyleFormat> } styles
 // @return {module:image/imagestyle/imagestyleengine~ImageStyleFormat|undefined}
-function getStyleByValue( value, styles ) {
+function getStyleByName( name, styles ) {
 	for ( const style of styles ) {
-		if ( style.value === value ) {
+		if ( style.name === name ) {
 			return style;
 		}
 	}

src/imagestyle/imagestylecommand.js

@@ -53,10 +53,10 @@ export default class ImageStyleCommand extends Command {
 
 		if ( !element ) {
 			this.value = false;
-		} else if ( this.style.value === null ) {
+		} else if ( this.style.isDefault ) {
 			this.value = !element.hasAttribute( 'imageStyle' );
 		} else {
-			this.value = ( element.getAttribute( 'imageStyle' ) == this.style.value );
+			this.value = ( element.getAttribute( 'imageStyle' ) == this.style.name );
 		}
 	}
 
@@ -79,7 +79,7 @@ export default class ImageStyleCommand extends Command {
 		doc.enqueueChanges( () => {
 			const batch = options.batch || doc.batch();
 
-			batch.setAttribute( imageElement, 'imageStyle', this.style.value );
+			batch.setAttribute( imageElement, 'imageStyle', this.style.name );
 		} );
 	}
 }