Piotrek Koszuliński hace 7 años
padre
commit
e735532f02

+ 74 - 44
packages/ckeditor5-media-embed/docs/features/media-embed.md

@@ -8,8 +8,6 @@ category: features
 
 The {@link module:media-embed/mediaembed~MediaEmbed} feature brings support for embeddable media (such as YouTube videos or tweets) in the editor content.
 
-Depending on configuration, it may require using services like [iframely](http://iframe.ly/) or [embed.ly](https://embed.ly/) to display content of these embedded media on your target website. Read more about [displaying embedded media](#displaying-embedded-media-on-your-website).
-
 ## Demo
 
 Example URLs:
@@ -45,36 +43,50 @@ ClassicEditor
 	.catch( ... );
 ```
 
+<info-box>
+	Depending on how you will configure this feature, you may need to use services like [Iframely](http://iframe.ly/) or [Embedly](https://embed.ly/) to display content of embedded media on your target website. Read more about [displaying embedded media](#displaying-embedded-media-on-your-website).
+</info-box>
+
 ## Configuration
 
 ### Output type
 
-The data output format of the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`}:
+The data output format of the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`} option.
 
 #### Non–semantic output
 
-TODO (when `false`, default) – outputs media in the same way it works in the editor, i.e. the media preview is saved to the database.
+By default the media embed feature outputs media in the same way it works in the editor, this is, if this media is "previewable", the media preview (HTML) is saved to the database:
 
-   ```html
-   <figure class="media">
-   	<div data-oembed-url="https://url">
-   		<iframe src="https://preview"></iframe>
-   	</div>
-   </figure>
-   ```
+```html
+<figure class="media">
+	<div data-oembed-url="https://media-url">
+		<iframe src="https://media-preview-url"></iframe>
+	</div>
+</figure>
+```
+
+Currently, the preview is only available for content providers for which CKEditor 5 can predict an `<iframe>` code – this is YouTube, Vimeo, Dailymotion, Spotify, etc. For other providers like Twitter or Instagram the editor cannot produce an `<iframe>` code and it does not, so far, allows retriving this code from an external oEmbed service. Therefore, for non previewable media it produces the semantic output:
 
-##### Semantic output
+```html
+<figure class="media">
+	<oembed url="https://media-url"></oembed>
+</figure>
+```
 
-TODO (when `true`) – does not include the preview of the media, just just the `<oembed>` tag with the `url` attribute. Best when the application processes (expands) the media on the server–side or directly in the front–end, preserving the versatile database representation.
+This means that, unless you [limited the list of providers](#media-providers) to only those which are previewable, you need to [make sure that media are displayed on your website](#displaying-embedded-media-on-your-website).
 
-   ```html
-   <figure class="media">
-   	<oembed url="https://url"></oembed>
-   </figure>
-   ```
+#### Semantic output
+
+Optionally, by setting `mediaEmbed.semanticDataOutput` to `true` you can configure the media embed feature to output semantic `<oembed>` tags for previewable and non-previewable media. This option works best when the application processes (expands) the media on the server–side or [directly in the front–end](#displaying-embedded-media-on-your-website), preserving the versatile database representation:
+
+```html
+<figure class="media">
+	<oembed url="https://media-url"></oembed>
+</figure>
+```
 
 <info-box info>
-	You can easily [expand](#using-media-in-the-frontend) the media using popular embed services in the front–end of your application regardless of the data output type you chose in your database.
+	This option does not change how media are displayed inside the editor – the previewable ones will still be displayed with previews.
 </info-box>
 
 ### Media providers
@@ -97,23 +109,49 @@ Names of providers **without previews**:
 * `'facebook'`
 
 <info-box notice>
-	The default media provider configuration may not support all possible media URLs, only the most common are included.
+	The default media provider configuration does not support all possible media URLs, only the most common are included. Services like Iframely or Embedly support thousands of media providers and it is up to you to define which you want to allow.
 </info-box>
 
+#### Extending
+
+To extend the default list of default providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}.
+
+#### Removing
+
+To remove certain providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#removeProviders `config.mediaEmbed.removeProviders`}.
+
+For instance, to leave only the previewable providers use this
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ MediaEmbed, ... ],
+		toolbar: [ 'mediaEmbed', ... ]
+		mediaEmbed: {
+			removeProviders: [ 'instagram', 'twitter', 'google', 'flickr', 'facebook' ]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
 #### Overriding
 
 To override the default providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#providers `config.mediaEmbed.providers`} and define your set according to the {@link module:media-embed/mediaembed~MediaEmbedProvider provider syntax}:
 
 ```js
 ClassicEditor
-	.create( editorElement, {
-		plugins: [ MediaEmbed, ... ],
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ MediaEmbed, ... ],,
+		toolbar: [ 'mediaEmbed', ... ]
 		mediaEmbed: {
 			providers: [
 				{
-					 name: 'myProvider',
-					 url: /^(https:\/\/)?(www\.)?example\.com\/media\/(\w+)/,
-					 html: mediaId => '...'
+					// An URL regexp or array of URL regexps:
+					url: /^(https:\/\/)?(www\.)?example\.com\/media\/(\w+)/,
+
+					// To be defined only if the media is previewable:
+					html: mediaId => '...'
 				},
 				...
 			]
@@ -123,14 +161,6 @@ ClassicEditor
 	.catch( ... );
 ```
 
-#### Extending
-
-To extend the default list of default providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}.
-
-#### Removing
-
-To remove certain providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#removeProviders `config.mediaEmbed.premoveProviders`}.
-
 ## Displaying embedded media on your website
 
 The media embed feature produces output that may not contain previews of some embedded media. That happens for all media types when the feature is configured to produce a [semantic output](#semantic-output) and for non-previewable media in the default configuration. That means that you need to transform the output `<oembed>` elements into real media on your target website.
@@ -153,7 +183,7 @@ First, having [secured the API key](https://iframely.com/docs/allow-origins), lo
 
 #### Semantic data
 
-You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput semantic media} like the following Twitter post produced by CKEditor
+You can convert all `<oembed>` elements like the following Twitter post produced by CKEditor 5:
 
 ```html
 <figure class="media">
@@ -161,19 +191,19 @@ You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semant
 </figure>
 ```
 
-using this short code snippet
+using this short code snippet:
 
 ```html
 <script>
 	document.querySelectorAll( 'oembed[url]' ).forEach( element => {
-		iframely.load( element, element.attributes.url.value ) ;
+		iframely.load( element, element.attributes.url.value );
 	} );
 </script>
 ```
 
-#### Nonsemantic data
+#### Non-semantic data
 
-Despite including the media preview, the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput non–semantic} data like the following one
+Additionally, despite the fact that the media preview is included for some media types (unless you [configured the media embed feature otherwise](#semantic-output)), you can still use Iframely for media embeds like the following one:
 
 ```html
 <figure class="media">
@@ -183,7 +213,7 @@ Despite including the media preview, the {@link module:media-embed/mediaembed~Me
 </figure>
 ```
 
-can still be converted by Iframely with just a few extra lines of code. To do that, use a slightly longer code snippet which discards the media preview saved in the database before using `iframely.load()`:
+The above data can still be converted by Iframely with just a few extra lines of code. To do that, in addition to the code snippet from the previous section, use a slightly longer code snippet which discards the media preview saved in the database before using `iframely.load()`:
 
 ```html
 <script>
@@ -215,7 +245,7 @@ To start using it, load the library from the CDN into your website:
 
 #### Semantic data
 
-You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput semantic media} like the following Twitter post produced by CKEditor
+You can convert `<oembed>` elements like the following Twitter post produced by CKEditor 5:
 
 ```html
 <figure class="media">
@@ -223,7 +253,7 @@ You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semant
 </figure>
 ```
 
-using this code snippet
+using this code snippet:
 
 ```html
 <script>
@@ -240,11 +270,11 @@ using this code snippet
 </script>
 ```
 
-Embedly discovers links like `<a href="..." class="embedly-card"></a>` and replaces them with rich media previews.
+Embedly automatically discovers links like `<a href="..." class="embedly-card"></a>` and replaces them with rich media previews.
 
-#### Nonsemantic data
+#### Non-semantic data
 
-The code is almost the same as with the semantic data but you should discard the media preview saved in the database before using embedly to avoid code duplication:
+In this case, the code is almost the same as with the semantic data but you should discard the media preview saved in the database before using Embedly to avoid code duplication:
 
 ```html
 <script>

+ 1 - 1
packages/ckeditor5-media-embed/src/mediaembed.js

@@ -175,7 +175,7 @@ export default class MediaEmbed extends Plugin {
  * {@link module:media-embed/mediaembed~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}.
  *
  * To **remove** certain providers, use
- * {@link module:media-embed/mediaembed~MediaEmbedConfig#removeProviders `config.mediaEmbed.premoveProviders`}.
+ * {@link module:media-embed/mediaembed~MediaEmbedConfig#removeProviders `config.mediaEmbed.removeProviders`}.
  *
  * @member {Array.<module:media-embed/mediaembed~MediaEmbedProvider>} module:media-embed/mediaembed~MediaEmbedConfig#providers
  */

+ 4 - 1
packages/ckeditor5-media-embed/tests/manual/mediaembed.js

@@ -14,7 +14,10 @@ ClassicEditor
 		plugins: [ ArticlePluginSet, MediaEmbed ],
 		toolbar: [
 			'heading', '|', 'mediaEmbed', '|', 'bold', 'italic', 'bulletedList', 'numberedList', 'blockQuote', 'link', 'undo', 'redo'
-		]
+		],
+		mediaEmbed: {
+			removeProviders: [ 'instagram', 'twitter', 'google', 'flickr', 'facebook' ]
+		}
 	} )
 	.then( editor => {
 		window.editor = editor;