1 | /**
|
2 | * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
|
3 | * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
|
4 | */
|
5 |
|
6 | /**
|
7 | * @module image/imagestyle
|
8 | */
|
9 |
|
10 | import { Plugin } from 'ckeditor5/src/core';
|
11 | import ImageStyleEditing from './imagestyle/imagestyleediting';
|
12 | import ImageStyleUI from './imagestyle/imagestyleui';
|
13 |
|
14 | /**
|
15 | * The image style plugin.
|
16 | *
|
17 | * For a detailed overview of the image styles feature, check the {@glink features/images/images-styles documentation}.
|
18 | *
|
19 | * This is a "glue" plugin which loads the following plugins:
|
20 | * * {@link module:image/imagestyle/imagestyleediting~ImageStyleEditing},
|
21 | * * {@link module:image/imagestyle/imagestyleui~ImageStyleUI}
|
22 | *
|
23 | * It provides a default configuration, which can be extended or overwritten.
|
24 | * Read more about the {@link module:image/image~ImageConfig#styles image styles configuration}.
|
25 | *
|
26 | * @extends module:core/plugin~Plugin
|
27 | */
|
28 | export default class ImageStyle extends Plugin {
|
29 | /**
|
30 | * @inheritDoc
|
31 | */
|
32 | static get requires() {
|
33 | return [ ImageStyleEditing, ImageStyleUI ];
|
34 | }
|
35 |
|
36 | /**
|
37 | * @inheritDoc
|
38 | */
|
39 | static get pluginName() {
|
40 | return 'ImageStyle';
|
41 | }
|
42 | }
|
43 |
|
44 | /**
|
45 | * The configuration for the {@link module:image/imagestyle~ImageStyle} plugin that should be provided
|
46 | * while creating the editor instance.
|
47 | *
|
48 | * A detailed information about the default configuration and customization can be found in
|
49 | * {@link module:image/image~ImageConfig#styles `ImageConfig#styles`}.
|
50 | *
|
51 | * @interface ImageStyleConfig
|
52 | */
|
53 |
|
54 | /**
|
55 | * A list of the image style options.
|
56 | *
|
57 | * @member {Array.<module:image/imagestyle~ImageStyleOptionDefinition>} module:image/imagestyle~ImageStyleConfig#options
|
58 | */
|
59 |
|
60 | /**
|
61 | * The {@link module:image/imagestyle `ImageStyle`} plugin requires a list of the
|
62 | * {@link module:image/imagestyle~ImageStyleConfig#options image style options} to work properly.
|
63 | * The default configuration is provided (listed below) and can be customized while creating the editor instance.
|
64 | *
|
65 | * # **Command**
|
66 | *
|
67 | * The {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand `imageStyleCommand`}
|
68 | * is configured based on the defined options,
|
69 | * so you can change the style of the selected image by executing the following command:
|
70 | *
|
71 | * editor.execute( 'imageStyle' { value: 'alignLeft' } );
|
72 | *
|
73 | * # **Buttons**
|
74 | *
|
75 | * All of the image style options provided in the configuration are registered
|
76 | * in the {@link module:ui/componentfactory~ComponentFactory UI components factory} with the "imageStyle:" prefixes and can be used
|
77 | * in the {@link module:image/image~ImageConfig#toolbar image toolbar configuration}. The buttons available by default depending
|
78 | * on the loaded plugins are listed in the next section.
|
79 | *
|
80 | * Read more about styling images in the {@glink features/images/images-styles Image styles guide}.
|
81 | *
|
82 | * # **Default options and buttons**
|
83 | *
|
84 | * If the custom configuration is not provided, the default configuration will be used depending on the loaded
|
85 | * image editing plugins.
|
86 | *
|
87 | * * If both {@link module:image/image/imageblockediting~ImageBlockEditing `ImageBlockEditing`} and
|
88 | * {@link module:image/image/imageinlineediting~ImageInlineEditing `ImageInlineEditing`} plugins are loaded
|
89 | * (which is usually the default editor configuration), the following options will be available for the toolbar
|
90 | * configuration. These options will be registered as the buttons with the "imageStyle:" prefixes.
|
91 | *
|
92 | * const imageDefaultConfig = {
|
93 | * styles: {
|
94 | * options: [
|
95 | * 'inline', 'alignLeft', 'alignRight',
|
96 | * 'alignCenter', 'alignBlockLeft', 'alignBlockRight',
|
97 | * 'block', 'side'
|
98 | * ]
|
99 | * }
|
100 | * };
|
101 | *
|
102 | * * If only the {@link module:image/image/imageblockediting~ImageBlockEditing `ImageBlockEditing`} plugin is loaded,
|
103 | * the following buttons (options) and groups will be available for the toolbar configuration.
|
104 | * These options will be registered as the buttons with the "imageStyle:" prefixes.
|
105 | *
|
106 | * const imageDefaultConfig = {
|
107 | * styles: {
|
108 | * options: [ 'block', 'side' ]
|
109 | * }
|
110 | * };
|
111 | *
|
112 | * * If only the {@link module:image/image/imageinlineediting~ImageInlineEditing `ImageInlineEditing`} plugin is loaded,
|
113 | * the following buttons (options) and groups will available for the toolbar configuration.
|
114 | * These options will be registered as the buttons with the "imageStyle:" prefixes.
|
115 | *
|
116 | * const imageDefaultConfig = {
|
117 | * styles: {
|
118 | * options: [ 'inline', 'alignLeft', 'alignRight' ]
|
119 | * }
|
120 | * };
|
121 | *
|
122 | * Read more about the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options}.
|
123 | *
|
124 | * # **Custom configuration**
|
125 | *
|
126 | * The image styles configuration can be customized in several ways:
|
127 | *
|
128 | * * Any of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options}
|
129 | * can be loaded by the reference to its name as follows:
|
130 | *
|
131 | * ClassicEditor
|
132 | * .create( editorElement, {
|
133 | * image: {
|
134 | * styles: {
|
135 | * options: [ 'alignLeft', 'alignRight' ]
|
136 | * }
|
137 | * }
|
138 | * } );
|
139 | *
|
140 | * * Each of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default image style options} can be customized,
|
141 | * e.g. to change the `icon`, `title` or CSS `className` of the style. The feature also provides several
|
142 | * {@link module:image/imagestyle/utils~DEFAULT_ICONS default icons} to choose from.
|
143 | *
|
144 | * import customIcon from 'custom-icon.svg';
|
145 | *
|
146 | * // ...
|
147 | *
|
148 | * ClassicEditor.create( editorElement, { image:
|
149 | * styles: {
|
150 | * options: {
|
151 | * // This will only customize the icon of the "block" style.
|
152 | * // Note: 'right' is one of default icons provided by the feature.
|
153 | * {
|
154 | * name: 'block',
|
155 | * icon: 'right'
|
156 | * },
|
157 | *
|
158 | * // This will customize the icon, title and CSS class of the default "side" style.
|
159 | * {
|
160 | * name: 'side',
|
161 | * icon: customIcon,
|
162 | * title: 'My side style',
|
163 | * className: 'custom-side-image'
|
164 | * }
|
165 | * }
|
166 | * }
|
167 | * } );
|
168 | *
|
169 | * * If none of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default image style options}
|
170 | * works for the integration, it is possible to define independent custom styles, too.
|
171 | *
|
172 | * See the documentation about the image style {@link module:image/imagestyle~ImageStyleOptionDefinition options}
|
173 | * to define the custom image style configuration properly.
|
174 | *
|
175 | * import redIcon from 'red-icon.svg';
|
176 | * import blueIcon from 'blue-icon.svg';
|
177 | *
|
178 | * // ...
|
179 | *
|
180 | * ClassicEditor.create( editorElement, { image:
|
181 | * styles: {
|
182 | * // A list of completely custom styling options.
|
183 | * options: [
|
184 | * {
|
185 | * name: 'regular',
|
186 | * modelElements: [ 'imageBlock', 'imageInline' ],
|
187 | * title: 'Regular image',
|
188 | * icon: 'full',
|
189 | * isDefault: true
|
190 | * }, {
|
191 | * name: 'blue',
|
192 | * modelElements: [ 'imageInline' ],
|
193 | * title: 'Blue image',
|
194 | * icon: blueIcon,
|
195 | * className: 'image-blue'
|
196 | * }, {
|
197 | * name: 'red',
|
198 | * modelElements: [ 'imageBlock' ],
|
199 | * title: 'Red image',
|
200 | * icon: redIcon,
|
201 | * className: 'image-red'
|
202 | * }
|
203 | * ]
|
204 | * }
|
205 | * } );
|
206 | *
|
207 | * @member {module:image/imagestyle~ImageStyleConfig} module:image/image~ImageConfig#styles
|
208 | */
|
209 |
|
210 | /**
|
211 | * The image styling option definition descriptor.
|
212 | *
|
213 | * This definition should be implemented in the `Image` plugin {@link module:image/image~ImageConfig#styles configuration} for:
|
214 | *
|
215 | * * customizing one of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} by providing the proper name
|
216 | * of the default style and the properties that should be overridden,
|
217 | * * or defining a completely custom styling option by providing a custom name and implementing the following properties.
|
218 | *
|
219 | * import fullSizeIcon from 'path/to/icon.svg';
|
220 | *
|
221 | * const imageStyleOptionDefinition = {
|
222 | * name: 'fullSize',
|
223 | * icon: fullSizeIcon,
|
224 | * title: 'Full size image',
|
225 | * className: 'image-full-size',
|
226 | * modelElements: [ 'imageBlock', 'imageInline' ]
|
227 | * }
|
228 | *
|
229 | * The styling option will be registered as the button under the name `'imageStyle:{name}'` in the
|
230 | * {@link module:ui/componentfactory~ComponentFactory UI components factory} (this functionality is provided by the
|
231 | * {@link module:image/imagestyle/imagestyleui~ImageStyleUI} plugin).
|
232 | *
|
233 | * @property {String} name The unique name of the styling option. It will be used to:
|
234 | *
|
235 | * * refer to one of the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} or define the custom style,
|
236 | * * store the chosen style in the model by setting the `imageStyle` attribute of the model image element,
|
237 | * * as a value of the {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand#execute `imageStyle` command},
|
238 | * * when registering a button for the style in the following manner: (`'imageStyle:{name}'`).
|
239 | *
|
240 | * @property {Boolean} [isDefault] When set, the style will be used as the default one for the model elements
|
241 | * listed in the `modelElements` property. A default style does not apply any CSS class to the view element.
|
242 | *
|
243 | * If this property is not defined, its value is inherited
|
244 | * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
|
245 | *
|
246 | * @property {String} icon One of the following to be used when creating the styles's button:
|
247 | *
|
248 | * * an SVG icon source (as an XML string),
|
249 | * * one of the keys in {@link module:image/imagestyle/utils~DEFAULT_ICONS} to use one of default icons provided by the plugin.
|
250 | *
|
251 | * If this property is not defined, its value is inherited
|
252 | * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
|
253 | *
|
254 | * @property {String} title The styles's title. Setting `title` to one of
|
255 | * {@link module:image/imagestyle/imagestyleui~ImageStyleUI#localizedDefaultStylesTitles}
|
256 | * will automatically translate it to the language of the editor.
|
257 | *
|
258 | * If this property is not defined, its value is inherited
|
259 | * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
|
260 | *
|
261 | * @property {String} [className] The CSS class used to represent the style in the view.
|
262 | * It should be used only for the non-default styles.
|
263 | *
|
264 | * If this property is not defined, its value is inherited
|
265 | * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
|
266 | *
|
267 | * @property {Array.<String>} modelElements The list of the names of the model elements that are supported by the style.
|
268 | * The possible values are:
|
269 | * * `[ 'imageBlock' ]` if the style can be applied to the image type introduced by the
|
270 | * {@link module:image/image/imageblockediting~ImageBlockEditing `ImageBlockEditing`} plugin,
|
271 | * * `[ 'imageInline' ]` if the style can be applied to the image type introduced by the
|
272 | * {@link module:image/image/imageinlineediting~ImageInlineEditing `ImageInlineEditing`} plugin,
|
273 | * * `[ 'imageInline', 'imageBlock' ]` if the style can be applied to both image types introduced by the plugins mentioned above.
|
274 | *
|
275 | * This property determines which model element names work with the style. If the model element name of the currently selected
|
276 | * image is different, upon executing the
|
277 | * {@link module:image/imagestyle/imagestylecommand~ImageStyleCommand#execute `imageStyle`} command the image type (model element name)
|
278 | * will automatically change.
|
279 | *
|
280 | * If this property is not defined, its value is inherited
|
281 | * from the {@link module:image/imagestyle/utils~DEFAULT_OPTIONS default styling options} addressed in the name property.
|
282 | *
|
283 | * @typedef {Object} module:image/imagestyle~ImageStyleOptionDefinition
|
284 | */
|