Sfoglia il codice sorgente

Docs: Add highlight feature guide.

Maciej Gołaszewski 8 anni fa
parent
commit
bbe9f6ff8f

+ 23 - 0
packages/ckeditor5-highlight/docs/_snippets/features/build-highlight-source.html

@@ -0,0 +1,23 @@
+<style>
+	.marker {
+		background-color: #ffff66;
+	}
+
+	.marker-green {
+		background-color: #66ff00;
+	}
+
+	.marker-pink {
+		background-color: #ff6fff;
+	}
+
+	.pen-red {
+		background-color: transparent;
+		color: #ff2929;
+	}
+
+	.pen-blue {
+		background-color: transparent;
+		color: #0091ff;
+	}
+</style>

+ 14 - 0
packages/ckeditor5-highlight/docs/_snippets/features/build-highlight-source.js

@@ -0,0 +1,14 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals window */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+
+import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight';
+
+ClassicEditor.build.plugins.push( Highlight );
+
+window.ClassicEditor = ClassicEditor;

+ 5 - 0
packages/ckeditor5-highlight/docs/_snippets/features/custom-highlight-options.html

@@ -0,0 +1,5 @@
+<div id="snippet-custom-highlight-options">
+	<p>
+		Here are defined highlighters: <mark class="marker-green">green one</mark> and <mark class="pen-blue">blue one</mark>.
+	</p>
+</div>

+ 27 - 0
packages/ckeditor5-highlight/docs/_snippets/features/custom-highlight-options.js

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+ClassicEditor
+	.create( document.querySelector( '#snippet-custom-highlight-options' ), {
+		toolbar: {
+			items: [
+				'headings', 'bulletedList', 'numberedList', 'highlightDropdown', 'undo', 'redo'
+			],
+			viewportTopOffset: 60
+		},
+		highlight: {
+			options: [
+				{ model: 'greenMarker', class: 'marker-green', title: 'Green marker', color: '#66ff00', type: 'marker' },
+				{ model: 'bluePen', class: 'pen-blue', title: 'Blue pen', color: '#0091ff', type: 'pen' }
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 12 - 0
packages/ckeditor5-highlight/docs/_snippets/features/highlight-buttons.html

@@ -0,0 +1,12 @@
+<div id="snippet-highlight-buttons">
+	<h2>Highlight feature sample.</h2>
+
+	<p>
+		Here are some markers:
+		<mark class="marker">yellow one</mark>, <mark class="marker-pink">pink one</mark> and <mark class="marker-green">green one</mark>.
+	</p>
+	<p>
+		Here are some pens:
+		<mark class="pen-red">red pen</mark> and <mark class="pen-blue">blue one</mark>.
+	</p>
+</div>

+ 23 - 0
packages/ckeditor5-highlight/docs/_snippets/features/highlight-buttons.js

@@ -0,0 +1,23 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-highlight-buttons' ), {
+		toolbar: {
+			items: [
+				'headings', 'highlight:marker', 'highlight:greenMarker', 'highlight:pinkMarker', 'highlight:bluePen',
+				'highlight:redPen', 'removeHighlight', 'undo', 'redo'
+			],
+			viewportTopOffset: 60
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 12 - 0
packages/ckeditor5-highlight/docs/_snippets/features/highlight.html

@@ -0,0 +1,12 @@
+<div id="snippet-highlight">
+	<h2>Highlight feature sample.</h2>
+
+	<p>
+		Here are some markers:
+		<mark class="marker">yellow one</mark>, <mark class="marker-pink">pink one</mark> and <mark class="marker-green">green one</mark>.
+	</p>
+	<p>
+		Here are some pens:
+		<mark class="pen-red">red pen</mark> and <mark class="pen-blue">blue one</mark>.
+	</p>
+</div>

+ 22 - 0
packages/ckeditor5-highlight/docs/_snippets/features/highlight.js

@@ -0,0 +1,22 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-highlight' ), {
+		toolbar: {
+			items: [
+				'headings', 'bulletedList', 'numberedList', 'highlightDropdown', 'undo', 'redo'
+			],
+			viewportTopOffset: 60
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 138 - 0
packages/ckeditor5-highlight/docs/features/highlight.md

@@ -0,0 +1,138 @@
+---
+title: Highlight
+category: features
+---
+
+{@snippet features/build-highlight-source}
+
+The {@link module:highlight/highlight~Highlight} feature enables support for setting highlight.
+
+## Demo
+
+{@snippet features/highlight}
+
+## Configuring highlight options
+
+It is, of course, possible to configure which highlight options the editor should support.
+Use the {@link module:highlight/highlight~HighlightConfig#options `highlight.options`} configuration option to do so.
+
+For example, the following editor will support only two highlighters:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		highlight: {
+			options: [
+				{
+					model: 'greenMarker',
+					class: 'marker-green',
+					title: 'Green marker',
+					color: '#66ff00',
+					type: 'marker' 
+				},
+				{ 
+					model: 'bluePen',
+					class: 'pen-blue',
+					title: 'Blue pen',
+					color: '#0091ff',
+					type: 'pen' 
+				}
+			]
+		},
+		toolbar: [
+			'headings', 'bulletedList', 'numberedList', 'highlight', 'undo', 'redo'
+		]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+{@snippet features/custom-highlight-options}
+
+Instead of using `highlightDropdown` the editor supports also button configuration:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		toolbar: {
+			items: [
+				'headings', 'highlight:marker', 'highlight:greenMarker',
+				'highlight:pinkMarker', 'highlight:bluePen',
+				'highlight:redPen', 'removeHighlight', 'undo', 'redo'
+			],
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+{@snippet features/highlight-buttons}
+
+## Installation
+
+To add this feature to your editor install the [`@ckeditor/ckeditor5-highlight`](https://www.npmjs.com/package/@ckeditor/ckeditor5-highlight) package:
+
+```
+npm install --save @ckeditor/ckeditor5-highlight
+```
+
+And add it to your plugin list and toolbar configuration:
+
+```js
+import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Highlight, ... ],
+		toolbar: [ 'highlightDropdown', ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/development/installing-plugins installing plugins}.
+</info-box>
+
+## Common API
+
+The {@link module:highlight/highlight~Highlight} plugin registers:
+
+* Dropdown: `'highlightDropdown'`.
+* Command: `'highlight'`.
+
+	The number of options and their names are based on the {@link module:highlight/highlight~HighlightConfig#options `highlight.options`} configuration option).
+
+	You can change highlight of the current selection by executing command with proper value:
+
+	```js
+	editor.execute( 'highlight', { value: 'marker' } );
+	```
+
+	The Value passed to `highlight` corresponds to the `model` property in configuration object. For default configuration:
+	```js
+	highlight.options = [
+		{ model: 'marker', class: 'marker', title: 'Marker', color: '#ffff66', type: 'marker' },
+		{ model: 'greenMarker', class: 'marker-green', title: 'Green marker', color: '#66ff00', type: 'marker' },
+		{ model: 'pinkMarker', class: 'marker-pink', title: 'Pink marker', color: '#ff6fff', type: 'marker' },
+		{ model: 'redPen', class: 'pen-red', title: 'Red pen', color: '#ff2929', type: 'pen' },
+		{ model: 'bluePen', class: 'pen-blue', title: 'Blue pen', color: '#0091ff', type: 'pen' }
+	]
+	```
+	
+	the `highlight` command will accept strings below as value:
+	- `'marker'` - and will be available as `highligth:marker'` button.
+	- `'greenMarker'` - and will be available as `highligth:greenMarker'` button.
+	- `'pinkMarker'` - and will be available as `highligth:pinkMarker'` button.
+	- `'redPen'` - and will be available as `highligth:redPen'` button.
+	- `'bluePen'` - and will be available as `highligth:bluePen'` button.
+	
+	passing an empty value will remove any `highlight` set:
+	
+	```js
+	editor.execute( 'highlight' );
+	```
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-highlight.

+ 1 - 1
packages/ckeditor5-highlight/tests/manual/highlight.html

@@ -20,8 +20,8 @@
 		background-color: transparent;
 		color: #0091ff;
 	}
-
 </style>
+
 <div id="editor">
 	<p>Highlight feature example.</p>
 	<p>