Add linkchecker and mediaembed enterprise docs

2016-12-14 11:19:14 +10:00
parent fecd8bac46
commit d541ac946b
7 changed files with 458 additions and 5 deletions
@@ -74,6 +74,3 @@ DEPENDENCIES
  nokogiri (= 1.6.6.4)
  octopress-minify-html (= 1.3.0)
  redcarpet (~> 3)
-
-BUNDLED WITH
-   1.13.1
@@ -401,6 +401,10 @@
  - url: "check-spelling"
    pages:
    - url: "modifying"
+  - url: "check-links-and-embed-media"
+    pages:
+    - url: "linkchecker-server"
+    - url: "mediaembed-server"
  - url: "accessibility"
  - url: "mentions"
  - url: "server"
@@ -0,0 +1,12 @@
+---
+layout: default
+title: Linkchecking and Media Embed
+description: Check hyperlinks and get embedded content from any URL.
+keywords: enterprise pricing video youtube vimeo mp3 mp4 mov movie clip film link linkchecking linkchecker mediaembed media
+---
+
+The [Linkchecker plugin]({{ site.baseurl }}/plugins/linkchecker/) and [Media Embed plugin]({{ site.baseurl }}/plugins/mediaembed/) provide link checking and conversion of a URL to an embeddable snippet of code capabilities to the editor. These are premium upgrades that are included in paid subscription plans of TinyMCE including [TinyMCE Enterprise](http://www.tinymce.com/pricing/).
+
+These plugins require an additional [server-side component]({{ site.baseurl }}/enterprise/server/) to be installed and configured.
+
+You'll also need to do some [Linkchecker server configuration]({{ site.baseurl }}/enterprise/check-links-and-embed-media/linkchecker-server/) and [Media Embed server configuration]({{ site.baseurl }}/enterprise/check-links-and-embed-media/mediaembed-server/).
@@ -0,0 +1,27 @@
+---
+layout: default
+title: Configure Linkchecker Server
+description: Configure the linkchecker server side component.
+keywords: enterprise pricing video youtube vimeo mp3 mp4 mov movie clip film link linkchecking linkchecker mediaembed media
+---
+
+Once you've got the [server-side component]({{ site.baseurl }}/enterprise/server/) installed, the *linkchecker* requires some additional configuration in your `application.conf` file. Don't forget to restart the Java application server after updating the configuration.
+
+This element configures the linkchecker service's built-in cache. When a hyperlink is checked and confirmed valid, the result is cached to save unnecessary network traffic in the future.
+
+Default settings are automatically configured, meaning these settings are optional.
+
+- `capacity` - sets the capacity of the cache. The default setting is 500.
+- `timeToLiveInSeconds` - sets the time-to-live of elements of the cache, measured in seconds. This is the maximum total amount of time that an element is allowed to remain in the cache. The default setting is 86400 seconds, which is one day.
+- `timeToIdleInSeconds` - sets the time-to-idle of elements of the cache, measured in seconds. This is the maximum amount of time that an element will remain in the cache if it is not being accessed. The default setting is 3600 seconds, which is one hour.
+
+Example:
+
+````
+ephox {
+  link-checking.cache {
+    capacity = 500
+    timeToLiveInSeconds = 86400
+    timeToIdleInSeconds = 3600
+  }
+}
@@ -0,0 +1,408 @@
+---
+layout: default
+title: Configure Media Embed Server
+description: Configure the link checking and media embedding service.
+keywords: enterprise pricing video youtube vimeo mp3 mp4 mov movie clip film link linkchecking linkchecker mediaembed media
+---
+
+Once you've got the [server-side component]({{ site.baseurl }}/enterprise/server/) installed, *mediaembed* requires some additional configuration in your `application.conf` file. Don't forget to restart the Java application server after updating the configuration.
+
+You may need to restart the Java application server for the new configuration to take effect.
+
+The *mediaembed* service allows you to choose between using your own [Iframely](https://iframely.com/) account, configuring custom oembed endpoints or using a combination of both.
+
+When you insert media into your content, the service will do the following (in order):
+
+1. Check if the URL matches any custom oembed configuration. If that fails,
+2. If Iframely is configured, query the Iframely API. If Iframely is not configured,
+3. Create a summary card.
+
+## Use your own Iframely account
+
+To use your own Iframely account, provide the following configuration items:
+
+- `enabled` - set to `true` to use Iframely. If set to `false`, you don't need to prvide the `base-url` or `api-key` configuration items.
+- `base-url` - the base URL of the Iframely API. Check their [docs](https://iframely.com/docs/iframely-api) if you're unsure.
+- `api-key` - your Iframely API key. This is provided by Iframely after setting up an account with them.
+
+Example with Iframely enabled (replace `xxx` with your Iframely API key):
+
+````
+ephox {
+  embed {
+    iframely {
+      enabled = true
+      base-url = "https://iframe.ly/api/iframely"
+      api-key = "xxx" // change this to your own Iframely API key
+    }
+  }
+}
+````
+
+Example with Iframely disabled:
+
+````
+ephox {
+  embed {
+    iframely {
+      enabled = false
+    }
+  }
+}
+````
+
+## Configure a custom endpoint
+The service can be configured to hit a specific oembed endpoint when media from a URL matching a provided pattern is inserted into your content.
+
+- `endpoint` - the URL of the oembed endpoint that should be consulted when inserting media with a URL that matches an entry in `schemes`.
+- `schemes` - a list of patterns. `*` is the only special character and matches any sequence of characters. For example, `http://www.example.com/*` matches `http://www.example.com/1` and `http://www.example.com/1/1` and any other URL that begins with `http://www.example.com`. Similarly, `http://www.example.com/*/index.html` matches `http://www.example.com/1/index.html` and `http://www.example.com/1/1/index.html` and any other URL that begins with `http://www.exampe.com/` and ends with `/index.html`.
+
+**Example note:** This configuration is provided as an example only. The `mediaembed` service converts an oembed response into an embeddable snippet of code. The content and quality of the snippet is dependent on the oembed response.
+
+Example:
+
+````
+ephox {
+  embed {
+    custom = [
+
+      # instagram
+      {
+        endpoint = "http://api.instagram.com/oembed"
+        schemes = [
+          "http://instagram.com/p/*",
+          "http://instagr.am/p/*",
+          "https://instagram.com/p/*",
+          "https://instagr.am/p/*",
+          "http://www.instagram.com/p/*",
+          "http://www.instagr.am/p/*",
+          "https://www.instagram.com/p/*",
+          "https://www.instagr.am/p/*",
+        ]
+      },
+      # http://oembed.com/ example
+      # flickr
+      {
+        endpoint = "http://www.flickr.com/services/oembed.json/"
+        schemes = [
+          "http://www.flickr.com/photos/*",
+          "https://www.flickr.com/photos/*",
+          "http://www.flickr.com/photos/*/foo/",
+          "https://www.flickr.com/photos/*/foo/",
+          "http://*.flickr.com/photos/*",
+          "https://*.flickr.com/photos/*"
+        ]
+      },
+      # a bogus endpoint with no schemes
+      {
+        endpoint = "http://bogus.com/"
+        schemes = []
+      },
+      # youtube
+      {
+        endpoint = "http://www.youtube.com/oembed"
+        schemes = [
+          "http://youtu.be/*",
+          "https://youtu.be/*",
+          "http://www.youtu.be/*",
+          "https://www.youtu.be/*",
+          "http://youtube.com/*",
+          "https://youtube.com/*",
+          "http://www.youtube.com/*",
+          "https://www.youtube.com/*",
+          "http://m.youtube.com/*",
+          "https://m.youtube.com/*"
+        ]
+      },
+      # NY Times
+      {
+        endpoint = "https://www.nytimes.com/svc/oembed/json/"
+        schemes = [
+          "http://www.nytimes.com/*",
+          "https://www.nytimes.com/*"
+        ]
+      },
+      # Daily Motion
+      {
+        endpoint = "http://www.dailymotion.com/services/oembed"
+        schemes = [
+          "http://www.dailymotion.com/video/*"
+          "https://www.dailymotion.com/video/*"
+          "http://www.dailymotion.com/embed/video/*"
+          "https://www.dailymotion.com/embed/video/*"
+        ]
+      },
+      # Soundcloud
+      {
+        endpoint = "http://soundcloud.com/oembed"
+        schemes = [
+          "http://soundcloud.com/*",
+          "https://soundcloud.com/*",
+          "http://api.soundcloud.com/tracks/*",
+          "https://api.soundcloud.com/tracks/*"
+        ]
+      },
+      # Facebook post
+      {
+        endpoint = "https://www.facebook.com/plugins/post/oembed.json/"
+        schemes = [
+          "http://*.facebook.com/permalink.php*",
+          "https://*.facebook.com/permalink.php*",
+          "http://*.facebook.com/photo.php*",
+          "https://*.facebook.com/photo.php*",
+          "http://*.facebook.com/*/photos/*",
+          "https://*.facebook.com/*/photos/*",
+          "http://*.facebook.com/*/posts/*",
+          "https://*.facebook.com/*/posts/*",
+          "http://*.facebook.com/*/activity/*",
+          "https://*.facebook.com/*/activity/*",
+          "http://*.facebook.com/notes/*",
+          "https://*.facebook.com/media/set/*"
+        ]
+      },
+      # Facebook Video
+      {
+        endpoint = "https://www.facebook.com/plugins/video/oembed.json/"
+        schemes = [
+          "http://www.facebook.com/video*",
+          "https://www.facebook.com/video*",
+          "http://www.facebook.com/*/videos/*",
+          "https://www.facebook.com/*/videos/*",
+          "http://business.facebook.com/video*",
+          "https://business.facebook.com/video*",
+          "http://business.facebook.com/*/videos/*",
+          "https://business.facebook.com/*/videos/*"
+        ]
+      },
+      # Facebook Page
+      {
+        endpoint = "https://www.facebook.com/plugins/page/oembed.json/"
+        schemes = [
+          "http://www.facebook.com/*",
+          "https://www.facebook.com/*",
+          "http://m.facebook.com/*",
+          "https://m.facebook.com/*"
+        ]
+      },
+      # Spotify
+      {
+        endpoint = "https://embed.spotify.com/oembed/"
+        schemes = [
+          "http://spotify.com/*",
+          "https://spotify.com/*",
+          "http://open.spotify.com/*",
+          "https://open.spotify.com/*",
+          "http://embed.spotify.com/*",
+          "https://embed.spotify.com/*",
+          "http://play.spotify.com/*",
+          "https://play.spotify.com/*"
+        ]
+      },
+      # Vine
+      {
+        endpoint = "https://vine.co/oembed.json"
+        schemes = [
+          "http://vine.co/v/*",
+          "https://vine.co/v/*"
+        ]
+      },
+      # Hulu
+      {
+        endpoint = "http://www.hulu.com/api/oembed.json",
+        schemes = [
+          "http://www.hulu.com/watch/*",
+          "https://www.hulu.com/watch/*"
+        ]
+      },
+      # Vimeo
+      {
+        endpoint = "http://vimeo.com/api/oembed.json",
+        schemes = [
+          "http://vimeo.com/*",
+          "https://vimeo.com/*",
+          "http://www.vimeo.com/*",
+          "https://www.vimeo.com/*"
+        ]
+      },
+      # CollegeHumor
+      {
+        endpoint = "http://www.collegehumor.com/oembed.json"
+        schemes = [
+          "http://www.collegehumor.com/video/*",
+          "https://www.collegehumor.com/video/*"
+        ]
+      },
+      # SmugMug
+      {
+        endpoint = "http://api.smugmug.com/services/oembed/"
+        schemes = [
+          "http://*.smugmug.com/*",
+          "https://*.smugmug.com/*"
+        ]
+      },
+      # Slideshare
+      {
+        endpoint = "http://www.slideshare.net/api/oembed/2"
+        schemes = [
+          "http://*.slideshare.net/*"
+        ]
+      },
+      # Twitter timelines
+      {
+        endpoint = "https://publish.twitter.com/oembed?i=timeline"
+        schemes = [
+          "http://twitter.com/*/timelines/*",
+          "https://twitter.com/*/timelines/*",
+          "http://twitter.com/*/lists/*",
+          "https://twitter.com/*/lists/*",
+          "http://twitter.com/*/likes",
+          "https://twitter.com/*/likes"
+        ]
+      },
+      # Twitter Users
+      {
+        endpoint = "https://publish.twitter.com/oembed?i=user"
+        schemes = [
+          "http://twitter.com/*",
+          "https://twitter.com/*"
+        ]
+      },
+      # Getty Images
+      {
+        endpoint = "http://embed.gettyimages.com/oembed"
+        schemes = [
+          "http://gty.im/*",
+          "https://gty.im/*"
+        ]
+      },
+      # Wordpress
+      {
+        endpoint = "http://public-api.wordpress.com/oembed/1.0/?for=ephox"
+        schemes = [
+          "http://*.wordpress.com/*",
+          "https://*.wordpress.com/*"
+        ]
+      },
+      # Twitch
+      {
+        endpoint = "https://api.twitch.tv/v4/oembed"
+        schemes = [
+          "http://www.twitch.tv/*",
+          "https://www.twitch.tv/*"
+        ]
+      },
+      # Meetup
+      {
+        endpoint = "https://api.meetup.com/oembed"
+        schemes = [
+          "http://www.meetup.com/*",
+          "https://www.meetup.com/*",
+          "http://meetup.com/*",
+          "https://meetup.com/*",
+          "http://meetu.ps/*",
+          "https://meetu.ps/*"
+        ]
+      },
+      # Spotify
+      {
+        endpoint = "https://embed.spotify.com/oembed/"
+        schemes = [
+          "http://open.spotify.com/*",
+          "https://open.spotify.com/*",
+          "http://play.spotify.com/*",
+          "https://play.spotify.com/*"
+        ]
+      },
+      # Tech crunch
+      {
+        endpoint = "http://public-api.wordpress.com/oembed/1.0/?for=ephox"
+        schemes = [
+          "http://techcrunch.com/*",
+          "https://techcrunch.com/*"
+        ]
+      },
+      # Dotsub
+      {
+        endpoint = "https://dotsub.com/services/oembed"
+        schemes = [
+          "http://dotsub.com/view/*",
+          "https://dotsub.com/view/*"
+        ]
+      },
+      # Speaker deck
+      {
+        endpoint = "https://speakerdeck.com/oembed.json"
+        schemes = [
+          "http://speakerdeck.com/*/*",
+          "https://speakerdeck.com/*/*"
+        ]
+      },
+      # Tumblr
+      {
+        endpoint = "https://www.tumblr.com/oembed/1.0"
+        schemes = [
+          "http://*.tumblr.com/post/*",
+          "https://*.tumblr.com/post/*"
+        ]
+      },
+      # Adobe Stock
+      {
+        endpoint = "https://stock.adobe.com/oembed"
+        schemes = [
+          "http://stock.adobe.com/*",
+          "https://stock.adobe.com/*"
+        ]
+      },
+      # Code pen
+      {
+        endpoint = "https://codepen.io/api/oembed"
+        schemes = [
+          "http://codepen.io/*/pen/*",
+          "https://codepen.io/*/pen/*"
+        ]
+      },
+      # 500px
+      {
+        endpoint = "https://500px.com/oembed"
+        schemes = [
+          "http://500px.com/photo/*",
+          "https://500px.com/photo/*"
+        ]
+      }
+    ]
+  }
+}
+````
+
+## Combining Iframely and custom endpoints
+It is also possible to configure Iframely with custom oembed endpoints. For example, you may want to use Iframely to embed media from the Internet and an internal oembed server to embed media from an Intranet.
+
+
+Example (replace `xxx` with your Iframely API key):
+
+````
+ephox {
+  embed {
+    iframely {
+      enabled = true
+      base-url = "https://iframe.ly/api/iframely"
+      api-key = "xxx" // change this to your own Iframely API key
+    },
+
+    custom = [
+      {
+        endpoint = "http://localhost:3000/oembed"
+        schemes = [
+          "http://intranet.example.com/*"
+        ]
+      }
+    ]
+  }
+}
+````
+
+## Summary cards
+
+If neither Iframely or an oembed endpoint is configured for a given URL, a summary card will be created.
+
+A summary card is an embeddable snippet of code which is generated based on what the `mediaembed` service can work out about the content at the URL. The quality of a summary card is greatly enhanced by the presence of [OpenGraph](http://ogp.me/) metadata in the content.
@@ -16,6 +16,7 @@ The following server-side components are packaged with the TinyMCE SDK:
 |:-----------------------------	|:-------						|:----------- |
 | [Spellchecking]({{ site.baseurl }}/enterprise/check-spelling/) 				| ephox-spelling.war		|Spell checking service for TinyMCE Enterprise.|
 | [Image Tools Proxy]({{ site.baseurl }}/plugins/imagetools/)				| ephox-image-proxy.war		|Image proxy service for the Image Tools plugin.|
+| [Linkchecker and Media Embed]({{ site.baseurl }}/enterprise/check-links-and-embed-media/)				| ephox-hyperlinking.war		|Linkchecker and Media Embed service for TinyMCE Enterprise.|

 > **Note:** The "Allowed Origins" service (ephox-allowed-origins.war) has been deprecated. Trusted domains can now simply be specified via `application.conf`, as documented below.

@@ -46,6 +47,7 @@ You’ll need to ensure you deploy the following WAR files packaged with the Tin

 - ephox-spelling.war
 - ephox-image-proxy.war
+- ephox-link-checker.war

 The easiest way to deploy these files is to simply drag and drop them into the webapps directory of your Tomcat/Jetty server (or equivalent folder of another Java application server), and then restart the server.

@@ -196,6 +198,7 @@ With the above steps completed you can now direct TinyMCE instances to use Enter

 - Set the TinyMCE `spellchecker_rpc_url` configuration property to the URL of the deployed server side spelling component.
 - Set the TinyMCE `imagetools_proxy` configuration property to the URL of the deployed server-side image proxy component.
+- Set the TinyMCE `mediaembed_service_url` and `linkchecker_service_url` configuration properties to the URL of the deployed server-side linkchecker and media embed component.

 Example of TinyMCE client configuration:

@@ -203,9 +206,11 @@ Example of TinyMCE client configuration:
 tinymce.init({
 	selector: 'textarea', // change this value according to your HTML
 	toolbar: 'image',
-	plugins: 'tinymcespellchecker image imagetools',
+	plugins: 'tinymcespellchecker image imagetools media mediaembed',
 	spellchecker_rpc_url: 'http://yourspelling.server.com/ephox-spelling/',
 	imagetools_proxy: 'http://yourproxy.server.com/ephox-image-proxy/image',
+	mediaembed_service_url: 'http://yourlinkchecker.server.com/ephox-link-checker/',
+	linkchecker_service_url: 'http://yourlinkchecker.server.com/ephox-link-checker/'
 });
 ````

@@ -17,7 +17,7 @@ If a service does not appear to be working, this is generally caused by one of t

 1. The `application.conf` file is incorrect. Please go back and follow the steps listed in the [installation guide]({{ site.baseurl }}/enterprise/server/#step3createaconfigurationfile). This is the most common problem - often the origins are specified without the port numbers and this can cause things to fail, eg: use `http://localhost:8080` instead of `http://localhost`. After making changes to the `application.conf` file, please restart your Java web server (e.g. Jetty or Tomcat).
 2. The `application.conf` file is correct, but something is wrong with one of the services. See the section below to debug the services.
-3. The `application.conf` file is correct, and the services are working, but the server-side component URLs that the editor uses are not quite right. Refer to the [Spell Checker Pro]({{ site.baseurl }}/plugins/tinymcespellchecker/) and [Image Tools]({{ site.baseurl }}/plugins/imagetools/) plugin pages for help.
+3. The `application.conf` file is correct, and the services are working, but the server-side component URLs that the editor uses are not quite right. Refer to the [Spell Checker Pro]({{ site.baseurl }}/plugins/tinymcespellchecker/), [Image Tools]({{ site.baseurl }}/plugins/imagetools/), [Media Embed]({{ site.baseurl }}/plugins/mediaembed/) and [Linkchecker]({{ site.baseurl }}/plugins/linkchecker) plugin pages for help.
 4. The browser is sending a different origin than expected (and configured in `application.conf`). Refer to step 6 of [Using browser tooling to investigate services issues]({{ site.baseurl }}/enterprise/server/troubleshoot/#usingbrowsertoolingtoinvestigateservicesissues)

 ## Browser-specific issues