mediaembed.js 8.7 KB

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