Bladeren bron

Minor tweaks to feature and tests with review.

Mateusz Samsel 6 jaren geleden
bovenliggende
commit
fd4ee68512

+ 13 - 17
packages/ckeditor5-word-count/docs/features/word-count.md

@@ -6,7 +6,7 @@ category: features
 
 # Word count
 
-The {@link module:wordcount/wordcount~WordCount} features provide a possibility to track the number of words and characters written in the editor.
+The {@link module:wordcount/wordcount~WordCount} feature provides a possibility to track the number of words and characters written in the editor.
 
 ## Demo
 
@@ -16,7 +16,7 @@ The {@link module:wordcount/wordcount~WordCount} features provide a possibility
 <div id="editor">
 	<p>Hello world.</p>
 </div>
-<div class="word-count">
+<div id="word-count">
 </div>
 ```
 
@@ -27,22 +27,20 @@ ClassicEditor
 	} )
 	.then( editor => {
 		const wordCountPlugin = editor.plugins.get( 'WordCount' );
-		const wordCountWrapper = document.querySelector( '.word-count' );
+		const wordCountWrapper = document.getElementById( 'word-count' );
 
 		wordCountWrapper.appendChild( wordCounterPlugin.getWordCountContainer() );
 	} )
-	.catch( err => {
-		console.error( err.stack );
-	} );
+	.catch( ... );
 ```
 
 ## Configuring options
 
-There are two options which change the output container. If there is set {@link module:wordcount/wordcount~WordCountConfig#displayWords} to `false`, then the section with word counter is removed from self-updating output container. In a similar way works second option {@link module:wordcount/wordcount~WordCountConfig#displayCharacters} with character container.
+There are two options which change the output container. If the {@link module:wordcount/wordcount~WordCountConfig#displayWords} is set to to `false`, then the section with word counter is hidden. Similarly, when the {@link module:wordcount/wordcount~WordCountConfig#displayCharacters} is set to `false` it will hide the character counter.
 
 ## Update event
 
-Word count feature emits an {@link module:wordcount/wordcount~WordCount#event:update update event} whenever there is a change in a model. This allows on having own callback with customized behavior reacting on this change.
+Word count feature emits an {@link module:wordcount/wordcount~WordCount#event:update update event} whenever there is a change in the model. This allows implementing customized behavior that reacts to word count updates.
 
 Below you can find an example, where the background color of a square is changed according to the number of characters in the editor. There is also a progress bar which indicates how many words is in it (the maximal value of the progress bar is set to 100, however, you can write further and progress bar remain in the maximal state).
 
@@ -56,16 +54,14 @@ ClassicEditor
 	.then( editor => {
 		const wordCountPlugin = editor.plugins.get( 'WordCount' );
 
-		wordCountPlugin.on( 'update', ( evt, payload ) => {
-			// payload is an object with "words" and "characters" field
-			doSthWithNewWordsNumber( payload.words );
-			doSthWithNewCharactersNumber( payload.characters );
+		wordCountPlugin.on( 'update', ( evt, data ) => {
+			// data is an object with "words" and "characters" field
+			doSthWithNewWordsNumber( data.words );
+			doSthWithNewCharactersNumber( data.characters );
 		} );
 
 	} )
-	.catch( err => {
-		console.error( err.stack );
-	} );
+	.catch( ... );
 ```
 
 ## Installation
@@ -96,8 +92,8 @@ ClassicEditor
 ## Common API
 
 The {@link module:wordcount/wordcount~WordCount} plugin provides:
-  * {@link module:wordcount/wordcount~WordCount#getWordCountContainer} method. It returns a self-updating HTML Element which might be used to track the current amount of words and characters in the editor. There is a possibility to remove "Words" or "Characters" counter with proper configuration of {@link module:wordcount/wordcount~WordCountConfig#displayWords} and {@link module:wordcount/wordcount~WordCountConfig#displayCharacters},
-  * {@link module:wordcount/wordcount~WordCount#event:update update event} which provides more versatile option to handle changes of words' and characters' number. There is a possibility to run own callback function with updated values.
+  * {@link module:wordcount/wordcount~WordCount#getWordCountContainer} method. It returns a self-updating HTML element which is updated with the current number of words and characters in the editor. There is a possibility to remove "Words" or "Characters" counters with proper configuration of {@link module:wordcount/wordcount~WordCountConfig#displayWords} and {@link module:wordcount/wordcount~WordCountConfig#displayCharacters},
+  * {@link module:wordcount/wordcount~WordCount#event:update update event} which is fired whenever the plugins update the number of counted words and characters. There is a possibility to run own callback function with updated values. Please note that update event is throttled.
 
 <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.

+ 7 - 8
packages/ckeditor5-word-count/src/utils.js

@@ -8,23 +8,22 @@
  */
 
 /**
- * Function walks through all the model's nodes. It obtains a plain text from each {@link module:engine/model/text~Text}
- * and {@link module:engine/model/textproxy~TextProxy}. All sections, which are not a text, are separated with a new line (`\n`).
+ * Returns plain text representation of an element and it's children. The blocks are separated by a newline (\n ).
  *
- * **Note:** Function walks through the entire model. There should be considered throttling during usage.
+ * **Note:** Function walks through the entire model, which might be very spread. There should be considered throttling it during usage.
  *
- * @param {module:engine/model/node~Node} node
+ * @param {module:engine/model/element~Element} element
  * @returns {String} Plain text representing model's data
  */
-export function modelElementToPlainText( node ) {
+export function modelElementToPlainText( element ) {
 	let text = '';
 
-	if ( node.is( 'text' ) || node.is( 'textProxy' ) ) {
-		text += node.data;
+	if ( element.is( 'text' ) || element.is( 'textProxy' ) ) {
+		text += element.data;
 	} else {
 		let prev = null;
 
-		for ( const child of node.getChildren() ) {
+		for ( const child of element.getChildren() ) {
 			const childText = modelElementToPlainText( child );
 
 			// If last block was finish, start from new line.

+ 16 - 16
packages/ckeditor5-word-count/src/wordcount.js

@@ -51,7 +51,7 @@ export default class WordCount extends Plugin {
 		super( editor );
 
 		/**
-		 * Property stores number of characters detected by {@link module:wordcount/wordcount~WordCount WordCount plugin}.
+		 * The number of characters in the editor.
 		 *
 		 * @observable
 		 * @readonly
@@ -60,7 +60,7 @@ export default class WordCount extends Plugin {
 		this.set( 'characters', 0 );
 
 		/**
-		 * Property stores number of words detected by {@link module:wordcount/wordcount~WordCount WordCount plugin}.
+		 * The number of words in the editor.
 		 *
 		 * @observable
 		 * @readonly
@@ -69,7 +69,7 @@ export default class WordCount extends Plugin {
 		this.set( 'words', 0 );
 
 		/**
-		 * Keeps reference to {@link module:ui/view~View view object} used to display self-updating HTML container.
+		 * A reference to a {@link module:ui/view~View view object} which contains self-updating HTML container.
 		 *
 		 * @private
 		 * @readonly
@@ -91,7 +91,7 @@ export default class WordCount extends Plugin {
 	init() {
 		const editor = this.editor;
 
-		editor.model.document.on( 'change', throttle( this._calcWordsAndCharacters.bind( this ), 250 ) );
+		editor.model.document.on( 'change:data', throttle( this._calculateWordsAndCharacters.bind( this ), 250 ) );
 	}
 
 	/**
@@ -116,16 +116,16 @@ export default class WordCount extends Plugin {
 	 * @returns {HTMLElement}
 	 */
 	getWordCountContainer() {
+		const editor = this.editor;
+		const t = editor.t;
+		const displayWords = editor.config.get( 'wordCount.displayWords' );
+		const displayCharacters = editor.config.get( 'wordCount.displayCharacters' );
+		const bind = Template.bind( this, this );
+		const children = [];
+
 		if ( !this._outputView ) {
 			this._outputView = new View();
 
-			const editor = this.editor;
-			const t = editor.t;
-			const displayWords = editor.config.get( 'wordCount.displayWords' );
-			const displayCharacters = editor.config.get( 'wordCount.displayCharacters' );
-			const bind = Template.bind( this, this );
-			const children = [];
-
 			if ( displayWords || displayWords === undefined ) {
 				const wordsLabel = t( 'Words' ) + ':';
 
@@ -182,7 +182,7 @@ export default class WordCount extends Plugin {
 	 * @private
 	 * @fires update
 	 */
-	_calcWordsAndCharacters() {
+	_calculateWordsAndCharacters() {
 		const txt = modelElementToPlainText( this.editor.model.document.getRoot() );
 
 		this.characters = txt.length;
@@ -197,7 +197,7 @@ export default class WordCount extends Plugin {
 }
 
 /**
- * Event is fired after {@link #words} and {@link #characters} are updated.
+ * Event fired after {@link #words} and {@link #characters} are updated.
  *
  * @event update
  * @param {Object} data
@@ -230,7 +230,7 @@ export default class WordCount extends Plugin {
  */
 
 /**
- * This option allows on hiding the word counter. The element obtained through
+ * This option allows for hiding the word counter. The element obtained through
  * {@link module:wordcount/wordcount~WordCount#getWordCountContainer} will only preserve
  * the characters part. Word counter is displayed by default when this configuration option is not defined.
  *
@@ -248,7 +248,7 @@ export default class WordCount extends Plugin {
  */
 
 /**
- * This option allows on hiding the character counter. The element obtained through
+ * This option allows for hiding the character counter. The element obtained through
  * {@link module:wordcount/wordcount~WordCount#getWordCountContainer} will only preserve
  * the words part. Character counter is displayed by default when this configuration option is not defined.
  *
@@ -256,7 +256,7 @@ export default class WordCount extends Plugin {
  *			displayCharacters = false
  *		}
  *
- * The mentioned configuration will result with the followed container:
+ * The mentioned configuration will result in the following container
  *
  *		<div class="ck ck-word-count">
  *			<div>Words: 4</div>

+ 4 - 4
packages/ckeditor5-word-count/tests/manual/wordcount.md

@@ -1,8 +1,8 @@
-1. Try to type in editor. Container below should be automatically updated with new amount of words and characters.
-2. Special characters are treat as separators for words. For example
+1. Try to type in the editor. The container below should be automatically updated with the current amount of words and characters.
+2. Special characters are treated as separators for words. For example
 	* `Hello world` - 2 words
 	* `Hello(World)` - 2 words
 	* `Hello\nWorld` - 2 words
-3. Numbers are treat as words.
+3. Numbers are treated as words.
 4. There are logged values of `WordCount:event-update` in the console. Values should change in same way as container in html.
-5. After destroy container with word and character values should be removed.
+5. After destroying the editor, the container with word and character values should be also removed.

+ 11 - 9
packages/ckeditor5-word-count/tests/utils.js

@@ -8,17 +8,19 @@ import { modelElementToPlainText } from '../src/utils';
 import Element from '@ckeditor/ckeditor5-engine/src/model/element';
 import Text from '@ckeditor/ckeditor5-engine/src/model/text';
 
-describe( 'modelElementToPlainText()', () => {
-	it( 'should extract only plain text', () => {
-		const text1 = new Text( 'Foo' );
-		const text2 = new Text( 'Bar', { bold: true } );
-		const text3 = new Text( 'Baz', { bold: true, underline: true } );
+describe( 'utils', () => {
+	describe( 'modelElementToPlainText()', () => {
+		it( 'should extract only plain text', () => {
+			const text1 = new Text( 'Foo' );
+			const text2 = new Text( 'Bar', { bold: true } );
+			const text3 = new Text( 'Baz', { bold: true, underline: true } );
 
-		const innerElement1 = new Element( 'paragraph', null, [ text1 ] );
-		const innerElement2 = new Element( 'paragraph', null, [ text2, text3 ] );
+			const innerElement1 = new Element( 'paragraph', null, [ text1 ] );
+			const innerElement2 = new Element( 'paragraph', null, [ text2, text3 ] );
 
-		const mainElement = new Element( 'container', null, [ innerElement1, innerElement2 ] );
+			const mainElement = new Element( 'container', null, [ innerElement1, innerElement2 ] );
 
-		expect( modelElementToPlainText( mainElement ) ).to.equal( 'Foo\nBarBaz' );
+			expect( modelElementToPlainText( mainElement ) ).to.equal( 'Foo\nBarBaz' );
+		} );
 	} );
 } );

+ 9 - 11
packages/ckeditor5-word-count/tests/wordcount.js

@@ -58,7 +58,7 @@ describe( 'WordCount', () => {
 				'<paragraph>1234</paragraph>' +
 				'<paragraph>(-@#$%^*())</paragraph>' );
 
-			wordCountPlugin._calcWordsAndCharacters();
+			wordCountPlugin._calculateWordsAndCharacters();
 
 			expect( wordCountPlugin.words ).to.equal( 6 );
 		} );
@@ -66,7 +66,7 @@ describe( 'WordCount', () => {
 		it( 'counts characters', () => {
 			setModelData( model, '<paragraph><$text foo="true">Hello</$text> world.</paragraph>' );
 
-			wordCountPlugin._calcWordsAndCharacters();
+			wordCountPlugin._calculateWordsAndCharacters();
 
 			expect( wordCountPlugin.characters ).to.equal( 12 );
 		} );
@@ -76,14 +76,14 @@ describe( 'WordCount', () => {
 				const fake = sinon.fake();
 				wordCountPlugin.on( 'update', fake );
 
-				wordCountPlugin._calcWordsAndCharacters();
+				wordCountPlugin._calculateWordsAndCharacters();
 
 				sinon.assert.calledOnce( fake );
 				sinon.assert.calledWithExactly( fake, sinon.match.any, { words: 0, characters: 0 } );
 
-				// _calcWordsAndCharacters is throttled, so for this test case is run manually
+				// _calculateWordsAndCharacters is throttled, so for this test case is run manually
 				setModelData( model, '<paragraph><$text foo="true">Hello</$text> world.</paragraph>' );
-				wordCountPlugin._calcWordsAndCharacters();
+				wordCountPlugin._calculateWordsAndCharacters();
 
 				sinon.assert.calledTwice( fake );
 				sinon.assert.calledWithExactly( fake, sinon.match.any, { words: 2, characters: 12 } );
@@ -120,7 +120,7 @@ describe( 'WordCount', () => {
 			setModelData( model, '<paragraph>Foo(bar)baz</paragraph>' +
 				'<paragraph><$text foo="true">Hello</$text> world.</paragraph>' );
 
-			wordCountPlugin._calcWordsAndCharacters();
+			wordCountPlugin._calculateWordsAndCharacters();
 
 			// There is \n between paragraph which has to be included into calculations
 			expect( container.innerText ).to.equal( 'Words: 5Characters: 24' );
@@ -133,7 +133,7 @@ describe( 'WordCount', () => {
 		} );
 
 		describe( 'destroy()', () => {
-			it( 'html element is removed and cleanup', done => {
+			it( 'html element is removed', done => {
 				const frag = document.createDocumentFragment();
 
 				frag.appendChild( container );
@@ -161,12 +161,10 @@ describe( 'WordCount', () => {
 		} );
 	} );
 
-	describe( '_calcWordsAndCharacters and throttle', () => {
+	describe( '_calculateWordsAndCharacters and throttle', () => {
 		beforeEach( done => {
 			// We need to flush initial throttle value after editor's initialization
-			setTimeout( () => {
-				done();
-			}, 255 );
+			setTimeout( done, 255 );
 		} );
 
 		it( 'gets update after model data change', done => {