T/1: The basic media embed feature

.travis.yml

@@ -1,7 +1,7 @@
 sudo: required
 dist: trusty
 addons:
-  firefox: latest
+  firefox: "latest"
   apt:
     sources:
     - google-chrome

docs/_snippets/features/build-media-source.js

@@ -0,0 +1,13 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals window */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/mediaembed';
+
+ClassicEditor.builtinPlugins.push( MediaEmbed );
+
+window.ClassicEditor = ClassicEditor;

docs/_snippets/features/media-embed.html

@@ -0,0 +1,36 @@
+<div id="snippet-media-embed">
+	<h3>YouTube</h3>
+
+	<figure class="media">
+		<oembed url="https://www.youtube.com/watch?v=DgM5DfAPQTI"></oembed>
+	</figure>
+
+	<h3>Vimeo</h3>
+
+	<figure class="media">
+		<oembed url="https://vimeo.com/1084537"></oembed>
+	</figure>
+
+	<h3>Twitter</h3>
+
+	<figure>
+		<oembed url="https://twitter.com/ckeditor/status/1027571541989572612"></oembed>
+	</figure>
+
+	<h3>Google Maps</h3>
+
+	<figure class="media">
+		<oembed url="https://www.google.com/maps/place/Poland/@51.9537505,19.1343786,6z/data=!3m1!4b1!4m5!3m4!1s0x47009964a4640bbb:0x97573ca49cc55ea!8m2!3d51.919438!4d19.145136?hl=en"></oembed>
+	</figure>
+</div>
+
+<style>
+	.ck.ck-content .media iframe {
+		/* Override default Umberto guide styles. */
+		margin: 0;
+	}
+
+	input.example-input {
+		min-width: 600px;
+	}
+</style>

docs/_snippets/features/media-embed.js

@@ -0,0 +1,28 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-media-embed' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'mediaEmbed', '|', 'heading', '|', 'bold', 'italic', '|', 'undo', 'redo'
+			],
+			viewportTopOffset: 60
+		},
+		mediaEmbed: {
+			semanticDataOutput: true
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

docs/features/media-embed.md

@@ -0,0 +1,86 @@
+---
+category: features
+---
+
+{@snippet features/build-media-source}
+
+# Media embed
+
+The {@link module:media-embed/mediaembed~MediaEmbed} feature brings a basic support for embeddable, synchronous media in the editor content.
+
+## Demo
+
+### Example URLs
+
+* <input class="example-input" type="text" value="https://www.youtube.com/watch?v=H08tGjXNHO4">
+* <input class="example-input" type="text" value="https://open.spotify.com/album/2IXlgvecaDqOeF3viUZnPI?si=ogVw7KlcQAGZKK4Jz9QzvA">
+* <input class="example-input" type="text" value="https://www.instagram.com/p/BmMZgokAGGQ/?taken-by=nasa">
+
+{@snippet features/media-embed}
+
+## Installation
+
+To add this feature to your editor, install the [`@ckeditor/ckeditor5-media-embed`](https://www.npmjs.com/package/@ckeditor/ckeditor5-media-embed) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-media-embed
+```
+
+Then add `'MediaEmbed'` to your plugin list and configure the media providers:
+
+```js
+import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/table';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ MediaEmbed, ... ],
+		toolbar: [ 'mediaEmbed', ... ]
+		mediaEmbed: {
+			...
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+## Configuration
+
+### 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:
+
+* **Non–semantic** (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">
+   	<div data-oembed-url="https://url">
+   		<iframe src="https://preview"></iframe>
+   	</div>
+   </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.
+
+   ```html
+   <figure class="media">
+   	<oembed url="https://url"></oembed>
+   </figure>
+   ```
+
+### Media providers
+
+## Common API
+
+The {@link module:media-embed/mediaembed~MediaEmbed} plugin registers:
+* the `'mediaEmbed'` UI button component,
+* the `'mediaEmbed'` command implemented by {@link module:media-embed/mediaembedcommand~MediaEmbedCommand}.
+
+	You can insert a new media or update the selected media URL by executing the following code:
+
+	```js
+	editor.execute( 'mediaEmbed', { url: 'http://url.to.the/media' } );
+	```
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-media-embed.

package.json

@@ -9,8 +9,14 @@
     "ckeditor5-feature"
   ],
   "dependencies": {
+    "@ckeditor/ckeditor5-core": "^11.0.0",
+    "@ckeditor/ckeditor5-engine": "^10.2.0",
+    "@ckeditor/ckeditor5-ui": "^11.0.0",
+    "@ckeditor/ckeditor5-utils": "^10.2.0",
+    "@ckeditor/ckeditor5-widget": "^10.2.0"
   },
   "devDependencies": {
+    "@ckeditor/ckeditor5-editor-classic": "^11.0.0",
     "eslint": "^4.15.0",
     "eslint-config-ckeditor5": "^1.0.7",
     "husky": "^0.14.3",

src/converters.js

@@ -0,0 +1,66 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * @module media-embed/converters
+ */
+
+import ViewRange from '@ckeditor/ckeditor5-engine/src/view/range';
+import ViewPosition from '@ckeditor/ckeditor5-engine/src/view/position';
+
+/**
+ * Returns a function that converts the model "url" attribute to the view representation.
+ *
+ * Depending on the configuration the view representation can be "sementaic" (for data pipeline):
+ *
+ *		<figure class="media">
+ *			<oembed url="foo"></div>
+ *		</figure>
+ *
+ * or "non-semantic" (for editing view pipeline):
+ *
+ *		<figure class="media">
+ *			<div data-oembed-url="foo">[ non-semantic media preview for "foo" ]</div>
+ *		</figure>
+ *
+ * **Note:** Changing the model "url" attribute replaces the entire content of the
+ * `<figure>` in the view.
+ *
+ * @param {module:media-embed/mediaregistry~MediaRegistry} mediaRegistry The registry providing
+ * the media and their content.
+ * @param {Object} options
+ * @param {String} [options.semanticDataOutput] When `true`, the converter will create view in the semantic form.
+ * @param {String} [options.renderForEditingView] When `true`, the converter will create a view specific for the
+ * editing pipeline (e.g. including CSS classes, content placeholders).
+ * @returns {Function}
+ */
+export function modelToViewUrlAttributeConverter( mediaRegistry, options ) {
+	const mediaViewElementOptions = {
+		useSemanticWrapper: options.semanticDataOutput,
+		renderContent: !options.semanticDataOutput,
+		renderForEditingView: options.renderForEditingView
+	};
+
+	return dispatcher => {
+		dispatcher.on( 'attribute:url:media', converter );
+	};
+
+	function converter( evt, data, conversionApi ) {
+		if ( !conversionApi.consumable.consume( data.item, evt.name ) ) {
+			return;
+		}
+
+		const url = data.attributeNewValue;
+		const viewWriter = conversionApi.writer;
+		const figure = conversionApi.mapper.toViewElement( data.item );
+
+		// TODO: removing it and creating it from scratch is a hack. We can do better than that.
+		viewWriter.remove( ViewRange.createIn( figure ) );
+
+		const mediaViewElement = mediaRegistry.getMediaViewElement( viewWriter, url, mediaViewElementOptions );
+
+		viewWriter.insert( ViewPosition.createAt( figure ), mediaViewElement );
+	}
+}