8
0

mediaembed.js 9.4 KB

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