瀏覽代碼

Docs: Aligned feature documentation to the config.mediaEmbed.mediaPreviewsInData.

Aleksander Nowodzinski 7 年之前
父節點
當前提交
2cf8269230

+ 0 - 3
packages/ckeditor5-media-embed/docs/_snippets/features/media-embed.js

@@ -15,9 +15,6 @@ ClassicEditor
 				'mediaEmbed', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
 			],
 			viewportTopOffset: 60
-		},
-		mediaEmbed: {
-			semanticDataOutput: true
 		}
 	} )
 	.then( editor => {

+ 17 - 17
packages/ckeditor5-media-embed/docs/features/media-embed.md

@@ -49,35 +49,37 @@ ClassicEditor
 
 ## Configuration
 
-### Output type
+### Data output format
 
-The data output format of the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`} option.
+The data output format of the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#mediaPreviewsInData `config.mediaEmbed.mediaPreviewsInData`} option (see below).
 
-#### Non–semantic output
+<info-box info>
+	This option does not change how media are displayed inside the editor – the previewable ones will still be displayed with previews.
+</info-box>
 
-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:
+#### Semantic data output (default)
+
+By default, the media embed feature outputs semantic `<oembed>` tags for previewable and non-previewable media. That being so, it 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">
-	<div data-oembed-url="https://media-url">
-		<iframe src="https://media-preview-url"></iframe>
-	</div>
+	<oembed url="https://media-url"></oembed>
 </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 retrieving this code from an external oEmbed service. Therefore, for non previewable media it produces the semantic output:
+#### Including previews in data
+
+Optionally, by setting `mediaEmbed.mediaPreviewsInData` to `true` you can configure the media embed feature to output media in the same way they look in the editor, this is, if this media is "previewable", the media preview (HTML) is saved to the database:
 
 ```html
 <figure class="media">
-	<oembed url="https://media-url"></oembed>
+	<div data-oembed-url="https://media-url">
+		<iframe src="https://media-preview-url"></iframe>
+	</div>
 </figure>
 ```
 
-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).
-
-#### 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:
+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 retrieving this code from an external oEmbed service. Therefore, for non previewable media it produces the default semantic output:
 
 ```html
 <figure class="media">
@@ -85,9 +87,7 @@ Optionally, by setting `mediaEmbed.semanticDataOutput` to `true` you can configu
 </figure>
 ```
 
-<info-box info>
-	This option does not change how media are displayed inside the editor – the previewable ones will still be displayed with previews.
-</info-box>
+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).
 
 ### Media providers
 

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

@@ -100,8 +100,8 @@ export default class MediaEmbed extends Plugin {
  * preview of a media identified by a certain id or a hash. When not defined, the media embed feature
  * will use a generic media representation in the view and output data.
  * Note that when
- * {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`}
- * is `true`, the rendering function **will not** be used for the media in the editor data output.
+ * {@link module:media-embed/mediaembed~MediaEmbedConfig#mediaPreviewsInData `config.mediaEmbed.mediaPreviewsInData`}
+ * is `true`, the rendering function **will always** be used for the media in the editor data output.
  */
 
 /**
@@ -153,7 +153,7 @@ export default class MediaEmbed extends Plugin {
  * only the most common are included.
  *
  * **Note**: Media without are always represented in the data using the "semantic" markup. See
- * {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`} to
+ * {@link module:media-embed/mediaembed~MediaEmbedConfig#mediaPreviewsInData `config.mediaEmbed.mediaPreviewsInData`} to
  * learn more about possible data outputs.
  *
  * **Note:**: The priority of media providers corresponds to the order of configuration. The first provider
@@ -230,14 +230,14 @@ export default class MediaEmbed extends Plugin {
 /**
  * Controls the data format produced by the feature.
  *
- * When `true`, the feature produces "semantic" data, i.e. it does not include the preview of
+ * When `false` (default), the feature produces "semantic" data, i.e. it does not include the preview of
  * the media, just the `<oembed>` tag with the `url` attribute:
  *
  *		<figure class="media">
  *			<oembed url="https://url"></oembed>
  *		</figure>
  *
- * when `false` (default), the media is represented in the output in the same way it looks in the editor,
+ * When `true`, the media is represented in the output in the same way it looks in the editor,
  * i.e. the media preview is saved to the database:
  *
  *		<figure class="media">
@@ -247,9 +247,9 @@ export default class MediaEmbed extends Plugin {
  *		</figure>
  *
  * **Note:** Preview–less media are always represented in the data using the "semantic" markup
- * regardless of the value of the `semanticDataOutput`. Learn more about different kinds of media
+ * regardless of the value of the `mediaPreviewsInData`. Learn more about different kinds of media
  * in the {@link module:media-embed/mediaembed~MediaEmbedConfig#providers `config.mediaEmbed.providers`}
  * configuration description.
  *
- * @member {Boolean} [module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput=false]
+ * @member {Boolean} [module:media-embed/mediaembed~MediaEmbedConfig#mediaPreviewsInData=false]
  */