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://scripts.embed.ly/jquery.embedly-3.0.0.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.preview('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 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.preview('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.preview('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.preview(['http://embed.ly', 'http://google.com'], {
key: 'internal',
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 3 methods
oembed- Corresponds to Embedly's oEmbed API Endpoint.
preview- Corresponds to Embedly's Preview API Endpoint.
objectify- Corresponds to the Embedly's Objectify API Endpoint.
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 breakdown.
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,endpointand theurlsto 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
oembedendpoint. It will create an image forphototypes, a simple title and description embed forlinktypes and directly embed the html forrichandvideotypes.Generally you will want to overwrite this function for a more customized look and feel.
displayshould 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 one of three Embedly endpoints. A paid plan is required for Preview and Objectify.
- oembed - a standard in 3rd party embedding, contains a finite set of attributes.
- 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 Preview or Objectify will have to include their own
displaycallback function for handling the embeds. Our defaultdisplaycallback is designed to work withoembedonly.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.protocolto 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 totrueforhttpsorfalsefor 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.
progressshould 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.
doneshould accept a list of data objects.$('a').embedly({progress: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);
});
});
To get you going even faster, Embedly hosts all the files you need on scripts.embed.ly. The latest version is available here:
http://scripts.embed.ly/jquery.embedly-3.0.0.js http://scripts.embed.ly/jquery.embedly-3.0.0.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
- 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
charsetting anddescriptionclass to the embed. Thanks Daniel Levitt - Added
wordsetting
- added secure flag for https requests