8
0
Просмотр исходного кода

Provided basic docs for the plugin.

Kamil Piechaczek 6 лет назад
Родитель
Сommit
dd5421cda5

+ 15 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-extended-category.html

@@ -0,0 +1,15 @@
+<div id="snippet-special-characters-extended-category">
+	<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>

+ 65 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-extended-category.js

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console, ClassicEditor */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-special-characters-extended-category' ), {
+		removePlugins: [
+			'SpecialCharactersEmoji'
+		],
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'alignment',
+				'|',
+				'blockQuote',
+				'link',
+				'imageUpload',
+				'mediaEmbed',
+				'insertTable',
+				'specialCharacters',
+				'|',
+				'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 );
+	} );

+ 15 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-new-category.html

@@ -0,0 +1,15 @@
+<div id="snippet-special-characters-new-category">
+	<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>

+ 65 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-new-category.js

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console, ClassicEditor */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-special-characters-new-category' ), {
+		removePlugins: [
+			'SpecialCharactersArrowsExtended'
+		],
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'alignment',
+				'|',
+				'blockQuote',
+				'link',
+				'imageUpload',
+				'mediaEmbed',
+				'insertTable',
+				'specialCharacters',
+				'|',
+				'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 );
+	} );

+ 0 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-source.html


+ 49 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters-source.js

@@ -0,0 +1,49 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* 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 SpecialCharactersEssentials from '@ckeditor/ckeditor5-special-characters/src/specialcharactersessentials';
+
+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( SpecialCharactersEssentials );
+ClassicEditor.builtinPlugins.push( SpecialCharactersEmoji );
+ClassicEditor.builtinPlugins.push( SpecialCharactersArrowsExtended );
+
+window.ClassicEditor = ClassicEditor;

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

@@ -0,0 +1,15 @@
+<div id="snippet-special-characters">
+	<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>

+ 66 - 0
packages/ckeditor5-special-characters/docs/_snippets/features/special-characters.js

@@ -0,0 +1,66 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console, ClassicEditor */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-special-characters' ), {
+		removePlugins: [
+			'SpecialCharactersEmoji',
+			'SpecialCharactersArrowsExtended'
+		],
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'alignment',
+				'|',
+				'blockQuote',
+				'link',
+				'imageUpload',
+				'mediaEmbed',
+				'insertTable',
+				'specialCharacters',
+				'|',
+				'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 );
+	} );

+ 34 - 0
packages/ckeditor5-special-characters/docs/api/special-characters.md

@@ -0,0 +1,34 @@
+---
+category: api-reference
+---
+
+# Special characters feature for CKEditor 5
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-special-characters.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-special-characters)
+
+This package implements the special characters feature for CKEditor 5.
+
+## Demo
+
+Check out the {@link features/special-characters#demo demo in the Special characters feature} guide.
+
+## Documentation
+
+See the {@link features/special-characters Special characters feature} guide and the {@link module:special-characters/specialcharacters~SpecialCharacters} plugin documentation.
+
+## Installation
+
+```plaintext
+npm install --save @ckeditor/ckeditor5-special-characters
+```
+
+## Contribute
+
+The source code of this package is available on GitHub in https://github.com/ckeditor/ckeditor5-special-characters.
+
+## External links
+
+* [`@ckeditor/ckeditor5-special-characters` on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-special-characters)
+* [`ckeditor/ckeditor5-special-characters` on GitHub](https://github.com/ckeditor/ckeditor5-special-characters)
+* [Issue tracker](https://github.com/ckeditor/ckeditor5/issues)
+* [Changelog](https://github.com/ckeditor/ckeditor5-special-characters/blob/master/CHANGELOG.md)

+ 139 - 0
packages/ckeditor5-special-characters/docs/features/special-characters.md

@@ -0,0 +1,139 @@
+---
+category: features
+menu-title: Special characters
+---
+
+# Special characters
+
+The {@link module:special-characters/specialcharacters~SpecialCharacters} plugin provides a possibility to insert a special character into the rich-text editor.
+
+## Demo
+
+Use the editor below to see the {@link module:special-characters/specialcharacters~SpecialCharacters} plugin in action.
+
+{@snippet features/special-characters-source}
+
+{@snippet features/special-characters}
+
+## Installation
+
+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:
+
+```plaintext
+npm install --save @ckeditor/ckeditor5-special-characters
+```
+
+And add it to your plugin list configuration:
+
+```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';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ SpecialCharacters, ... ],
+		toolbar: [ 'specialCharacters', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Common API
+
+The {@link module:special-characters/specialcharacters~SpecialCharacters} plugin registers the UI button component (`'specialCharacters'`).
+
+<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>
+
+## Special characters in the package
+
+The `@ckeditor/ckeditor5-special-characters` package provides a few basic special characters grouped into the following categories:
+
+- {@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.
+
+## Adding a new special character category
+
+By using the {@link module:special-characters/specialcharacters~SpecialCharacters#addItems `SpecialCharacters#addItems()`} function, you can define a new special characters category.
+
+Let's create a simple plugin that provides the `Emoji` category in the special characters dropdown.
+
+```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: '❤' }
+		] );
+	}
+}
+```
+
+After adding the above plugin into the editor, the new special characters category will be available in the dropdown.
+
+### Custom special characters category demo
+
+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-new-category}
+
+## Adding a new special characters to 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
+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: '↓' }
+		] );
+	}
+}
+```
+
+### Extending existing special characters category category demo
+
+Use the special character icon in the editor's toolbar then select `Arrows` in the select dropdown in order to add new arrows.
+
+{@snippet features/special-characters-extended-category}
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-special-characters.