url-embed
A flexible ES6 class-based system that supports converting URLs into embed code.
The module provides support for many common oembed providers, as well as support for creating your own custom providers.
The Basics
This module exports the following properties:
- EmbedEngine class: given one or more urls will resolve them to corresponding markup.
- URLEmbedProvider interface: defines the basic methods that will get invoked by EmbedEngine
- OEmbedProvider interface: extends URLEmbedProvider and implements support for interacting with an oembed provider's API
- Embed class: the primary object passed through callbacks
- defaultProviderClasses: map of all default providers indexed by provider name:
- errorClasses: map of all error classes:
Example: Resolving a single embed
'use strict'; let urlEmbed = ;let EmbedEngine = urlEmbedEmbedEngine;let Embed = urlEmbedEmbed;let engine = timeoutMs: 2000 referrer: 'www.example.com';engine; let embedOptions = maxHeight: 300 let embed = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' embedOptions; // Get single embedengine;
Example: Resolving muliple embeds in parallel
'use strict'; let urlEmbed = ;let EmbedEngine = urlEmbedEmbedEngine;let Embed = urlEmbedEmbed; let engine = timeoutMs: 2000 referrer: 'www.example.com'; engine; let embedArray = 'https://www.instagram.com/p/BCA0qkon9B1/?taken-by=mtv' 'https://soundcloud.com/newyorker/listen-to-craig-raine-read-bitch' 'https://www.youtube.com/watch?v=2LO4QL_i8is' 'https://vimeo.com/156045670' 'http://soundcloud.com/forss/flickermood' 'https://www.flickr.com/photos/sas999/25092061391/in/explore-2016-02-22/' 'http://www.dailymotion.com/video/x3lwpy7_the-worst-car-in-the-history-of-the-world-top-gear-bbc_auto' 'https://www.facebook.com/facebook/videos/10153231379946729/' 'https://www.facebook.com/MTV/posts/10153553500401701' 'https://twitter.com/simpscreens/status/702025133951680512' 'http://imgur.com/gallery/KSMB2tI' 'https://play.spotify.com/track/0ivpUENLpheuPoa6VuY1ax' 'http://mtv.tumblr.com/post/139813756155/kanye-west-taking-a-kanye-rest-so-he-can-do-his' 'https://videopress.com/v/kUJmAcSf' 'http://www.example.com/foo'; // Get multiple embedsengine;
Creating Your Own URL Embed Providers
You can extend URLEmbedProvider and OEmbedProvider to make your own embed providers.
Example: Creating a new oembed provider
'use strict'; let OEmbedProvider = OEmbedProvider; {} // Name of providerSoundCloudprototypename = 'soundcloud'; // oembed API URLSoundCloudprototypeproviderURL = 'http://soundcloud.com/oembed'; // List of RegExp patterns to match provider urlsSoundCloudprototypeurlPatterns = '^https?://(www\.)?soundcloud\.com/.*'; // Format indicates the response type of the oembed APISoundCloudprototypeformat = 'json'; moduleexports = SoundCloud;
Example: Creating a custom provider
'use strict'; let urlEmbed = ;let URLEmbedProvider = urlEmbedURLEmbedProvider;let UnexpectedStatusError = urlEmbederrorClassesUnexpectedStatusError; /* * @override */ { try embeddatahtml = '<iframe src="http://www.example.com/embed/video/12345" width="512" height="288" frameborder="0"></iframe>'; this; ; catch error embeddatahtml = this; embederror = error; ; } /* * Optional custom override of function that generates error markup. * Will deliver back customized messaging for missing items and API errors * @override */ { if embederror instanceof UnexpectedStatusError if embederrorstatus == 404 return 'Embed not found for: ' + embedembedURL; else return 'Server returned an error for: ' + errorstatus + ' when resolving: ' + embedembedURL; return 'Oops. Something went wrong for: <a href="' + embedembedURL + '">' + embedembedURL + '</a>'; } CustomProviderprototypename = 'custom';CustomProviderprototypeurlPatterns = '^https?://www\.example\.com/video/.*'; moduleexports = CustomProvider;
Example: registering a provider with the EmbedEngine
'use strict' let CustomProvider = ; let engine = 'url-embed'; engine;
Other tips, tricks and feats of strength
Example: Modifying an existing provider by extending its class
'use strict'; let urlEmbed = ;let Embed = urlEmbedEmbed;let EmbedEngine = urlEmbedEmbedEngine;let engine = ; let defaultProviderClasses = urlEmbeddefaultProviderClasses;let Youtube = defaultProviderClassesYoutube; // Class level override of filterData { datahtml = 'YOLO!!!! ' + datahtml } // Test it outengine; engine; /*** Outputs:* YOLO!!!! <iframe width="459" height="344" src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed" frameborder="0" allowfullscreen></iframe>*/
Example:
- Modifying the embed code for an instance of an existing provider
- Modifying the embed code for all providers
'use strict'; let urlEmbed = ;let Embed = urlEmbedEmbed;let EmbedEngine = urlEmbedEmbedEngine;let engine = ; let defaultProviderClasses = urlEmbeddefaultProviderClasses;let Youtube = defaultProviderClassesYoutube;let provider = ; // Instance-level override of Youtube.filterData.provider { datahtml = 'YOLO!!!! ' + datahtml} engine; // Instance level override of EmbedEngine.filterDataengine { datahtml = '<hug>' + datahtml + '</hug>';} engine; engine; engine; /** Outputs:* <hug>YOLO!!!! <iframe width="459" height="344" src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed" frameborder="0" allowfullscreen></iframe></hug>* <hug><iframe src="https://embed.spotify.com/?uri=spotify:track:0ivpUENLpheuPoa6VuY1ax" width="300" height="380" frameborder="0" allowtransparency="true"></iframe></hug>*/