Embedly jQuery

Embedly jQuery is a jQuery Library for interacting with the Embedly API.

Basic Setup

Embedly jQuery requires jQuery 1.5 or greater as it uses Deferred Objects. Add jQuery and Embedly jQuery to your document.

<head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.2/jquery.min.js" type="text/javascript"></script>
  <script src="http://cdn.embed.ly/jquery.embedly-3.1.2.min.js" type="text/javascript"></script>
</head>

Or with Bower:

bower install embedly-jquery

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);
});

Key

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.

Selector

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');

Client

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 also support chaining:

$.embedly.oembed(['http://embed.ly', 'http://apple.com'])

.then(function(data){

// Return only the titles. return data.map(function(d){return d.title;});

}).then(function(titles){

// yay titles console.log(titles)

});

Methods

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.

Batching

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);
});

Data

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.

Options

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 the urls 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 for photo types, a simple title and description embed for link types and directly embed the html for rich and video 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 default display callback is designed to work with oembed 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 to true for https or false 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)
});

Errors and Invalid URLs

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.
  }
})

Data / Custom Events

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);
  });
});

Image Proxy and Resizing

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}});

Image Methods

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.

Display Method Parameters

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 and url 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.

Image Query Parameters

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.

CDN

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

Licensing

BSD License can be found at - http://github.com/embedly/embedly-jquery/tree/master/LICENSE/

Embedly URLs

Git location: http://github.com/embedly/embedly-jquery/
Home Page: http://embed.ly
Support: http://support.embed.ly

Changelog

3.1.2

Bower configuration.

3.1.1

Makes $.embedly.defaults.key work with $.embedly.display.build

3.1.0

Add Display Image Proxy and Resizing endpoint.
Add $.display for dealing with image resizing and proxying.
Updated the README.rst.

3.0.5

Fixes bad deployment.

3.0.4

Add extract endpoint.

3.0.3

Use $.map instead of array.map for IE support

3.0.2

Implemented the urlRe back into the options.

3.0.1

Fixed a bug in bad batching.

3.0.0

Complete rewrite of the existing plugin to be easier to use.
Removed $.browser dependency. (#30)

2.2.0

Fixing bug that was causing callbacks to be overwritten (#23)

2.1.9

Updated Image styles to work on all images, including thumbnails
hide empty descriptions

2.1.8

Fixed how default values/settings are handled

2.1.7

Added secure and frame as a query param
Move qunit to lib
Removed jQuery as we weren't using it.

2.1.6

Updated the README.rst
Added $.embedly.defaults
Added char setting and description class to the embed. Thanks Daniel Levitt
Added word setting

2.1.5

added secure flag for https requests

embedly/embedly-jquery

embedly

Reviews

Repository Details