瀏覽代碼

Added examples to docs & updated descriptions.

Damian Konopka 7 年之前
父節點
當前提交
a5616d5041

+ 25 - 0
packages/ckeditor5-highlight/docs/_snippets/features/custom-highlight-colors-normal.html

@@ -0,0 +1,25 @@
+<style>
+	/* We are not using here :root because of many instances of editor */
+	#snippet-custom-highlight-colors-normal + .ck-editor .marker-green {
+		background-color: rgb(24, 201, 32);
+	}
+
+	#snippet-custom-highlight-colors-normal + .ck-editor .marker-yellow {
+		background-color: #f2ee28;
+	}
+
+	#snippet-custom-highlight-colors-normal + .ck-editor .pen-red {
+		color: hsl(355, 78%, 49%);
+	}
+</style>
+
+<div id="snippet-custom-highlight-colors-normal">
+	<p>
+		Here are markers defined as rgb, hex or hsl format directly in .js config:
+	</p>
+	<ul>
+		<li>the <mark class="marker-green">green one</mark></li>
+		<li>the <mark class="marker-yellow">yellow one</mark></li>
+		<li>the <mark class="pen-red">red one</mark></li>
+	</ul>
+</div>

+ 46 - 0
packages/ckeditor5-highlight/docs/_snippets/features/custom-highlight-colors-normal.js

@@ -0,0 +1,46 @@
+/**
+ * @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-colors-normal' ), {
+		toolbar: {
+			items: [
+				'headings', '|', 'bulletedList', 'numberedList', 'highlightDropdown', 'undo', 'redo'
+			],
+			viewportTopOffset: 60
+		},
+		highlight: {
+			options: [
+				{
+					model: 'greenMarker',
+					class: 'marker-green',
+					title: 'Green marker',
+					color: 'rgb(24, 201, 32)',
+					type: 'marker'
+				},
+				{
+					model: 'yellowMarker',
+					class: 'marker-yellow',
+					title: 'Yellow marker',
+					color: '#f2ee28',
+					type: 'marker'
+				},
+				{
+					model: 'redPen',
+					class: 'pen-red',
+					title: 'Red pen',
+					color: 'hsl(355, 78%, 49%)',
+					type: 'pen'
+				},
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 25 - 0
packages/ckeditor5-highlight/docs/_snippets/features/custom-highlight-colors-variables.html

@@ -0,0 +1,25 @@
+<style>
+	/* We are not using here :root because of many instances of editor */
+	#snippet-custom-highlight-colors-variables + .ck-editor {
+
+		/* Make green a little darker. */
+		--ck-highlight-marker-green: #199c19;
+
+		/* Change yellow to orange */
+		--ck-highlight-marker-yellow: #ffa61a;
+
+		/* Make red more pinkish. */
+		--ck-highlight-pen-red: #ec3e98;
+	}
+</style>
+
+<div id="snippet-custom-highlight-colors-variables">
+		<p>
+			Here are markers with changed colors through CSS Variables:
+		</p>
+		<ul>
+			<li>the <mark class="marker-green">green one</mark></li>
+			<li>the <mark class="marker-yellow">yellow one</mark></li>
+			<li>the <mark class="pen-red">red one</mark></li>
+		</ul>
+</div>

+ 46 - 0
packages/ckeditor5-highlight/docs/_snippets/features/custom-highlight-colors-variables.js

@@ -0,0 +1,46 @@
+/**
+ * @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-colors-variables' ), {
+		toolbar: {
+			items: [
+				'headings', '|', 'bulletedList', 'numberedList', 'highlightDropdown', 'undo', 'redo'
+			],
+			viewportTopOffset: 60
+		},
+		highlight: {
+			options: [
+				{
+					model: 'greenMarker',
+					class: 'marker-green',
+					title: 'Green marker',
+					color: 'var(--ck-highlight-marker-green)',
+					type: 'marker'
+				},
+				{
+					model: 'yellowMarker',
+					class: 'marker-yellow',
+					title: 'Yellow marker',
+					color: 'var(--ck-highlight-marker-yellow)',
+					type: 'marker'
+				},
+				{
+					model: 'redPen',
+					class: 'pen-red',
+					title: 'Red pen',
+					color: 'var(--ck-highlight-pen-red)',
+					type: 'pen'
+				},
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

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

@@ -13,6 +13,8 @@ The {@link module:highlight/highlight~Highlight} feature offers a text marking t
 
 ## Configuring the highlight options
 
+### Dropdown
+
 It is possible to configure which highlight options are supported by the editor.
 You can use the {@link module:highlight/highlight~HighlightConfig#options `highlight.options`} configuration and define your own highlight styles.
 
@@ -49,6 +51,8 @@ ClassicEditor
 
 {@snippet features/custom-highlight-options}
 
+### Inline buttons
+
 Instead of using the (default) `highlightDropdown`, the feature also supports a configuration with separate buttons directly in the toolbar:
 
 ```js
@@ -68,6 +72,84 @@ ClassicEditor
 
 {@snippet features/highlight-buttons}
 
+### Custom colors
+
+#### CSS Variables
+
+The highlight feature by default is using power of [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) which are defined in the [stylesheet](https://github.com/ckeditor/ckeditor5-highlight/blob/master/src/highlight.css). Thanks to them, we can easily make customization with change of lightness, hue or completely different color.
+
+```css
+:root {
+
+	/* Make green a little darker. */
+	--ck-highlight-marker-green: #199c19;
+
+	/* Change yellow to orange */
+	--ck-highlight-marker-yellow: #ffd11d;
+
+	/* Make red more pinkish. */
+	--ck-highlight-pen-red: #ec3e98;
+}
+```
+
+{@snippet features/custom-highlight-colors-variables}
+
+#### Inline color in config
+
+There is also possibility to use inline color values like `rgb`, `hex` or `hsl` format. Firstly, you need to change values of markers and pens in {@link module:highlight/highlight~HighlightConfig#options `highlight.options`} .
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		highlight: {
+			options: [
+				{
+					model: 'greenMarker',
+					class: 'marker-green',
+					title: 'Green marker',
+					color: 'rgb(24, 201, 32)',
+					type: 'marker'
+				},
+				{
+					model: 'yellowMarker',
+					class: 'marker-yellow',
+					title: 'Yellow marker',
+					color: '#f2ee28',
+					type: 'marker'
+				},
+				{
+					model: 'redPen',
+					class: 'pen-red',
+					title: 'Red pen',
+					color: 'hsl(355, 78%, 49%)',
+					type: 'pen'
+				}
+			]
+		},
+		toolbar: [
+			'headings', '|', 'bulletedList', 'numberedList', 'highlightDropdown', 'undo', 'redo'
+		]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+Secondly you need to take care of changes in stylesheet classes due to skipping CSS Variables. You should also remember about removing inactive CSS definitions in [stylesheet](https://github.com/ckeditor/ckeditor5-highlight/blob/master/src/highlight.css) like mixins and variables.
+
+```css
+.marker-green {
+	background-color: rgb(24, 201, 32);
+}
+.marker-yellow {
+	background-color: #f2ee28;
+}
+.pen-red {
+	color: hsl(355, 78%, 49%);
+}
+```
+
+{@snippet features/custom-highlight-colors-normal}
+
 ## Installation
 
 To add this feature to your editor install the [`@ckeditor/ckeditor5-highlight`](https://www.npmjs.com/package/@ckeditor/ckeditor5-highlight) package:

+ 6 - 4
packages/ckeditor5-highlight/src/highlight.js

@@ -52,8 +52,9 @@ export default class Highlight extends Plugin {
  * @typedef {Object} module:highlight/highlight~HighlightOption
  * @property {String} title The user-readable title of the option.
  * @property {String} model The unique attribute value in the model.
- * @property {String} color The name of CSS variable used for the highlighter. It should match the `class` CSS definition.
- * The color is used in the user interface to represent the highlighter.
+ * @property {String} color The CSS var() used for the highlighter. The color is used in the user interface to represent the highlighter.
+ * It is possible to use default color format.
+ * See: {@link features/highlight#custom-colors Custom colors - Inline color in config}.
  * @property {String} class The CSS class used on the `<mark>` element in the view. It should match the `color` setting.
  * @property {'marker'|'pen'} type The type of highlighter:
  * - `'marker'` – uses the `color` as a `background-color` style,
@@ -135,8 +136,9 @@ export default class Highlight extends Plugin {
  * - `'marker'` - rendered as a `<mark>` element, styled with the `background-color`,
  * - `'pen'` - rendered as a `<mark>` element, styled with the font `color`.
  *
- * **Note**: A style sheet with CSS classes is required for the configuration to work properly.
- * The highlight feature does provide actual stylesheet with default colors.
+ * **Note**: A stylesheet with CSS classes is required for the configuration to work properly thanks to CSS Variables.
+ * The highlight feature provides actual stylesheet with default colors. It is possible to use inline color format
+ * like rgb/hex or hsl. See: {@link features/highlight#custom-colors Custom colors - Inline color in config}
  *
  * **Note**: It is recommended that the `color` value should correspond to the class in the content
  * style sheet. It represents the highlighter in the user interface of the editor.