Procházet zdrojové kódy

Docs: Extended the media-embed guide.

Aleksander Nowodzinski před 7 roky
rodič
revize
d5aa9bad82

+ 191 - 4
packages/ckeditor5-media-embed/docs/features/media-embed.md

@@ -26,7 +26,7 @@ To add this feature to your editor, install the [`@ckeditor/ckeditor5-media-embe
 npm install --save @ckeditor/ckeditor5-media-embed
 ```
 
-Then add `'MediaEmbed'` to your plugin list and configure the media providers:
+Then add `'MediaEmbed'` to your plugin list and {@link module:media-embed/mediaembed~MediaEmbedConfig configure} the feature:
 
 ```js
 import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/table';
@@ -47,9 +47,9 @@ ClassicEditor
 
 ### Output type
 
-To satisfy most of the use–cases, the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `semanticDataOutput`} option to output different kind data:
+The data output format of the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`}:
 
-* **Non–semantic** (default) – outputs media in the same way it works in the editor, i.e. the media preview is saved to the database.
+* **Non–semantic** (when `false`, default) – outputs media in the same way it works in the editor, i.e. the media preview is saved to the database.
 
    ```html
    <figure class="media">
@@ -59,7 +59,7 @@ To satisfy most of the use–cases, the feature can be configured using the {@li
    </figure>
    ```
 
-* **Semantic** – 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.
+* **Semantic** (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.
 
    ```html
    <figure class="media">
@@ -67,8 +67,195 @@ To satisfy most of the use–cases, the feature can be configured using the {@li
    </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.
+</info-box>
+
 ### Media providers
 
+CKEditor comes with several supported media providers which can be extended or altered.
+
+Names of providers **with previews**:
+
+* `'dailymotion'`,
+* `'spotify'`,
+* `'youtube'`,
+* `'vimeo'`
+
+Names of providers **without previews**:
+
+* `'instagram'`,
+* `'twitter'`,
+* `'google'`,
+* `'flickr'`,
+* `'facebook'`
+
+<info-box notice>
+	The default media provider configuration may not support all possible media URLs, only the most common are included.
+</info-box>
+
+#### 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, ... ],
+		mediaEmbed: {
+			providers: [
+				{
+					 name: 'myProvider',
+					 url: /^(https:\/\/)?(www\.)?example\.com\/media\/(\w+)/,
+					 html: mediaId => '...'
+				},
+				...
+			]
+		}
+	} )
+	.then( ... )
+	.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`}.
+
+## Using media in the front–end
+
+### Iframely
+
+[Iframely](https://iframely.com) offers the [embed.js](https://iframely.com/docs/embedjs) library which converts [various media](https://iframely.com/docs/providers) URLs into rich previews. It works in the front–end and remains fully compatible with the output produced by CKEditor.
+
+First, having [secured the API key](https://iframely.com/docs/allow-origins), load the `embed.js` library from the CDN into your website:
+
+```html
+<head>
+	...
+	<script charset="utf-8" src="//cdn.iframe.ly/embed.js?api_key={API KEY}"></script>
+	...
+</head>
+```
+
+#### Semantic data
+
+You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput semantic media} like the following Twitter post produced by CKEditor
+
+```html
+<figure class="media">
+	<oembed url="https://twitter.com/ckeditor/status/1021777799844126720"></oembed>
+</figure>
+```
+
+using this short code snippet
+
+```html
+<script>
+	document.querySelectorAll( 'oembed[url]' ).forEach( element => {
+		iframely.load( element, element.attributes.url.value ) ;
+	} );
+</script>
+```
+
+#### Non–semantic data
+
+Despite including the media preview, the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput non–semantic} data like the following one
+
+```html
+<figure class="media">
+	<div data-oembed-url="https://twitter.com/ckeditor/status/1021777799844126720">
+		[Media preview]
+	</div>
+</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()`:
+
+```html
+<script>
+	document.querySelectorAll( 'div[data-oembed-url]' ).forEach( element => {
+		// Discard the static media preview from the database (empty the <div data-oembed-url="...">).
+		while ( element.firstChild ) {
+			element.removeChild( element.firstChild );
+		}
+
+		// Generate the media preview using Iframely.
+		iframely.load( element, element.dataset.oembedUrl ) ;
+	} );
+</script>
+```
+
+### Embedly
+
+Just like Iframely, [Embedly](https://embed.ly) offers the client–side API which converts media URLs into rich previews.
+
+To start using it, load the library from the CDN into your website:
+
+```html
+<head>
+	...
+	<script async charset="utf-8" src="//cdn.embedly.com/widgets/platform.js"></script>
+	...
+</head>
+```
+
+#### Semantic data
+
+You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput semantic media} like the following Twitter post produced by CKEditor
+
+```html
+<figure class="media">
+	<oembed url="https://twitter.com/ckeditor/status/1021777799844126720"></oembed>
+</figure>
+```
+
+using this code snippet
+
+```html
+<script>
+	document.querySelectorAll( 'oembed[url]' ).forEach( element => {
+		// Create the <a href="..." class="embedly-card"></a> element that Embedly uses
+		// to discover the media.
+		const anchor = document.createElement( 'a' );
+
+		anchor.setAttribute( 'href', element.getAttribute( 'url ') );
+		anchor.className = 'embedly-card';
+
+		element.appendChild( anchor );
+	} );
+</script>
+```
+
+Embedly discovers links like `<a href="..." class="embedly-card"></a>` and replaces them with rich media previews.
+
+#### 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:
+
+```html
+<script>
+	document.querySelectorAll( 'div[data-oembed-url]' ).forEach( element => {
+		// Discard the static media preview from the database (empty the <div data-oembed-url="...">).
+		while ( element.firstChild ) {
+			element.removeChild( element.firstChild );
+		}
+
+		// Create the <a href="..." class="embedly-card"></a> element that Embedly uses
+		// to discover the media.
+		const anchor = document.createElement( 'a' );
+
+		anchor.setAttribute( 'href', element.dataset.oembedUrl );
+		anchor.className = 'embedly-card';
+
+		element.appendChild( anchor );
+	} );
+</script>
+```
+
 ## Common API
 
 The {@link module:media-embed/mediaembed~MediaEmbed} plugin registers:

+ 2 - 0
packages/ckeditor5-media-embed/src/mediaembed.js

@@ -158,6 +158,7 @@ export default class MediaEmbed extends Plugin {
  *
  *		ClassicEditor
  *			.create( editorElement, {
+ *				plugins: [ MediaEmbed, ... ],
  *				mediaEmbed: {
  *					providers: [
  *						{
@@ -187,6 +188,7 @@ export default class MediaEmbed extends Plugin {
  *
  *		ClassicEditor
  *			.create( editorElement, {
+ *				plugins: [ MediaEmbed, ... ],
  *				mediaEmbed: {
  *					extraProviders: [
  *						{