浏览代码

Docs: Extended the feature guide. Fixed wording, typos and links in the package. Improved code style.

Aleksander Nowodzinski 6 年之前
父节点
当前提交
a6f2079939

+ 2 - 1
packages/ckeditor5-remove-format/docs/_snippets/features/build-remove-format-source.js

@@ -18,6 +18,7 @@ import Subscript from '@ckeditor/ckeditor5-basic-styles/src/subscript';
 import Superscript from '@ckeditor/ckeditor5-basic-styles/src/superscript';
 import Code from '@ckeditor/ckeditor5-basic-styles/src/code';
 
-ClassicEditor.builtinPlugins.push( RemoveFormat, Alignment, Font, Bold, Italic, Underline, Strikethrough, Subscript, Superscript, Code );
+ClassicEditor.builtinPlugins.push(
+	RemoveFormat, Alignment, Font, Bold, Italic, Underline, Strikethrough, Subscript, Superscript, Code );
 
 window.ClassicEditor = ClassicEditor;

+ 4 - 4
packages/ckeditor5-remove-format/docs/_snippets/features/remove-format.html

@@ -1,9 +1,9 @@
 <div id="editor">
 	<p>
-		You can use <strong>remove format feature</strong> to easily remove unnecessary content formatting.
+		You can use the <strong>remove format</strong> feature to easily clean up text formatting.
 	</p>
 	<p>
-		Formatting that will be removed by this feature include:
+		Some examples of the formatting removed by this feature:
 		<strong>bold</strong>,
 		<i>italics</i>,
 		<u>underline</u>,
@@ -15,9 +15,9 @@
 		<span style="font-family: 'Courier New', Courier, monospace;">font family</span>.
 	</p>
 	<p style="text-align: center">
-		Remove format will also strip alignment.
+		Remove format resets the text alignment too.
 	</p>
 	<p>
-		At the same time the feature will not erase non-formatting content, so <a href="https://ckeditor.com">your links</a> are safe!
+		<b>Note</b>: The feature will not erase non-formatting content — <a href="https://ckeditor.com">your links</a> are safe!
 	</p>
 </div>

+ 2 - 2
packages/ckeditor5-remove-format/docs/_snippets/features/remove-format.js

@@ -9,6 +9,8 @@ ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		toolbar: {
 			items: [
+				'removeformat',
+				'|',
 				'bold',
 				'italic',
 				'underline',
@@ -21,8 +23,6 @@ ClassicEditor
 				'alignment',
 				'link',
 				'|',
-				'removeformat',
-				'|',
 				'undo',
 				'redo'
 			],

+ 2 - 2
packages/ckeditor5-remove-format/docs/api/remove-format.md

@@ -10,11 +10,11 @@ This package implements the remove format feature for CKEditor 5.
 
 ## Demo
 
-Check out the {@link features/remove-format#demo demo in the remove-format feature} guide.
+Check out the {@link features/remove-format#demo demo in the remove format feature} guide.
 
 ## Documentation
 
-See the {@link features/remove-format remove-format feature} guide and the {@link module:remove-format/removeformat~RemoveFormat} plugin documentation.
+See the {@link features/remove-format remove format feature} guide and the {@link module:remove-format/removeformat~RemoveFormat} plugin documentation.
 
 ## Installation
 

+ 56 - 6
packages/ckeditor5-remove-format/docs/features/remove-format.md

@@ -1,18 +1,68 @@
 ---
-title: Remove Format
+title: Removing Text Formatting
+menu-title: Remove Format
 category: features
 ---
 
-The {@link module:remove-format/removeformat~RemoveFormat} feature allow to easily remove any formatting.
-
-Since it only clears formatting markup, this means that items like links, tables or images will not be removed.
-
 {@snippet features/build-remove-format-source}
 
+The {@link module:remove-format/removeformat~RemoveFormat Remove Format} feature allows to quickly remove any text formatting applied using inline HTML elements and CSS styles, like {@link features/basic-styles basic text styles} (bold, italic, etc.), {@link features/font font family, size, and color} and similar. Note that block—level formatting ({@link features/headings headings}, {@link features/image images}) and semantic data ({@link features/link links}) will not be removed.
+
 ## Demo
 
+Select the content you want to clean up and press the "Remove Format" button in the toolbar:
+
 {@snippet features/remove-format}
 
 ## Configuring the remove format feature
 
-Elements considered by remove format feature are determined by schema. Only elements marked with `isFormatting` property are removed by the remove format feature.
+The feature has no integration–level configuration. Once enabled, it works out–of–the–box with all {@link features/index core editor features}.
+
+## Integrating with editor features
+
+To make it possible for the remove formatting feature to work with your custom content, you must first mark it in the {@link framework/guides/architecture/editing-engine#schema schema}. All you need to do is set the `isFormatting` property on your custom {@link framework/guides/architecture/editing-engine#text-attributes text attribute}. {@link module:engine/model/schema~Schema#setAttributeProperties Learn more about attribute properties.}
+
+## Installation
+
+To add this feature to your editor install the [`@ckeditor/ckeditor5-remove-format`](https://www.npmjs.com/package/@ckeditor/ckeditor5-remove-format) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-remove-format
+```
+
+And add it to your plugin list and the toolbar configuration:
+
+```js
+import RemoveFormat from '@ckeditor/ckeditor5-remove-format/src/removeformat';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ RemoveFormat, ... ],
+		toolbar: [ 'removeFormat', ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Common API
+
+The {@link module:remove-format/removeformat~RemoveFormat} plugin registers the `'removeFormat'` UI button component the command of the same name implemented by {@link module:remove-format/removeformatcommand~RemoveFormatCommand}.
+
+The command can be executed using the {@link module:core/editor/editor~Editor#execute `editor.execute()`} method:
+
+```js
+// Removes all the formatting in the selection.
+editor.execute( 'removeFormat' );
+```
+
+<info-box>
+	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-remove-format.

+ 4 - 3
packages/ckeditor5-remove-format/src/removeformat.js

@@ -15,9 +15,10 @@ import RemoveFormatCommand from './removeformatcommand';
 /**
  * The remove format plugin.
  *
- * For a detailed overview, check the {@glink features/remove-format Remove Format feature} documentation.
+ * This is a "glue" plugin which loads the {@link module:remove-format/removeformatcommand~RemoveFormatCommand command}
+ * and the {@link module:remove-format/removeformatui~RemoveFormatUI UI}.
  *
- * This is a "glue" plugin which loads logic and UI of the remove format plugin.
+ * For a detailed overview, check out the {@glink features/remove-format Remove Format feature} documentation.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -32,7 +33,7 @@ export default class RemoveFormat extends Plugin {
 	init() {
 		const editor = this.editor;
 
-		editor.commands.add( 'removeformat', new RemoveFormatCommand( editor ) );
+		editor.commands.add( 'removeFormat', new RemoveFormatCommand( editor ) );
 	}
 
 	/**

+ 11 - 8
packages/ckeditor5-remove-format/src/removeformatcommand.js

@@ -4,13 +4,13 @@
  */
 
 /**
- * @module remove-format/removeformat
+ * @module remove-format/removeformatcommand
  */
 
 import Command from '@ckeditor/ckeditor5-core/src/command';
 import DocumentSelection from '@ckeditor/ckeditor5-engine/src/model/documentselection';
 
-const removedAttributes = [
+const removableAttributes = [
 	'bold',
 	'italic',
 	'underline',
@@ -25,10 +25,12 @@ const removedAttributes = [
 ];
 
 /**
- * The removeformat command. It is used by the {@link module:remove-format/removeformat~RemoveFormat remove format feature}
- * to clear the formatting form current user selection.
+ * The remove format command.
  *
- *		editor.execute( 'removeformat' );
+ * It is used by the {@link module:remove-format/removeformat~RemoveFormat remove format feature}
+ * to clear the formatting within the selection.
+ *
+ *		editor.execute( 'removeFormat' );
  *
  * @extends module:core/command~Command
  */
@@ -50,7 +52,7 @@ export default class RemoveFormatCommand extends Command {
 
 		model.change( writer => {
 			for ( const item of this._getStylableElements( model.document.selection ) ) {
-				for ( const attributeName of removedAttributes ) {
+				for ( const attributeName of removableAttributes ) {
 					if ( item instanceof DocumentSelection ) {
 						writer.removeSelectionAttribute( attributeName );
 					} else {
@@ -62,7 +64,8 @@ export default class RemoveFormatCommand extends Command {
 	}
 
 	/**
-	 * Yields items from a selection (including selection itself) that contains styles to be removed by the remove format feature.
+	 * Yields items from a selection (including selection itself) that contain styles to be removed
+	 * by the remove format feature.
 	 *
 	 * @protected
 	 * @param {module:engine/model/documentselection~DocumentSelection} selection
@@ -83,7 +86,7 @@ export default class RemoveFormatCommand extends Command {
 		}
 
 		function itemHasRemovableFormatting( item ) {
-			for ( const attributeName of removedAttributes ) {
+			for ( const attributeName of removableAttributes ) {
 				if ( item.hasAttribute( attributeName ) ) {
 					return true;
 				}

+ 4 - 3
packages/ckeditor5-remove-format/src/removeformatui.js

@@ -11,10 +11,11 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
 import removeFormatIcon from '../theme/icons/remove-format.svg';
 
-const REMOVE_FORMAT = 'removeformat';
+const REMOVE_FORMAT = 'removeFormat';
 
 /**
- * The default remove format UI plugin.
+ * The remove format UI plugin. It registers a `'removeFormat'` button which can be
+ * used in the toolbar.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -45,7 +46,7 @@ export default class RemoveFormatUI extends Plugin {
 
 			view.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );
 
-			// Execute command.
+			// Execute the command.
 			this.listenTo( view, 'execute', () => editor.execute( REMOVE_FORMAT ) );
 
 			return view;

+ 3 - 3
packages/ckeditor5-remove-format/tests/integration.js

@@ -48,7 +48,7 @@ describe( 'RemoveFormat', () => {
 			setModelData( model, '<paragraph>foo[<$text bold="true">foo</$text></paragraph>' +
 				'<paragraph><$text bold="true">bar</$text>]bar</paragraph>' );
 
-			editor.execute( 'removeformat' );
+			editor.execute( 'removeFormat' );
 
 			expect( getModelData( model ) )
 				.to.equal( '<paragraph>foo[foo</paragraph><paragraph>bar]bar</paragraph>' );
@@ -58,7 +58,7 @@ describe( 'RemoveFormat', () => {
 			setModelData( model, '<paragraph>[<$text linkHref="url">foo</$text></paragraph><image src="assets/sample.png">' +
 				'<caption>caption</caption></image><paragraph>bar]</paragraph>' );
 
-			editor.execute( 'removeformat' );
+			editor.execute( 'removeFormat' );
 
 			expect( getModelData( model ) )
 				.to.equal( '<paragraph>[<$text linkHref="url">foo</$text></paragraph>' +
@@ -69,7 +69,7 @@ describe( 'RemoveFormat', () => {
 			setModelData( model, '<paragraph>[</paragraph>' +
 				'<image src="assets/sample.png"><caption><$text bold="true">foo</$text></caption></image><paragraph>bar]</paragraph>' );
 
-			editor.execute( 'removeformat' );
+			editor.execute( 'removeFormat' );
 
 			expect( getModelData( model ) )
 				.to.equal( '<paragraph>' +

+ 1 - 1
packages/ckeditor5-remove-format/tests/manual/removeformat.html

@@ -15,6 +15,6 @@
 	</figure>
 
 	<p>
-		What about content that should not be removed? Say <a href="#">Links for example</a>?
+		<a href="#">Links</a> are not removed.
 	</p>
 </div>

+ 3 - 2
packages/ckeditor5-remove-format/tests/manual/removeformat.js

@@ -26,10 +26,11 @@ import Underline from '@ckeditor/ckeditor5-basic-styles/src/underline';
 
 ClassicEditor
 	.create( global.document.querySelector( '#editor' ), {
-		plugins: [ Bold, Clipboard, Enter, Highlight, Italic, Link, Paragraph, RemoveFormat, ShiftEnter, Typing,
+		plugins: [
+			Bold, Clipboard, Enter, Highlight, Italic, Link, Paragraph, RemoveFormat, ShiftEnter, Typing,
 			Underline, Undo, Image, Image, ImageCaption, ImageToolbar
 		],
-		toolbar: [ 'removeformat', 'italic', 'bold', 'link', 'underline', 'highlight', '|', 'undo', 'redo' ]
+		toolbar: [ 'removeFormat', '|', 'italic', 'bold', 'link', 'underline', 'highlight', '|', 'undo', 'redo' ]
 	} )
 	.then( editor => {
 		window.editor = editor;

+ 6 - 4
packages/ckeditor5-remove-format/tests/manual/removeformat.md

@@ -1,8 +1,10 @@
 # Remove Format
 
-Basic manual test for the remove format feature.
+Select the content and press the "Remove Format" button in the toolbar.
 
-* Bold, emphasize, underline and highlight should be removed.
+## Things to consider
+
+* Bold, emphasize, underline, and highlight should be removed.
 * Links **must not** be removed.
-* Try to remove some formatting from image caption by making selection containing the entire widget.
-* Icon is disabled if your selection doesn't contain any formatting that might be removed.
+* Try to remove some formatting from an image caption by creating a selection containing the entire widget.
+* The button should be disabled if your selection doesn't contain any formatting that might be removed.

+ 1 - 2
packages/ckeditor5-remove-format/tests/removeformatcommand.js

@@ -4,7 +4,6 @@
  */
 
 import RemoveFormatCommand from '../src/removeformatcommand';
-
 import Command from '@ckeditor/ckeditor5-core/src/command';
 import ModelTestEditor from '@ckeditor/ckeditor5-core/tests/_utils/modeltesteditor';
 import {
@@ -22,7 +21,7 @@ describe( 'RemoveFormatCommand', () => {
 				model = editor.model;
 
 				command = new RemoveFormatCommand( newEditor );
-				editor.commands.add( 'removeformat', command );
+				editor.commands.add( 'removeFormat', command );
 
 				model.schema.register( 'p', {
 					inheritAllFrom: '$block'

+ 8 - 9
packages/ckeditor5-remove-format/tests/removeformatui.js

@@ -6,8 +6,7 @@
 /* global document */
 
 import RemoveFormat from '../src/removeformat';
-import RemoveFormatUi from '../src/removeformatui';
-
+import RemoveFormatUI from '../src/removeformatui';
 import ClassicTestEditor from '@ckeditor/ckeditor5-core/tests/_utils/classictesteditor';
 import testUtils from '@ckeditor/ckeditor5-core/tests/_utils/utils';
 import {
@@ -40,12 +39,12 @@ describe( 'RemoveFormatUI', () => {
 
 		return ClassicTestEditor
 			.create( element, {
-				plugins: [ RemoveFormat, RemoveFormatUi ]
+				plugins: [ RemoveFormat, RemoveFormatUI ]
 			} )
 			.then( newEditor => {
 				editor = newEditor;
-				command = editor.commands.get( 'removeformat' );
-				button = editor.ui.componentFactory.create( 'removeformat' );
+				command = editor.commands.get( 'removeFormat' );
+				button = editor.ui.componentFactory.create( 'removeFormat' );
 			} );
 	} );
 
@@ -90,14 +89,14 @@ describe( 'RemoveFormatUI', () => {
 
 				return ClassicTestEditor
 					.create( editorElement, {
-						plugins: [ RemoveFormat, RemoveFormatUi ],
-						toolbar: [ 'removeformat' ],
+						plugins: [ RemoveFormat, RemoveFormatUI ],
+						toolbar: [ 'removeFormat' ],
 						language: 'pl'
 					} )
 					.then( newEditor => {
 						editor = newEditor;
-						button = editor.ui.componentFactory.create( 'removeformat' );
-						command = editor.commands.get( 'removeformat' );
+						button = editor.ui.componentFactory.create( 'removeFormat' );
+						command = editor.commands.get( 'removeFormat' );
 
 						editorElement.remove();