Embedly jQuery is a jQuery Library for interacting with the Embedly API.
Embedly jQuery requires jQuery 1.5 or greater as it uses Deferred Objects. For older versions of jQuery see version 2.2.2. Add jQuery and Embedly jQuery to your document.
<head> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js" type="text/javascript"></script> <script src="http://cdn.embed.ly/jquery.embedly-3.1.1.min.js" type="text/javascript"></script> </head>
You can now use jQuery selectors to replace links with embedded content:
$('#content a').embedly({key: 'Your Embedly Key'});
Or can now use the client directly:
$.embedly.extract('http://embed.ly', {key: 'Your Embedly Key'}).progress(function(data){ alert(data.title); });
Embedly requires that you pass a key with every request. To signup for a key
please visit app.embed.ly/signup. To avoid adding your
key to every $.embedly
call you can add it to the defaults
like so:
$.embedly.defaults.key = 'Your Embedly Key'; # Directly $.embedly.extract('http://embed.ly').progress(function(data){alert(data.title)}); # CSS Selector $('a').embedly();
Otherwise you must add it to every request like so:
# Directly $.embedly.extract('http://embed.ly', {key:'Your Embedly Key'}) .progress(function(data){alert(data.title)}); # CSS Selector $('a').embedly({key:'Your Embedly Key'});
For the rest of the documentation we will assume that you set up the defaults
or passing the key
directly into the call.
Use a CSS selector to replace every valid link with an embed on the page.
$('a').embedly( options ); # Replace all valid links $('a').embedly(); # Replace a subset of links $('a.oembed').embedly(); # Replace with maxWidth option set to 600px and method option set # to 'after' $('a').embedly({query: {maxwidth: 600}, 'method':'after'}); # Replace only Hulu links $('a').embedly({ query: {maxwidth: 600}, urlRe: /http:\/\/(www\.hulu\.com\/watch.*)/i, method:'after' }); # Embedly supports chaining, so you can modify your original jQuery set # after triggering Embedly $('a').embedly().css('backgroundColor','#dadada');
The Selector is excellent for inserting Embedly data into the DOM, but if you would like even more control on how you use Embedly data, then use the Client directly.
The client follows jQuery's Promise pattern. You should be familiar with the concept of Deferred Objects. before using the Client, but we will explain in a simple example here.
var deferred = $.embedly.extract(['http://embed.ly', 'http://google.com'], { key: 'xxxxxx', query: { words: 20, } }).progress(function(data){ // Called after each URL has been returned from the Embedly server. Order // is not preserved for this method, so for long lists where URLs need to // be batched the data results will likely be out of order. console.log(data.url, data.title); }).done(function(results){ // Called after the call has been completed with every data result in a // list. Order is preserved in this method regardless of batching. $.each(results, function(i, data){ console.log(data.original_url) }); }); // Deferred objs retain information, so you can register callbacks even after // the ajax call was completed. deferred.done(function(results){ // This will execute immediately if the ajax call is complete console.log('done', results.length); }); deferred.progress(function(data){ // If the call has been completed, the deferred object will only pass back // the last object that was sent to the notify function. You should // register a progress function immediately after the embedly client call // to catch all notify events. alert('last object', data.url); });
You can also pass a single URL to the client, but the done
method will
always be passed a list of results.
$.embedly.oembed('http://embed.ly').progress(function(data){ // Will only be called once in this case. console.log(data.url, data.title); }).done(function(results){ // Even though there was only one url, this will still be a list of // results. var data = results[0]; });
The client only has 4 methods
oembed
- Corresponds to Embedly's oEmbed API Endpoint. Available with Embed product.
extract
- Corresponds to Embedly's Extract API Endpoint. Available with Extract product.
preview
- Corresponds to Embedly's Preview API Endpoint. Available with Legacy plans.
objectify
- Corresponds to the Embedly's Objectify API Endpoint. Available with Legacy plans.
Embedly's API only accepts a maximum of 20 URLs per API request, because of
this the ajax
method automatically batches URLs into groups of 20. The
progress
method will still return when the data of a URL is ready and the
done
method will retain order. If you would like a smaller batch size you
can specify batch
in the options like so:
$.embedly.oembed(['http://embed.ly', ....], {batch:10}).done(function(results){ console.log(results.length); });
The data passed back by the client is a JSON Object of the data return by the Embedly API. For more information on responses see the Response documentation.
The only difference is that the oEmbed
data object contains an
original_url
attribute that is used for book keeping purposes.
key
[string:'']- You can sign up or log in as an existing user to retrieve your Embedly key. A key will allow higher usage levels and extra features, see products.
query
[Object:default object]A direct pass though to all the Query Arguments that the Embedly API accepts. These will be combined with the
key
,endpoint
and theurls
to form the request to Embedly.:query: { maxwidth: 400, maxheight: 400, chars: 200, autoplay: true ... }
For more information, read the Query Arguments documentation.
display
[Function:default function]
This method will embed the content on the page. As a convenience Embedly has a simple display function built in if you are using the
oembed
endpoint. It will create an image forphoto
types, a simple title and description embed forlink
types and directly embed the html forrich
andvideo
types.Generally you will want to overwrite this function for a more customized look and feel.
display
should accept a data object:$('a').embedly({display:function(data){ $(this).text(data.title); });
method
[String:'replace']A string value to tell Embedly how to place the content in your page when using the default display function.
- replace - replaces the link with the content
- after - inserts the content after the link
- afterParent - inserts the content after the parent element
- replaceParent - replaces parent element with the embed content
wrapElement
[String:'div']- A string value representing the valid HTML element to wrap the content in.
className
[String:'embed']- A string value representing a CSS class you would like to assign to the wrapElement.
addImageStyles
[Boolean:true]- A boolean value representing whether or not Embedly should use the style element to resize images based on the maxWidth and maxHeight parameters.
endpoint
[String:oembed]A string value that maps to our Embedly endpoints. The Preview and Objectify endpoints are only available for Legacy plans.
- oembed - a standard in 3rd party embedding, contains a finite set of attributes.
- extract - returns a wide variety of attributes (article text, images, dominant colors, keywords, related links, and embeds in page) for creating an experience with your links.
- preview - returns a larger set of attributes (multiple images, RSS content, and embeds in page) for customizing your embeds.
- objectify - returns all of the meta and API data Embedly has for a link. Advanced users.
Developers intending to use Extract, Preview, or Objectify will have to include their own
display
callback function for handling the embeds. Our defaultdisplay
callback is designed to work withoembed
only.urlRe
[RegEx:]- A regular expression representing what links to show content for. Use our generator to generate a regular expression for a specific set of sources.
secure
[Boolean:null]- By default Embedly jQuery will use
window.location.protocol
to figure out whether your request needs to be made to the HTTPS endpoint or the HTTP. You can override this by explicitly setting the secure parameter totrue
forhttps
orfalse
for HTTP. batch
[Integer:20]- Embedly's API only accepts a maximum of 20 URLs per request, so the Client batches these up into groups of 20. If you would like to set a custom size, you can do so with this argument.
progress
[Function:null]Added directly to the Deferred object and will be called when the API returns JSON data for this URL.
progress
should accept a single data object and does not contain any information about the element that is being operated on.$('a').embedly({progress:function(data){ console.log(data.type) });
done
[Function:null]Added directly to the Deferred object and will be called when every URL has been processed by the Embedly API.
done
should accept a list of data objects.$('a').embedly({done:function(data){ console.log(data.type) });
It's more than likely with user generated content that there will be a number
of invalid URLs passed to the client. If you also use a specific URLRe, you
will receive even more invalid URLs. The Client and the Selector treat these
the came and they are still passed to the progress
, done
and
display
functions. It's very easy to handle these:
$.embedly.objectify('notaurl').progress(function(data){ if (data.invalid === true){ // The URL that you passed in was not a good one. console.log(data.error, data.error_message); } else if (data.type === 'error'){ // The API passed back an error. console.log(data.type, data.error_message); } else { // Everything is good to go. Proceed Captain. } })
Starting in revision 2.0.0 we have started writing the Embedly data to the DOM elements using jQuery.data(). You can read more about the data function here, but basically saves the Embedly data on the element for retrieval later. For example:
# $('a').embedly() # ... after the AJAX returns an oembed ... $('a').data('embedly')
This call returns the embedly
object for each a tag, so you can access the
data later on. Because this data is not written to the DOM until the AJAX
requests are complete we have added a custom event listener called
displayed.
This event fires for each node when the oEmbed object is
written to the node using jQuery.data(). We did this so that developers could
continue to use our default callback function for writing embeds to the page
and still have access to the embedly
data for customization.
# version 1 $('a').embedly().bind('displayed', function(e){ var data = $(this).data('embedly'); alert(data.title); }); # version 2 $('a').embedly().bind('displayed', function(e, data){ alert(data.title); });
The event handler gets the embedly object passed in as a parameter as well if you don't want to use jQuery.data(); The two are equivalent.
It's possible to get yourself into a race condition using the embedly
data
where the using initiates an event and the data has yet to be returned. To get
around this there is a loaded
Deferred Object on the data that will resolve
when everything is ready. Here is a simple example:
$('a').embedly().on('click', function(){ var embed = $(this).data('embedly'); // Attach a done event to the loaded object that will be called when // everything is ready. embed.loaded.done(function(data){ alert(data.url); }); });
Embedly Display gives you access to an image proxy and resizing endpoints that allow you to scale images to any size. You can use $.embedly.defaults to set keys or query resize parameters:
$.embedly.defaults.key = 'Your Embedly Key'; $.embedly.defaults.query = {width: 300};
You can use selectors to resize or proxy images, we will look for all images with the data-src attribute:
e.g. <img data-src="http://embed.ly/static/images/logos/logo_color.png"></img> $('img').display('resize', {query: {width: 300}});
Or generate image urls with the client:
$.embedly.display.resize('http://embed.ly/static/images/logos/logo_color.png', {query: {width: 300}});
The Image Display client has 4 methods that each take 2 parameters: url, options. Each method returns an image url that can be added to the DOM.
display
- Corresponds to Embedly's Display API Endpoint used to simply proxy an image. Add secure to proxy through HTTPS.
resize
- Corresponds to Embedly's Resize API Endpoint used to resize an image by scaling it to a specific width or height preserving aspect ratio. Required query parameters: width or height. Optional: grow.
crop
- Corresponds to Embedly's Crop API Endpoint used to crop an image to a specific width and height. Required query parameters: width, height.
fill
- Corresponds to Embedly's Fill API Endpoint used to fit an image to a specific canvas size filled with a specific color. Required query parameters: width, height, color.
endpoint
[string:'display']- The image methods: display, resize, crop or fill. (required)
options
[Object:default object]A direct pass though to all the Query Arguments that the Embedly Display endpoints accept. These will be combined with the
key
andurl
to form the request to Embedly. See Query section below. arguments.:options: { key: 'your Embedly key', query: { width: 400, height: 400, color: #fff, ... } }
Required query arguments vary between endpoints, you can consult the Display endpoints documentation.
These are the query arguments that can be passed via the options. These arguments should be added to the options.query:
width
[integer:null]- The width you would like to scale the image.
height
[integer:null]- The height you would like to scale the image.
color
[string:null]- The color to fill the image with 3 or 6 hexadecimal characters. (fff, 4f2a55)
grow
[Boolean:false]- By default the API will not increase the size of images.
Set to
true
to allow images to be increased in size. errorurl
[string:null]- The fall back image url that will be used if the original image is invalid or cannot be processed. Ensure this image exists.
To get you going even faster, Embedly hosts all the files you need on cdn.embed.ly. Also available over HTTPS. The latest version is available here:
http://cdn.embed.ly/jquery.embedly-3.1.2.js http://cdn.embed.ly/jquery.embedly-3.1.2.min.js
BSD License can be found at - http://github.com/embedly/embedly-jquery/tree/master/LICENSE/
- Git location: http://github.com/embedly/embedly-jquery/
- Home Page: http://embed.ly
- Support: http://support.embed.ly
- Bower configuration.
- Makes
$.embedly.defaults.key work with $ .embedly.display.build
- Add Display Image Proxy and Resizing endpoint.
- Add $.display for dealing with image resizing and proxying.
- Updated the README.rst.
- Fixes bad deployment.
- Add extract endpoint.
- Use $.map instead of array.map for IE support
- Implemented the urlRe back into the options.
- Fixed a bug in bad batching.
- Complete rewrite of the existing plugin to be easier to use.
- Removed $.browser dependency. (#30)
- Fixing bug that was causing callbacks to be overwritten (#23)
- Updated Image styles to work on all images, including thumbnails
- hide empty descriptions
- Fixed how default values/settings are handled
- Added secure and frame as a query param
- Move qunit to lib
- Removed jQuery as we weren't using it.
- Updated the README.rst
- Added
$.embedly.defaults
- Added
char
setting anddescription
class to the embed. Thanks Daniel Levitt - Added
word
setting
- added secure flag for https requests