Parcourir la source

Merge pull request #12 from ckeditor/i/5985

Docs: Corrected the docs for special characters. Closes ckeditor/ckeditor5#5985.
Piotrek Koszuliński il y a 6 ans
Parent
commit
e5aa2e7d36

+ 11 - 6
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-extended-category.js

@@ -3,15 +3,22 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
-/* globals window, document, console, ClassicEditor */
+/* globals window, document, console, ClassicEditor, SpecialCharactersEssentials */
 
 import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
 
+function SpecialCharactersArrowsExtended( editor ) {
+	editor.plugins.get( 'SpecialCharacters' ).addItems( 'Arrows', [
+		{ title: 'simple arrow left', character: '←' },
+		{ title: 'simple arrow up', character: '↑' },
+		{ title: 'simple arrow right', character: '→' },
+		{ title: 'simple arrow down', character: '↓' }
+	] );
+}
+
 ClassicEditor
 	.create( document.querySelector( '#snippet-special-characters-extended-category' ), {
-		removePlugins: [
-			'SpecialCharactersEmoji'
-		],
+		extraPlugins: [ SpecialCharactersEssentials, SpecialCharactersArrowsExtended ],
 		toolbar: {
 			items: [
 				'heading',
@@ -24,8 +31,6 @@ ClassicEditor
 				'outdent',
 				'indent',
 				'|',
-				'alignment',
-				'|',
 				'specialCharacters',
 				'blockQuote',
 				'link',

+ 15 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-limited-categories.html

@@ -0,0 +1,15 @@
+<div id="snippet-special-characters-limited-categories">
+	<h2 style="text-align:center;">The Flavorful Tuscany Meetup</h2>
+	<h3 style="text-align:center;">Welcome letter</h3>
+	<p>Dear Guest,</p>
+	<p>We are delighted to welcome you to the annual <i>Flavorful Tuscany Meetup</i> and hope you will enjoy the programme as well as your stay at the <a href="https://ckeditor.com">Bilancino Hotel</a>.</p>
+	<p>Please arrive at the <a href="https://ckeditor.com">Bilancino Hotel</a> reception desk at least half an hour earlier to make sure that the registration process goes as smoothly as possible.</p>
+	<p>We look forward to welcoming you to the event. The full schedule can be found below.</p>
+</div>
+
+<style>
+	.ck-content h2 {
+		border-bottom: none;
+		margin-bottom: 0;
+	}
+</style>

+ 61 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-limited-categories.js

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console, ClassicEditor, SpecialCharactersCurrency, SpecialCharactersMathematical */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-special-characters-limited-categories' ), {
+		extraPlugins: [ SpecialCharactersCurrency, SpecialCharactersMathematical ],
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'specialCharacters',
+				'blockQuote',
+				'link',
+				'imageUpload',
+				'mediaEmbed',
+				'insertTable',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		image: {
+			styles: [
+				'full',
+				'alignLeft',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:full',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
+		},
+		table: {
+			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 12 - 6
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-new-category.js

@@ -3,15 +3,23 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
-/* globals window, document, console, ClassicEditor */
+/* globals window, document, console, ClassicEditor, SpecialCharactersEssentials */
 
 import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
 
+function SpecialCharactersEmoji( editor ) {
+	editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [
+		{ title: 'smiley face', character: '😊' },
+		{ title: 'rocket', character: '🚀' },
+		{ title: 'basketball', character: '🏀' },
+		{ title: 'floppy disk', character: '💾' },
+		{ title: 'hearth', character: '❤' }
+	] );
+}
+
 ClassicEditor
 	.create( document.querySelector( '#snippet-special-characters-new-category' ), {
-		removePlugins: [
-			'SpecialCharactersArrowsExtended'
-		],
+		extraPlugins: [ SpecialCharactersEssentials, SpecialCharactersEmoji ],
 		toolbar: {
 			items: [
 				'heading',
@@ -24,8 +32,6 @@ ClassicEditor
 				'outdent',
 				'indent',
 				'|',
-				'alignment',
-				'|',
 				'specialCharacters',
 				'blockQuote',
 				'link',

+ 6 - 37
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-source.js

@@ -5,47 +5,16 @@
 
 /* globals window */
 
-import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
-import Alignment from '@ckeditor/ckeditor5-alignment/src/alignment';
 import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
 import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
+import SpecialCharactersCurrency from '@ckeditor/ckeditor5-special-characters/src/SpecialCharactersCurrency';
+import SpecialCharactersMathematical from '@ckeditor/ckeditor5-special-characters/src/SpecialCharactersMathematical';
 
-class SpecialCharactersEmoji extends Plugin {
-	static get pluginName() {
-		return 'SpecialCharactersEmoji';
-	}
-
-	init() {
-		this.editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [
-			{ title: 'smiley face', character: '😊' },
-			{ title: 'rocket', character: '🚀' },
-			{ title: 'basketball', character: '🏀' },
-			{ title: 'floppy disk', character: '💾' },
-			{ title: 'hearth', character: '❤' }
-		] );
-	}
-}
-
-class SpecialCharactersArrowsExtended extends Plugin {
-	static get pluginName() {
-		return 'SpecialCharactersArrowsExtended';
-	}
-
-	init() {
-		this.editor.plugins.get( 'SpecialCharacters' ).addItems( 'Arrows', [
-			{ title: 'simple arrow left', character: '←' },
-			{ title: 'simple arrow up', character: '↑' },
-			{ title: 'simple arrow right', character: '→' },
-			{ title: 'simple arrow down', character: '↓' }
-		] );
-	}
-}
-
-ClassicEditor.builtinPlugins.push( Alignment );
 ClassicEditor.builtinPlugins.push( SpecialCharacters );
-ClassicEditor.builtinPlugins.push( SpecialCharactersEssentials );
-ClassicEditor.builtinPlugins.push( SpecialCharactersEmoji );
-ClassicEditor.builtinPlugins.push( SpecialCharactersArrowsExtended );
 
 window.ClassicEditor = ClassicEditor;
+window.SpecialCharacters = SpecialCharacters;
+window.SpecialCharactersCurrency = SpecialCharactersCurrency;
+window.SpecialCharactersMathematical = SpecialCharactersMathematical;
+window.SpecialCharactersEssentials = SpecialCharactersEssentials;

+ 2 - 7
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters.js

@@ -3,16 +3,13 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
-/* globals window, document, console, ClassicEditor */
+/* globals window, document, console, ClassicEditor, SpecialCharactersEssentials */
 
 import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
 
 ClassicEditor
 	.create( document.querySelector( '#snippet-special-characters' ), {
-		removePlugins: [
-			'SpecialCharactersEmoji',
-			'SpecialCharactersArrowsExtended'
-		],
+		extraPlugins: [ SpecialCharactersEssentials ],
 		toolbar: {
 			items: [
 				'heading',
@@ -25,8 +22,6 @@ ClassicEditor
 				'outdent',
 				'indent',
 				'|',
-				'alignment',
-				'|',
 				'specialCharacters',
 				'blockQuote',
 				'link',

+ 110 - 84
packages/ckeditor5-special-characters/docs/features/special-characters.md

@@ -15,136 +15,162 @@ Use the editor below to see the {@link module:special-characters/specialcharacte
 
 {@snippet features/special-characters}
 
-## Installation
+## Configuration
 
-To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-special-characters`](https://www.npmjs.com/package/@ckeditor/ckeditor5-special-characters) package:
+### Adding a new category
 
-```plaintext
-npm install --save @ckeditor/ckeditor5-special-characters
-```
+You can define a new special characters category using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function.
 
-And add it to your plugin list configuration:
+For example, the following plugin adds the "Emoji" category in the special characters dropdown.
 
 ```js
-// The plugin provides API for management special characters and their categories. 
 import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
-
-// `SpecialCharacters` does not provide any special character. They are delivered by another plugins.
-// You can import those ones that you want to use in the editor.
-import SpecialCharactersCurrency from '@ckeditor/ckeditor5-special-characters/src/specialcharacterscurrency';
-import SpecialCharactersMathematical from '@ckeditor/ckeditor5-special-characters/src/specialcharactersmathematical';
-import SpecialCharactersArrows from '@ckeditor/ckeditor5-special-characters/src/specialcharactersarrows';
-import SpecialCharactersLatin from '@ckeditor/ckeditor5-special-characters/src/specialcharacterslatin';
-import SpecialCharactersText from '@ckeditor/ckeditor5-special-characters/src/specialcharacterstext';
-
-// Or import the plugin combining basic set of characters. The imports above can be replaced with the `SpecialCharactersEssentials` plugin.
 import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
 
+function SpecialCharactersEmoji( editor ) {
+	editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [
+		{ title: 'smiley face', character: '😊' },
+		{ title: 'rocket', character: '🚀' },
+		{ title: 'basketball', character: '🏀' },
+		{ title: 'floppy disk', character: '💾' },
+		{ title: 'hearth', character: '❤' }
+	] );
+}
+
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
-		plugins: [ SpecialCharacters, ... ],
+		plugins: [
+			SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersEmoji,
+
+			// Other plugins...
+		],
 		toolbar: [ 'specialCharacters', ... ],
 	} )
 	.then( ... )
 	.catch( ... );
 ```
 
-<info-box info>
-	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+After adding the above plugin into the editor, the new category will be available in the special characters dropdown.
+
+<info-box>
+	A title of a special character must be unique across the entire special characters set.
 </info-box>
 
-## Common API
+Below, you can see a demo based on the example shown above. Use the special characters icon in the editor's toolbar then select "Emoji" in the select dropdown in order to insert a emoji into the editor.
 
-The {@link module:special-characters/specialcharacters~SpecialCharacters} plugin registers the UI button component (`'specialCharacters'`).
+{@snippet features/special-characters-new-category}
+
+### Adding characters to an existing category
+
+By using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function, you can also add new special characters into existing category.
+
+```js
+import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
+import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
+
+function SpecialCharactersArrowsExtended( editor ) {
+	editor.plugins.get( 'SpecialCharacters' ).addItems( 'Arrows', [
+		{ title: 'simple arrow left', character: '←' },
+		{ title: 'simple arrow up', character: '↑' },
+		{ title: 'simple arrow right', character: '→' },
+		{ title: 'simple arrow down', character: '↓' }
+	] );
+}
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [
+			SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersArrowsExtended,
+
+			// Other plugins...
+		],
+		toolbar: [ 'specialCharacters', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
+```
 
 <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.
+	A title of a special character must be unique across the entire special characters set.
 </info-box>
 
-## Special characters in the package
+Below, you can see a demo based on the example shown above. Use the special characters icon in the editor's toolbar then select "Arrows" in the select dropdown. You'll see that it contains more arrows than the other instances.
 
-The `@ckeditor/ckeditor5-special-characters` package provides a few basic special characters grouped into the following categories:
+{@snippet features/special-characters-extended-category}
 
-- {@link module:special-characters/specialcharactersarrows~SpecialCharactersArrows} – arrows special characters,
-- {@link module:special-characters/specialcharacterscurrency~SpecialCharactersCurrency} - currency special characters,
-- {@link module:special-characters/specialcharacterslatin~SpecialCharactersLatin} – Latin special characters,
-- {@link module:special-characters/specialcharactersmathematical~SpecialCharactersMathematical} – Mathematical special characters,
-- {@link module:special-characters/specialcharacterstext~SpecialCharactersText} – Text special characters
-- {@link module:special-characters/specialcharactersessentials~SpecialCharactersEssentials} – combining plugins listed above.
+### Removing categories
 
-## Adding a new special character category
+The special characters feature exposes each category as a separate plugin. While the {@link module:special-characters/specialcharactersessentials~SpecialCharactersEssentials} plugin can be used to conveniently include all of them, you can customize the category list by adding individual plugins.
 
-By using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function, you can define a new special characters category.
+The `@ckeditor/ckeditor5-special-characters` package provides special characters grouped into the following categories:
 
-<info-box warning>
-    The "All" category name is reserved by the plugin and cannot be used as a new name for special characters category.
-</info-box>
+* {@link module:special-characters/specialcharactersarrows~SpecialCharactersArrows} – arrows special characters,
+* {@link module:special-characters/specialcharacterscurrency~SpecialCharactersCurrency} - currency special characters,
+* {@link module:special-characters/specialcharacterslatin~SpecialCharactersLatin} – Latin special characters,
+* {@link module:special-characters/specialcharactersmathematical~SpecialCharactersMathematical} – mathematical special characters,
+* {@link module:special-characters/specialcharacterstext~SpecialCharactersText} – text special characters,
+* {@link module:special-characters/specialcharactersessentials~SpecialCharactersEssentials} – combining plugins listed above.
 
-Let's create a simple plugin that provides the `Emoji` category in the special characters dropdown.
+For example, you can limit categories to "Mathematical" and "Currency" only by picking the {@link module:special-characters/specialcharactersmathematical~SpecialCharactersMathematical} and {@link module:special-characters/specialcharacterscurrency~SpecialCharactersCurrency} plugins, like so:
 
 ```js
-import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
-
-export default class SpecialCharactersEmoji extends Plugin {
-	static get pluginName() {
-		return 'SpecialCharactersEmoji';
-	}
-
-	init() {
-		this.editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [
-			{ title: 'smiley face', character: '😊' },
-			{ title: 'rocket', character: '🚀' },
-			{ title: 'basketball', character: '🏀' },
-			{ title: 'floppy disk', character: '💾' },
-			{ title: 'hearth', character: '❤' }
-		] );
-	}
-}
-```
+import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
+import SpecialCharactersCurrency from '@ckeditor/ckeditor5-special-characters/src/specialcharacterscurrency';
+import SpecialCharactersMathematical from '@ckeditor/ckeditor5-special-characters/src/specialcharactersmathematical';
 
-After adding the above plugin into the editor, the new special characters category will be available in the dropdown.
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [
+			SpecialCharacters, SpecialCharactersCurrency, SpecialCharactersMathematical,
 
-<info-box warning>
-    A title of a special character must be unique across the entire special characters set.
-</info-box>
+			// Other plugins...
+		],
+		toolbar: [ 'specialCharacters', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
+```
 
-### Custom special characters category demo
+Below, you can see a demo based on the example shown above. After clicking the special character icon in the editor's toolbar you can see that it contains fewer categories compared to other editors on this page.
 
-Use the special character icon in the editor's toolbar then select `Emoji` in the select dropdown in order to insert a emoji into the editor.
+{@snippet features/special-characters-limited-categories}
 
-{@snippet features/special-characters-new-category}
+## Installation
 
-## Adding a new special characters to existing category
+To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-special-characters`](https://www.npmjs.com/package/@ckeditor/ckeditor5-special-characters) package:
 
-By using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function, you can also add new special characters into existing category.
+```plaintext
+npm install --save @ckeditor/ckeditor5-special-characters
+```
+
+And add it to your plugin list configuration:
 
 ```js
-class SpecialCharactersArrowsExtended extends Plugin {
-	static get pluginName() {
-		return 'SpecialCharactersArrowsExtended';
-	}
-
-	init() {
-        // The `Arrows` category is provided by the `SpecialCharactersArrows` plugin.
-		this.editor.plugins.get( 'SpecialCharacters' ).addItems( 'Arrows', [
-			{ title: 'simple arrow left', character: '←' },
-			{ title: 'simple arrow up', character: '↑' },
-			{ title: 'simple arrow right', character: '→' },
-			{ title: 'simple arrow down', character: '↓' }
-		] );
-	}
-}
+// Core plugin that provides the API for management special characters and their categories.
+import SpecialCharacters from '@ckeditor/ckeditor5-special-characters/src/specialcharacters';
+// Plugin that combines the basic set of special characters.
+import SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ SpecialCharacters, SpecialCharactersEssentials, ... ],
+		toolbar: [ 'specialCharacters', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
 ```
 
-<info-box warning>
-    A title of a special character must be unique across the entire special characters set.
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 </info-box>
 
-### Extending existing special characters category category demo
+## Common API
 
-Use the special character icon in the editor's toolbar then select `Arrows` in the select dropdown in order to add new arrows.
+The {@link module:special-characters/specialcharacters~SpecialCharacters} plugin registers the UI button component (`'specialCharacters'`).
 
-{@snippet features/special-characters-extended-category}
+<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
 

+ 3 - 0
packages/ckeditor5-special-characters/src/specialcharacters.js

@@ -132,6 +132,9 @@ export default class SpecialCharacters extends Plugin {
 	/**
 	 * Adds a collection of special characters to specified group. A title of a special character must be unique.
 	 *
+	 * **Note:** The "All" category name is reserved by the plugin and cannot be used as a new name for special
+	 * characters category.
+	 *
 	 * @param {String} groupName
 	 * @param {Array.<module:special-characters/specialcharacters~SpecialCharacterDefinition>} items
 	 */