|
|
@@ -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
|
|
|
|