8
0

mediaembed.js 9.3 KB

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