8
0

mediaembed.js 9.4 KB

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