|
| 1 | +--- |
| 2 | +title: Highlight |
| 3 | +category: features |
| 4 | +--- |
| 5 | + |
| 6 | +{@snippet features/build-highlight-source} |
| 7 | + |
| 8 | +The {@link module:highlight/highlight~Highlight} feature offers a text marking tools that help content authors speed up their work, e.g. reviewing content or marking it for the future reference. It uses inline `<marker>` elements in the view, supports both markers (background color) and pens (text color), and comes with a flexible configuration. |
| 9 | + |
| 10 | +## Demo |
| 11 | + |
| 12 | +{@snippet features/highlight} |
| 13 | + |
| 14 | +## Configuring the highlight options |
| 15 | + |
| 16 | +It is possible to configure which highlight options are supported by the editor. |
| 17 | +You can use the {@link module:highlight/highlight~HighlightConfig#options `highlight.options`} configuration and define your own highlight styles. |
| 18 | + |
| 19 | +For example, the following editor supports only two styles (a green marker and a red pen): |
| 20 | + |
| 21 | +```js |
| 22 | +ClassicEditor |
| 23 | + .create( document.querySelector( '#editor' ), { |
| 24 | + highlight: { |
| 25 | + options: [ |
| 26 | + { |
| 27 | + model: 'greenMarker', |
| 28 | + class: 'marker-green', |
| 29 | + title: 'Green marker', |
| 30 | + color: '#63f963', |
| 31 | + type: 'marker' |
| 32 | + }, |
| 33 | + { |
| 34 | + model: 'redPen', |
| 35 | + class: 'pen-red', |
| 36 | + title: 'Red pen', |
| 37 | + color: '#e91313', |
| 38 | + type: 'pen' |
| 39 | + } |
| 40 | + ] |
| 41 | + }, |
| 42 | + toolbar: [ |
| 43 | + 'headings', '|', 'bulletedList', 'numberedList', 'highlightDropdown', 'undo', 'redo' |
| 44 | + ] |
| 45 | + } ) |
| 46 | + .then( ... ) |
| 47 | + .catch( ... ); |
| 48 | +``` |
| 49 | + |
| 50 | +{@snippet features/custom-highlight-options} |
| 51 | + |
| 52 | +Instead of using the (default) `highlightDropdown`, the feature also supports a configuration with separate buttons directly in the toolbar: |
| 53 | + |
| 54 | +```js |
| 55 | +ClassicEditor |
| 56 | + .create( document.querySelector( '#editor' ), { |
| 57 | + toolbar: { |
| 58 | + items: [ |
| 59 | + 'headings', '|', 'highlight:marker', 'highlight:greenMarker', |
| 60 | + 'highlight:pinkMarker', 'highlight:greenPen', |
| 61 | + 'highlight:redPen', 'removeHighlight', 'undo', 'redo' |
| 62 | + ] |
| 63 | + } |
| 64 | + } ) |
| 65 | + .then( ... ) |
| 66 | + .catch( ... ); |
| 67 | +``` |
| 68 | + |
| 69 | +{@snippet features/highlight-buttons} |
| 70 | + |
| 71 | +## Installation |
| 72 | + |
| 73 | +To add this feature to your editor install the [`@ckeditor/ckeditor5-highlight`](https://www.npmjs.com/package/@ckeditor/ckeditor5-highlight) package: |
| 74 | + |
| 75 | +``` |
| 76 | +npm install --save @ckeditor/ckeditor5-highlight |
| 77 | +``` |
| 78 | + |
| 79 | +And add it to your plugin list and the toolbar configuration: |
| 80 | + |
| 81 | +```js |
| 82 | +import Highlight from '@ckeditor/ckeditor5-highlight/src/highlight'; |
| 83 | + |
| 84 | +ClassicEditor |
| 85 | + .create( document.querySelector( '#editor' ), { |
| 86 | + plugins: [ Highlight, ... ], |
| 87 | + toolbar: [ 'highlightDropdown', ... ] |
| 88 | + } ) |
| 89 | + .then( ... ) |
| 90 | + .catch( ... ); |
| 91 | +``` |
| 92 | + |
| 93 | +<info-box info> |
| 94 | + Read more about {@link builds/guides/development/installing-plugins installing plugins}. |
| 95 | +</info-box> |
| 96 | + |
| 97 | +## Common API |
| 98 | + |
| 99 | +The {@link module:highlight/highlight~Highlight} plugin registers: |
| 100 | + |
| 101 | +* The `'highlightDropdown'` dropdown, |
| 102 | +* The {@link module:highlight/highlightcommand~HighlightCommand `'highlight'`} command. |
| 103 | + |
| 104 | + The number of options and their names correspond to the {@link module:highlight/highlight~HighlightConfig#options `highlight.options`} configuration option. |
| 105 | + |
| 106 | + You can change the highlight of the current selection by executing the command with a desired value: |
| 107 | + |
| 108 | + ```js |
| 109 | + editor.execute( 'highlight', { value: 'yellowMarker' } ); |
| 110 | + ``` |
| 111 | + |
| 112 | + The `value` corresponds to the `model` property in configuration object. For the default configuration: |
| 113 | + ```js |
| 114 | + highlight.options = [ |
| 115 | + { model: 'yellowMarker', class: 'marker-yellow', title: 'Yellow Marker', color: '#fdfd77', type: 'marker' }, |
| 116 | + { model: 'greenMarker', class: 'marker-green', title: 'Green marker', color: '#63f963', type: 'marker' }, |
| 117 | + { model: 'pinkMarker', class: 'marker-pink', title: 'Pink marker', color: '#fc7999', type: 'marker' }, |
| 118 | + { model: 'blueMarker', class: 'marker-blue', title: 'Blue marker', color: '#72cdfd', type: 'marker' }, |
| 119 | + { model: 'redPen', class: 'pen-red', title: 'Red pen', color: '#e91313', type: 'pen' }, |
| 120 | + { model: 'greenPen', class: 'pen-green', title: 'Green pen', color: '#118800', type: 'pen' } |
| 121 | + ] |
| 122 | + ``` |
| 123 | + |
| 124 | + the `highlight` command will accept the corresponding strings as values: |
| 125 | + - `'yellowMarker'` – available as a `'highlight:yellowMarker'` button, |
| 126 | + - `'greenMarker'` – available as a `'highlight:greenMarker'` button, |
| 127 | + - `'pinkMarker'` – available as a `'highlight:pinkMarker'` button, |
| 128 | + - `'blueMarker'` – available as a `'highlight:blueMarker'` button, |
| 129 | + - `'redPen'` – available as a `'highlight:redPen'` button, |
| 130 | + - `'greenPen'` – available as a `'highlight:greenPen'` button. |
| 131 | + |
| 132 | + passing an empty `value` will remove any `highlight` from the selection: |
| 133 | + |
| 134 | + ```js |
| 135 | + editor.execute( 'highlight' ); |
| 136 | + ``` |
| 137 | + |
| 138 | +## Contribute |
| 139 | + |
| 140 | +The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-highlight. |
0 commit comments