浏览代码

Renamed config.styles to config.options.

Piotrek Koszuliński 7 年之前
父节点
当前提交
0031237f3c

+ 1 - 1
packages/ckeditor5-alignment/docs/_snippets/features/custom-text-alignment-options.js

@@ -14,7 +14,7 @@ ClassicEditor
 			viewportTopOffset: 60
 		},
 		alignment: {
-			styles: [ 'left', 'right' ]
+			options: [ 'left', 'right' ]
 		}
 	} )
 	.then( editor => {

+ 4 - 4
packages/ckeditor5-alignment/docs/features/text-alignment.md

@@ -13,7 +13,7 @@ The {@link module:alignment/alignment~Alignment} feature enables support for tex
 
 ## Configuring alignment options
 
-It is, of course, possible to configure which alignment options the editor should support. Use the {@link module:alignment/alignmentediting~AlignmentEditingConfig#styles `alignment.styles`} configuration option to do so (you can choose from `'left'`, `'right'`, `'center'` and `'justify'`,  but `'left'` should be always included).
+It is, of course, possible to configure which alignment options the editor should support. Use the {@link module:alignment/alignment~AlignmentConfig#options `alignment.options`} configuration option to do so (you can choose from `'left'`, `'right'`, `'center'` and `'justify'`,  but `'left'` should be always included).
 
 For example, the following editor will support only two alignment to the left and to the right:
 
@@ -21,7 +21,7 @@ For example, the following editor will support only two alignment to the left an
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		alignment: {
-			styles: [ 'left', 'right' ]
+			options: [ 'left', 'right' ]
 		},
 		toolbar: [
 			'headings', 'bulletedList', 'numberedList', 'alignmentDropdown', 'undo', 'redo'
@@ -35,7 +35,7 @@ ClassicEditor
 
 ## Configuring the toolbar
 
-You can choose to use the alignment dropdown (`'alignmentDropdown'`) or configure the toolbar to use separate buttons for each of the styles:
+You can choose to use the alignment dropdown (`'alignmentDropdown'`) or configure the toolbar to use separate buttons for each of the options:
 
 ```js
 ClassicEditor
@@ -83,7 +83,7 @@ The {@link module:alignment/alignment~Alignment} plugin registers:
 * Dropdown: `'alignmentDropdown'`.
 * Buttons and commands: `'alignLeft'`, `'alignRight'`, `'alignCenter'`, `'alignJustify'`.
 
-	The number of options and their names are based on the {@link module:alignment/alignmentediting~AlignmentEditingConfig#styles `alignment.styles`} configuration option).
+	The number of options and their names are based on the {@link module:alignment/alignment~AlignmentConfig#options `alignment.options`} configuration option).
 
 	You can align the currently selected block(s) by executing one of these commands:
 

+ 47 - 0
packages/ckeditor5-alignment/src/alignment.js

@@ -37,3 +37,50 @@ export default class Alignment extends Plugin {
 		return 'Alignment';
 	}
 }
+
+/**
+ * The configuration of the {@link module:alignment/alignment~Alignment Alignment feature}.
+ *
+ * Read more in {@link module:alignment/alignment~AlignmentConfig}.
+ *
+ * @member {module:alignment/alignment~AlignmentConfig} module:core/editor/editorconfig~EditorConfig#alignment
+ */
+
+/**
+ * The configuration of the {@link module:alignment/alignment~Alignment Alignment feature}.
+ *
+ *		ClassicEditor
+ *			.create( editorElement, {
+ * 				alignment: {
+ *					options: [ 'left', 'right' ]
+ * 				}
+ *			} )
+ *			.then( ... )
+ *			.catch( ... );
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface AlignmentConfig
+ */
+
+/**
+ * Available alignment options.
+ *
+ * The available options are – `'left'`, `'right'`, `'center'` and `'justify'`. Other values are ignored.
+ *
+ * **Note:** It is recommended to always use `'left'` as it is the default value which the user should
+ * normally be able to choose.
+ *
+ *		ClassicEditor
+ *			.create( editorElement, {
+ * 				alignment: {
+ *					options: [ 'left', 'right' ]
+ * 				}
+ *			} )
+ *			.then( ... )
+ *			.catch( ... );
+ *
+ * See a demo of {@glink features/text-alignment#configuring-alignment-options custom alignment options}.
+ *
+ * @member {Array.<String>} module:alignment/alignment~AlignmentConfig#options
+ */

+ 20 - 20
packages/ckeditor5-alignment/src/alignmentcommand.js

@@ -22,22 +22,22 @@ export default class AlignmentCommand extends Command {
 	 * Creates an instance of the command.
 	 *
 	 * @param {module:core/editor/editor~Editor} editor The editor instance.
-	 * @param {'left'|'right'|'center'|'justify'} type Alignment type to be handled by this command.
-	 * @param {Boolean} isDefault Indicates if command is of default type.
+	 * @param {'left'|'right'|'center'|'justify'} alignment Alignment value to be handled by this command.
+	 * @param {Boolean} isDefault Indicates if the command is the default alignment.
 	 */
-	constructor( editor, type, isDefault ) {
+	constructor( editor, alignment, isDefault ) {
 		super( editor );
 
 		/**
-		 * The type of the list created by the command.
+		 * The alignment value handled by the command.
 		 *
 		 * @readonly
 		 * @member {'left'|'right'|'center'|'justify'}
 		 */
-		this.type = type;
+		this.alignment = alignment;
 
 		/**
-		 * Whether this command has default type.
+		 * Whether this command is the default alignment.
 		 *
 		 * @readonly
 		 * @private
@@ -47,7 +47,7 @@ export default class AlignmentCommand extends Command {
 
 		/**
 		 * A flag indicating whether the command is active, which means that the selection starts in a block
-		 * that has defined alignment of the same type.
+		 * which has the same alignment as {@link #alignment this command}.
 		 *
 		 * @observable
 		 * @readonly
@@ -74,18 +74,18 @@ export default class AlignmentCommand extends Command {
 	execute() {
 		const editor = this.editor;
 		const model = editor.model;
-		const document = model.document;
+		const doc = model.document;
 
 		model.change( writer => {
 			// Get only those blocks from selected that can have alignment set
-			const blocks = Array.from( document.selection.getSelectedBlocks() ).filter( block => this._canBeAligned( block ) );
+			const blocks = Array.from( doc.selection.getSelectedBlocks() ).filter( block => this._canBeAligned( block ) );
 
 			// Remove alignment attribute if current alignment is as selected or is default one.
 			// Default alignment should not be stored in model as it will bloat model data.
 			if ( this.value || this._isDefault ) {
 				removeAlignmentFromSelection( blocks, writer );
 			} else {
-				setAlignmentOnSelection( blocks, writer, this.type );
+				setAlignmentOnSelection( blocks, writer, this.alignment );
 			}
 		} );
 	}
@@ -93,9 +93,9 @@ export default class AlignmentCommand extends Command {
 	/**
 	 * Checks whether block can have aligned set.
 	 *
+	 * @private
 	 * @param {module:engine/model/element~Element} block A block to be checked.
 	 * @returns {Boolean}
-	 * @private
 	 */
 	_canBeAligned( block ) {
 		return this.editor.model.schema.checkAttribute( block, 'alignment' );
@@ -116,20 +116,20 @@ export default class AlignmentCommand extends Command {
 
 		const selectionAlignment = firstBlock.getAttribute( 'alignment' );
 
-		// Command's value will be set when commands type is matched in selection or the selection is default one.
-		return selectionAlignment ? selectionAlignment === this.type : this._isDefault;
+		// Command's value will be on when command's alignment matches the alignment of the current block,
+		// or when it's the default alignment and the block has no alignment set.
+		return selectionAlignment ? selectionAlignment === this.alignment : this._isDefault;
 	}
 }
 
 /**
- * Helper function that returns command name for given style. May produce unknown commands if passed style is not
- * in {@link module:alignment/alignmentediting~AlignmentEditing.supportedStyles}.
+ * Helper function that returns command name for alignment option.
  *
- * @param {String} style
+ * @param {String} option
  * @returns {String}
  */
-export function commandNameFromStyle( style ) {
-	return `align${ upperFirst( style ) }`;
+export function commandNameFromOptionName( option ) {
+	return `align${ upperFirst( option ) }`;
 }
 
 // Removes alignment attribute from blocks.
@@ -142,8 +142,8 @@ function removeAlignmentFromSelection( blocks, writer ) {
 
 // Sets alignment attribute on blocks.
 // @private
-function setAlignmentOnSelection( blocks, writer, type ) {
+function setAlignmentOnSelection( blocks, writer, alignment ) {
 	for ( const block of blocks ) {
-		writer.setAttribute( 'alignment', type, block );
+		writer.setAttribute( 'alignment', alignment, block );
 	}
 }

+ 19 - 48
packages/ckeditor5-alignment/src/alignmentediting.js

@@ -7,7 +7,7 @@
  * @module alignment/alignmentediting
  */
 
-import AlignmentCommand, { commandNameFromStyle } from './alignmentcommand';
+import AlignmentCommand, { commandNameFromOptionName } from './alignmentcommand';
 
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import buildViewConverter from '@ckeditor/ckeditor5-engine/src/conversion/buildviewconverter';
@@ -22,11 +22,13 @@ export default class AlignmentEditing extends Plugin {
 	constructor( editor ) {
 		super( editor );
 
-		editor.config.define( 'alignment', { styles: [ ...this.constructor.supportedStyles ] } );
+		editor.config.define( 'alignment', {
+			options: [ ...this.constructor.supportedOptions ]
+		} );
 	}
 
 	/**
-	 * List of supported alignment styles:
+	 * List of supported alignment options:
 	 *
 	 * * `'left'`,
 	 * * `'right'`,
@@ -35,9 +37,9 @@ export default class AlignmentEditing extends Plugin {
 	 *
 	 * @static
 	 * @readonly
-	 * @member {Array.<String>} module:alignment/alignmentediting~AlignmentEditing.supportedStyles
+	 * @member {Array.<String>} module:alignment/alignmentediting~AlignmentEditing.supportedOptions
 	 */
-	static get supportedStyles() {
+	static get supportedOptions() {
 		return [ 'left', 'right', 'center', 'justify' ];
 	}
 
@@ -50,7 +52,7 @@ export default class AlignmentEditing extends Plugin {
 		const data = editor.data;
 		const editing = editor.editing;
 
-		const enabledStyles = editor.config.get( 'alignment.styles' );
+		const enabledOptions = editor.config.get( 'alignment.options' );
 
 		// Allow alignment attribute on all blocks.
 		schema.extend( '$block', { allowAttributes: 'alignment' } );
@@ -66,7 +68,7 @@ export default class AlignmentEditing extends Plugin {
 				const textAlign = viewElement.getStyle( 'text-align' );
 
 				// Do not convert empty, default or unknown alignment values.
-				if ( !textAlign || isDefault( textAlign ) || !enabledStyles.includes( textAlign ) ) {
+				if ( !textAlign || isDefault( textAlign ) || !enabledOptions.includes( textAlign ) ) {
 					return;
 				}
 
@@ -74,22 +76,22 @@ export default class AlignmentEditing extends Plugin {
 			} );
 
 		// Add only enabled & supported commands.
-		enabledStyles
+		enabledOptions
 			.filter( isSupported )
-			.forEach( style => {
-				editor.commands.add( commandNameFromStyle( style ), new AlignmentCommand( editor, style, isDefault( style ) ) );
+			.forEach( option => {
+				editor.commands.add( commandNameFromOptionName( option ), new AlignmentCommand( editor, option, isDefault( option ) ) );
 			} );
 	}
 }
 
 /**
- * Checks whether passed style is supported by {@link module:alignment/alignmentediting~AlignmentEditing}.
+ * Checks whether passed option is supported by {@link module:alignment/alignmentediting~AlignmentEditing}.
  *
- * @param {String} style Style value to check.
+ * @param {String} option Option value to check.
  * @returns {Boolean}
  */
-export function isSupported( style ) {
-	return AlignmentEditing.supportedStyles.includes( style );
+export function isSupported( option ) {
+	return AlignmentEditing.supportedOptions.includes( option );
 }
 
 // Dispatcher handler responsible for setting style to a view element.
@@ -100,9 +102,9 @@ function convertStyle() {
 			return;
 		}
 
-		if ( data.attributeNewValue ) { // Set style.
+		if ( data.attributeNewValue ) {
 			conversionApi.mapper.toViewElement( data.item ).setStyle( { 'text-align': data.attributeNewValue } );
-		} else { // Remove style.
+		} else {
 			conversionApi.mapper.toViewElement( data.item ).removeStyle( 'text-align' );
 		}
 	};
@@ -111,37 +113,6 @@ function convertStyle() {
 // Check whether alignment is default one.
 // @private
 function isDefault( textAlign ) {
-	// Right now only RTL is supported so 'left' value is always default one.
+	// Right now only LTR is supported so 'left' value is always the default one.
 	return textAlign === 'left';
 }
-
-/**
- * The configuration of the {@link module:alignment/alignmentediting~AlignmentEditing Alignment feature}.
- *
- * Read more in {@link module:alignment/alignmentediting~AlignmentEditingConfig}.
- *
- * @member {module:alignment/alignmentediting~AlignmentEditingConfig} module:core/editor/editorconfig~EditorConfig#alignment
- */
-
-/**
- * The configuration of the {@link module:alignment/alignmentediting~AlignmentEditing Alignment feature}.
- *
- *		ClassicEditor
- *			.create( editorElement, {
- * 				alignment: {
- *					styles: [ 'left', 'right' ]
- * 				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
- *
- * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
- *
- * @interface AlignmentEditingConfig
- */
-
-/**
- * Enabled alignment styles from supported styles: `left`, `right`, `center` and `justify`. Other values are ignored.
- *
- * @member {String} module:alignment/alignmentediting~AlignmentEditingConfig#styles
- */

+ 17 - 16
packages/ckeditor5-alignment/src/alignmentui.js

@@ -13,7 +13,7 @@ import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
 import Model from '@ckeditor/ckeditor5-ui/src/model';
 import createButtonDropdown from '@ckeditor/ckeditor5-ui/src/dropdown/button/createbuttondropdown';
 
-import { commandNameFromStyle } from './alignmentcommand';
+import { commandNameFromOptionName } from './alignmentcommand';
 import { isSupported } from './alignmentediting';
 
 import alignLeftIcon from '../theme/icons/align-left.svg';
@@ -31,26 +31,27 @@ const icons = new Map( [
 /**
  * The default Alignment UI plugin.
  *
- * It introduces the `'alignLeft'`, `'alignRight'`, `'alignCenter'` and `'alignJustify'` buttons.
+ * It introduces the `'alignLeft'`, `'alignRight'`, `'alignCenter'` and `'alignJustify'` buttons
+ * and the `'alignmentDropdown'` dropdown.
  *
  * @extends module:core/plugin~Plugin
  */
 export default class AlignmentUI extends Plugin {
 	/**
-	 * Returns the localized style titles provided by the plugin.
+	 * Returns the localized option titles provided by the plugin.
 	 *
 	 * The following localized titles corresponding with
-	 * {@link module:alignment/alignmentediting~AlignmentEditingConfig#styles} are available:
+	 * {@link module:alignment/alignment~AlignmentConfig#options} are available:
 	 *
 	 * * `'left'`,
 	 * * `'right'`,
 	 * * `'center'`,
-	 * * `'justify'`
+	 * * `'justify'`.
 	 *
 	 * @readonly
 	 * @type {Object.<String,String>}
 	 */
-	get localizedStylesTitles() {
+	get localizedOptionTitles() {
 		const t = this.editor.t;
 
 		return {
@@ -75,15 +76,15 @@ export default class AlignmentUI extends Plugin {
 		const editor = this.editor;
 		const componentFactory = editor.ui.componentFactory;
 		const t = editor.t;
-		const styles = editor.config.get( 'alignment.styles' );
+		const options = editor.config.get( 'alignment.options' );
 
-		styles
+		options
 			.filter( isSupported )
-			.forEach( style => this._addButton( style ) );
+			.forEach( option => this._addButton( option ) );
 
 		componentFactory.add( 'alignmentDropdown', locale => {
-			const buttons = styles.map( style => {
-				return componentFactory.create( commandNameFromStyle( style ) );
+			const buttons = options.map( option => {
+				return componentFactory.create( commandNameFromOptionName( option ) );
 			} );
 
 			const model = new Model( {
@@ -104,20 +105,20 @@ export default class AlignmentUI extends Plugin {
 	 * Helper method for initializing a button and linking it with an appropriate command.
 	 *
 	 * @private
-	 * @param {String} style The name of style for which add button.
+	 * @param {String} option The name of the alignment option for which to add a button.
 	 */
-	_addButton( style ) {
+	_addButton( option ) {
 		const editor = this.editor;
 
-		const commandName = commandNameFromStyle( style );
+		const commandName = commandNameFromOptionName( option );
 		const command = editor.commands.get( commandName );
 
 		editor.ui.componentFactory.add( commandName, locale => {
 			const buttonView = new ButtonView( locale );
 
 			buttonView.set( {
-				label: this.localizedStylesTitles[ style ],
-				icon: icons.get( style ),
+				label: this.localizedOptionTitles[ option ],
+				icon: icons.get( option ),
 				tooltip: true
 			} );
 

+ 1 - 1
packages/ckeditor5-alignment/tests/alignmentcommand.js

@@ -57,7 +57,7 @@ describe( 'AlignmentCommand', () => {
 			expect( defaultAlignmentCommand ).to.have.property( 'value', true );
 		} );
 
-		it( 'is false when selection is inside block that has different alignment (default style)', () => {
+		it( 'is false when selection is inside block that has different alignment (default option)', () => {
 			setModelData( model, '<paragraph alignment="justify">x[]x</paragraph>' );
 
 			expect( defaultAlignmentCommand ).to.have.property( 'value', false );

+ 3 - 3
packages/ckeditor5-alignment/tests/alignmentediting.js

@@ -200,17 +200,17 @@ describe( 'AlignmentEditing', () => {
 	} );
 
 	describe( 'config', () => {
-		describe( 'styles', () => {
+		describe( 'options', () => {
 			describe( 'default value', () => {
 				it( 'should be set', () => {
-					expect( editor.config.get( 'alignment.styles' ) ).to.deep.equal( [ 'left', 'right', 'center', 'justify' ] );
+					expect( editor.config.get( 'alignment.options' ) ).to.deep.equal( [ 'left', 'right', 'center', 'justify' ] );
 				} );
 			} );
 
 			it( 'should customize commands', () => {
 				return VirtualTestEditor
 					.create( {
-						alignment: { styles: [ 'left', 'right' ] },
+						alignment: { options: [ 'left', 'right' ] },
 						plugins: [ AlignmentEditing, Paragraph ]
 					} )
 					.then( editor => {

+ 4 - 4
packages/ckeditor5-alignment/tests/alignmentui.js

@@ -34,13 +34,13 @@ describe( 'Alignment UI', () => {
 		return editor.destroy();
 	} );
 
-	describe( 'localizedStylesTitles()', () => {
-		it( 'should return localized titles of styles', () => {
+	describe( 'localizedOptionTitles()', () => {
+		it( 'should return localized titles of options', () => {
 			const editorMock = { t: str => str };
 
 			const plugin = new AlignmentUI( editorMock );
 
-			expect( plugin.localizedStylesTitles ).to.deep.equal( {
+			expect( plugin.localizedOptionTitles ).to.deep.equal( {
 				'left': 'Align left',
 				'right': 'Align right',
 				'center': 'Align center',
@@ -244,7 +244,7 @@ describe( 'Alignment UI', () => {
 				return ClassicTestEditor
 					.create( element, {
 						plugins: [ AlignmentEditing, AlignmentUI ],
-						alignment: { styles: [ 'center', 'justify' ] }
+						alignment: { options: [ 'center', 'justify' ] }
 					} )
 					.then( newEditor => {
 						editor = newEditor;

+ 1 - 1
packages/ckeditor5-alignment/tests/manual/alignmentconfig.js

@@ -16,7 +16,7 @@ ClassicEditor
 			'headings', 'bold', 'italic', 'link', 'alignmentDropdown', 'bulletedList', 'numberedList',
 			'blockQuote', 'undo', 'redo'
 		],
-		alignment: { styles: [ 'center', 'justify' ] }
+		alignment: { options: [ 'center', 'justify' ] }
 	} )
 	.then( editor => {
 		window.editor = editor;