| 1 | /**
|
| 2 | * @license Copyright (c) 2003-2024, 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 | import type { ToolbarConfigItem } from 'ckeditor5/src/core.js';
|
| 6 | import type { ArrayOrItem } from 'ckeditor5/src/utils.js';
|
| 7 | /**
|
| 8 | * @module media-embed/mediaembedconfig
|
| 9 | */
|
| 10 | /**
|
| 11 | * The configuration of the media embed features.
|
| 12 | *
|
| 13 | * Read more about {@glink features/media-embed#configuration configuring the media embed feature}.
|
| 14 | *
|
| 15 | * ```ts
|
| 16 | * ClassicEditor
|
| 17 | * .create( editorElement, {
|
| 18 | * mediaEmbed: ... // Media embed feature options.
|
| 19 | * } )
|
| 20 | * .then( ... )
|
| 21 | * .catch( ... );
|
| 22 | * ```
|
| 23 | *
|
| 24 | * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
|
| 25 | */
|
| 26 | export interface MediaEmbedConfig {
|
| 27 | /**
|
| 28 | * The default media providers supported by the editor.
|
| 29 | *
|
| 30 | * The names of providers with rendering functions (previews):
|
| 31 | *
|
| 32 | * * "dailymotion",
|
| 33 | * * "spotify",
|
| 34 | * * "youtube",
|
| 35 | * * "vimeo"
|
| 36 | *
|
| 37 | * The names of providers without rendering functions:
|
| 38 | *
|
| 39 | * * "instagram",
|
| 40 | * * "twitter",
|
| 41 | * * "googleMaps",
|
| 42 | * * "flickr",
|
| 43 | * * "facebook"
|
| 44 | *
|
| 45 | * See the {@link module:media-embed/mediaembedconfig~MediaEmbedProvider provider syntax} to learn more about
|
| 46 | * different kinds of media and media providers.
|
| 47 | *
|
| 48 | * **Note**: The default media provider configuration may not support all possible media URLs,
|
| 49 | * only the most common are included.
|
| 50 | *
|
| 51 | * Media without rendering functions are always represented in the data using the "semantic" markup. See
|
| 52 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#previewsInData `config.mediaEmbed.previewsInData`} to
|
| 53 | * learn more about possible data outputs.
|
| 54 | *
|
| 55 | * The priority of media providers corresponds to the order of configuration. The first provider
|
| 56 | * to match the URL is always used, even if there are other providers that support a particular URL.
|
| 57 | * The URL is never matched against the remaining providers.
|
| 58 | *
|
| 59 | * To discard **all** default media providers, simply override this configuration with your own
|
| 60 | * {@link module:media-embed/mediaembedconfig~MediaEmbedProvider definitions}:
|
| 61 | *
|
| 62 | * ```ts
|
| 63 | * ClassicEditor
|
| 64 | * .create( editorElement, {
|
| 65 | * plugins: [ MediaEmbed, ... ],
|
| 66 | * mediaEmbed: {
|
| 67 | * providers: [
|
| 68 | * {
|
| 69 | * name: 'myProvider',
|
| 70 | * url: /^example\.com\/media\/(\w+)/,
|
| 71 | * html: match => '...'
|
| 72 | * },
|
| 73 | * ...
|
| 74 | * ]
|
| 75 | * }
|
| 76 | * } )
|
| 77 | * .then( ... )
|
| 78 | * .catch( ... );
|
| 79 | * ```
|
| 80 | *
|
| 81 | * You can take inspiration from the default configuration of this feature which you can find in:
|
| 82 | * https://github.com/ckeditor/ckeditor5-media-embed/blob/master/src/mediaembedediting.js
|
| 83 | *
|
| 84 | * To **extend** the list of default providers, use
|
| 85 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}.
|
| 86 | *
|
| 87 | * To **remove** certain providers, use
|
| 88 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#removeProviders `config.mediaEmbed.removeProviders`}.
|
| 89 | */
|
| 90 | providers?: Array<MediaEmbedProvider>;
|
| 91 | /**
|
| 92 | * The additional media providers supported by the editor. This configuration helps extend the default
|
| 93 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#providers}.
|
| 94 | *
|
| 95 | * ```ts
|
| 96 | * ClassicEditor
|
| 97 | * .create( editorElement, {
|
| 98 | * plugins: [ MediaEmbed, ... ],
|
| 99 | * mediaEmbed: {
|
| 100 | * extraProviders: [
|
| 101 | * {
|
| 102 | * name: 'extraProvider',
|
| 103 | * url: /^example\.com\/media\/(\w+)/,
|
| 104 | * html: match => '...'
|
| 105 | * },
|
| 106 | * ...
|
| 107 | * ]
|
| 108 | * }
|
| 109 | * } )
|
| 110 | * .then( ... )
|
| 111 | * .catch( ... );
|
| 112 | * ```
|
| 113 | *
|
| 114 | * See the {@link module:media-embed/mediaembedconfig~MediaEmbedProvider provider syntax} to learn more.
|
| 115 | */
|
| 116 | extraProviders?: Array<MediaEmbedProvider>;
|
| 117 | /**
|
| 118 | * The list of media providers that should not be used despite being available in
|
| 119 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#providers `config.mediaEmbed.providers`} and
|
| 120 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}
|
| 121 | *
|
| 122 | * ```ts
|
| 123 | * mediaEmbed: {
|
| 124 | * removeProviders: [ 'youtube', 'twitter' ]
|
| 125 | * }
|
| 126 | * ```
|
| 127 | */
|
| 128 | removeProviders?: Array<string>;
|
| 129 | /**
|
| 130 | * Overrides the element name used for "semantic" data.
|
| 131 | *
|
| 132 | * This is not relevant if
|
| 133 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#previewsInData `config.mediaEmbed.previewsInData`} is set to `true`.
|
| 134 | *
|
| 135 | * When not set, the feature produces the `<oembed>` tag:
|
| 136 | *
|
| 137 | * ```html
|
| 138 | * <figure class="media">
|
| 139 | * <oembed url="https://url"></oembed>
|
| 140 | * </figure>
|
| 141 | * ```
|
| 142 | *
|
| 143 | * To override the element name with, for instance, the `o-embed` name:
|
| 144 | *
|
| 145 | * ```ts
|
| 146 | * mediaEmbed: {
|
| 147 | * elementName: 'o-embed'
|
| 148 | * }
|
| 149 | * ```
|
| 150 | *
|
| 151 | * This will produce semantic data with the `<o-embed>` tag:
|
| 152 | *
|
| 153 | * ```html
|
| 154 | * <figure class="media">
|
| 155 | * <o-embed url="https://url"></o-embed>
|
| 156 | * </figure>
|
| 157 | * ```
|
| 158 | *
|
| 159 | * @default 'oembed'
|
| 160 | */
|
| 161 | elementName?: string;
|
| 162 | /**
|
| 163 | * Controls the data format produced by the feature.
|
| 164 | *
|
| 165 | * When `false` (default), the feature produces "semantic" data, i.e. it does not include the preview of
|
| 166 | * the media, just the `<oembed>` tag with the `url` attribute:
|
| 167 | *
|
| 168 | * ```ts
|
| 169 | * <figure class="media">
|
| 170 | * <oembed url="https://url"></oembed>
|
| 171 | * </figure>
|
| 172 | * ```
|
| 173 | *
|
| 174 | * When `true`, the media is represented in the output in the same way it looks in the editor,
|
| 175 | * i.e. the media preview is saved to the database:
|
| 176 | *
|
| 177 | * ```ts
|
| 178 | * <figure class="media">
|
| 179 | * <div data-oembed-url="https://url">
|
| 180 | * <iframe src="https://preview"></iframe>
|
| 181 | * </div>
|
| 182 | * </figure>
|
| 183 | * ```
|
| 184 | *
|
| 185 | * **Note:** Media without preview are always represented in the data using the "semantic" markup
|
| 186 | * regardless of the value of the `previewsInData`. Learn more about different kinds of media
|
| 187 | * in the {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#providers `config.mediaEmbed.providers`}
|
| 188 | * configuration description.
|
| 189 | *
|
| 190 | * @defualt false
|
| 191 | */
|
| 192 | previewsInData?: boolean;
|
| 193 | /**
|
| 194 | * Items to be placed in the media embed toolbar.
|
| 195 | * This option requires adding {@link module:media-embed/mediaembedtoolbar~MediaEmbedToolbar} to the plugin list.
|
| 196 | *
|
| 197 | * Read more about configuring toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
|
| 198 | */
|
| 199 | toolbar?: Array<ToolbarConfigItem>;
|
| 200 | }
|
| 201 | /**
|
| 202 | * The media embed provider descriptor. Used in
|
| 203 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#providers `config.mediaEmbed.providers`} and
|
| 204 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}.
|
| 205 | *
|
| 206 | * See {@link module:media-embed/mediaembedconfig~MediaEmbedConfig} to learn more.
|
| 207 | *
|
| 208 | * ```ts
|
| 209 | * {
|
| 210 | * name: 'example',
|
| 211 | *
|
| 212 | * // The following RegExp matches https://www.example.com/media/{media id},
|
| 213 | * // (either with "http(s)://" and "www" or without), so the valid URLs are:
|
| 214 | * //
|
| 215 | * // * https://www.example.com/media/{media id},
|
| 216 | * // * http://www.example.com/media/{media id},
|
| 217 | * // * www.example.com/media/{media id},
|
| 218 | * // * example.com/media/{media id}
|
| 219 | * url: /^example\.com\/media\/(\w+)/,
|
| 220 | *
|
| 221 | * // The rendering function of the provider.
|
| 222 | * // Used to represent the media when editing the content (i.e. in the view)
|
| 223 | * // and also in the data output of the editor if semantic data output is disabled.
|
| 224 | * html: match => `The HTML representing the media with ID=${ match[ 1 ] }.`
|
| 225 | * }
|
| 226 | * ```
|
| 227 | *
|
| 228 | * You can allow any sort of media in the editor using the "allow–all" `RegExp`.
|
| 229 | * But mind that, since URLs are processed in the order of configuration, if one of the previous
|
| 230 | * `RegExps` matches the URL, it will have a precedence over this one.
|
| 231 | *
|
| 232 | * ```ts
|
| 233 | * {
|
| 234 | * name: 'allow-all',
|
| 235 | * url: /^.+/
|
| 236 | * }
|
| 237 | * ```
|
| 238 | *
|
| 239 | * To implement responsive media, you can use the following HTML structure:
|
| 240 | *
|
| 241 | * ```ts
|
| 242 | * {
|
| 243 | * ...
|
| 244 | * html: match =>
|
| 245 | * '<div style="position:relative; padding-bottom:100%; height:0">' +
|
| 246 | * '<iframe src="..." frameborder="0" ' +
|
| 247 | * 'style="position:absolute; width:100%; height:100%; top:0; left:0">' +
|
| 248 | * '</iframe>' +
|
| 249 | * '</div>'
|
| 250 | * }
|
| 251 | * ```
|
| 252 | */
|
| 253 | export interface MediaEmbedProvider {
|
| 254 | /**
|
| 255 | * The name of the provider. Used e.g. when
|
| 256 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#removeProviders removing providers}.
|
| 257 | */
|
| 258 | name: string;
|
| 259 | /**
|
| 260 | * The `RegExp` object (or array of objects) defining the URL of the media.
|
| 261 | * If any URL matches the `RegExp`, it becomes the media in the editor model, as defined by the provider. The result
|
| 262 | * of matching (output of `String.prototype.match()`) is passed to the `html` rendering function of the media.
|
| 263 | *
|
| 264 | * **Note:** You do not need to include the protocol (`http://`, `https://`) and `www` subdomain in your `RegExps`,
|
| 265 | * they are stripped from the URLs before matching anyway.
|
| 266 | */
|
| 267 | url: ArrayOrItem<RegExp>;
|
| 268 | /**
|
| 269 | * The rendering function of the media. The function receives the entire matching
|
| 270 | * array from the corresponding `url` `RegExp` as an argument, allowing rendering a dedicated
|
| 271 | * preview of the media identified by a certain ID or a hash. When not defined, the media embed feature
|
| 272 | * will use a generic media representation in the view and output data.
|
| 273 | * Note that when
|
| 274 | * {@link module:media-embed/mediaembedconfig~MediaEmbedConfig#previewsInData `config.mediaEmbed.previewsInData`}
|
| 275 | * is `true`, the rendering function **will always** be used for the media in the editor data output.
|
| 276 | */
|
| 277 | html?: (match: RegExpMatchArray) => string;
|
| 278 | }
|