CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Typedef

MediaEmbedProvider (media-embed)

@ckeditor/ckeditor5-media-embed/src/mediaembed

typedef
Object
See source

The media embed provider descriptor. Used in config.mediaEmbed.providers and config.mediaEmbed.extraProviders.

See MediaEmbedConfig to learn more.

{
	name: 'example',

	// The following RegExp matches https://www.example.com/media/{media id},
	// (either with "http(s)://" and "www" or without), so the valid URLs are:
	//
	// * https://www.example.com/media/{media id},
	// * http://www.example.com/media/{media id},
	// * www.example.com/media/{media id},
	// * example.com/media/{media id}
	url: /^example\.com\/media\/(\w+)/,

	// The rendering function of the provider.
	// Used to represent the media when editing the content (i.e. in the view)
	// and also in the data output of the editor if semantic data output is disabled.
	html: match => `The HTML representing the media with ID=${ match[ 1 ] }.`
}

You can allow any sort of media in the editor using the "allow–all" RegExp. But mind that, since URLs are processed in the order of configuration, if one of the previous RegExps matches the URL, it will have a precedence over this one.

{
	name: 'allow-all',
	url: /^.+/
}

To implement responsive media, you can use the following HTML structure:

{
	...
	html: match =>
		'<div style="position:relative; padding-bottom:100%; height:0">' +
			'<iframe src="..." frameborder="0" ' +
				'style="position:absolute; width:100%; height:100%; top:0; left:0">' +
			'</iframe>' +
		'</div>'
}

Filtering

Properties

  • html : function | undefined

    (optional) The rendering function of the media. The function receives the entire matching array from the corresponding url RegExp as an argument, allowing rendering a dedicated preview of the media identified by a certain ID or a hash. When not defined, the media embed feature will use a generic media representation in the view and output data. Note that when config.mediaEmbed.previewsInData is true, the rendering function will always be used for the media in the editor data output.

  • name : String

    The name of the provider. Used e.g. when removing providers.

  • url : RegExp | Array.<RegExp>

    The RegExp object (or array of objects) defining the URL of the media. If any URL matches the RegExp, it becomes the media in the editor model, as defined by the provider. The result of matching (output of String.prototype.match()) is passed to the html rendering function of the media.

    Note: You do not need to include the protocol (http://, https://) and www subdomain in your RegExps, they are stripped from the URLs before matching anyway.