Skip to content
A slim library to work with oEmbed format. http://sul.im/oembed
Ruby
Find file
Failed to load latest commit information.
lib Extract all error classes into separate file
spec Update specs to the last RSpec syntax
.gitignore Initial commit
.rspec Init RSpec suite
.travis.yml Travis can't run the build
Gemfile
LICENSE Update my name :)
README.md Don't mention support for Rubinius
Rakefile Promote :spec to the default Rake task
oembed.gemspec Add Rake to development dependecies

README.md

oembed gem

Build Status Code Climate

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

oembed gem is a simple to use and slim (~150 LOC) library to work with oEmbed format. It has no external dependencies at runtime. All you need to have is Ruby itself.

The library shares a behaviour of oEmbed client with any Ruby object. Just include Oembed::Client into that object and you are good to go.

oembed gem is provider agnostic. It has no pre-configured providers. You can build a client for any oEmbed provider of the world :)

Installation

Add this line to your application's Gemfile:

gem 'oembed'

And then execute:

$ bundle

Or install it yourself as:

$ gem install oembed

Usage

You have to do a few things to build an oEmbed client with oembed gem.

  • include Oembed::Client into your object,
  • add instance method #endpoint_uri to that object. This method has to return a string with URI of oEmbed endpoint.

Lets start with a simple example. It will be a client for the awesome Speaker Deck. Note that we call the service class NameApi - this is to avoid clashing with gems (such as twitter) that may have classes named after the service.

require 'oembed'

class SpeakerDeckApi
  include Oembed::Client

  # Read more about endpoint on https://speakerdeck.com/faq#oembed
  def endpoint_uri
    'http://speakerdeck.com/oembed.json'
  end
end

That's it. Now you can use a method #fetch to get data from oEmbed enpoint of Speaker Deck.

client = SpeakerDeckApi.new
client.fetch('https://speakerdeck.com/u/soulim/p/rails')

The method #fetch will return a hash with oEmded data.

{
  "type" => "rich",
  "version" => 1.0,
  "provider_name" => "Speaker Deck",
  "provider_url" => "https://speakerdeck.com/",
  "title" => "Локализация приложения на базе Rails. Личный опыт и советы",
  "author_name" => "Alex Soulim",
  "author_url" => "https://speakerdeck.com/u/soulim",
  "html" => "<iframe style=\"border:0; padding:0; margin:0; background:transparent;\" mozallowfullscreen=\"true\" webkitallowfullscreen=\"true\" frameBorder=\"0\" allowTransparency=\"true\" id=\"presentation_frame_4fd3874cebb4b2001f0277e5\" src=\"//speakerdeck.com/embed/4fd3874cebb4b2001f0277e5\" width=\"710\" height=\"596\"></iframe>\n",
  "width" => 710,
  "height" => 596
}

oembed gem supports JSON and XML response formats. Here is an example of client for XML endpoint.

require 'oembed'

class FlickrApi
  include Oembed::Client

  def endpoint_uri
    'http://www.flickr.com/services/oembed.xml'
  end
end

client = FlickrApi.new
client.fetch('http://www.flickr.com/photos/alex_soulim/3593916989')

It will return:

{
  "type"=>"photo",
  "title"=>"IMG_2072",
  "author_name"=>"Alex Soulim", "author_url"=>"http://www.flickr.com/photos/alex_soulim/",
  "width"=>"683",
  "height"=>"1024",
  "url"=>"http://farm4.staticflickr.com/3618/3593916989_3d8aa991ea_b.jpg",
  "web_page"=>"http://www.flickr.com/photos/alex_soulim/3593916989/",
  "thumbnail_url"=>"http://farm4.staticflickr.com/3618/3593916989_3d8aa991ea_s.jpg",
  "thumbnail_width"=>"75",
  "thumbnail_height"=>"75",
  "web_page_short_url"=>"http://flic.kr/p/6tzLj2",
  "license"=>"All Rights Reserved",
  "license_id"=>"0",
  "version"=>"1.0",
  "cache_age"=>"3600",
  "provider_name"=>"Flickr",
  "provider_url"=>"http://www.flickr.com/"
}

You can make requests with additional parameters. Let's build a client for Instagram and use :maxwidth parameter.

require 'oembed'

class InstagramApi
  include Oembed::Client

  def endpoint_uri
    'http://api.instagram.com/oembed'
  end
end

client = InstagramApi.new
client.fetch('http://instagr.am/p/BUG/', maxwidth: 300)

If you need to always customise the fetch with additional parameters this can be done by providing a fetch method in the service class. In this example we are adding a maxwidth parameter to the request.

require 'oembed'

class YoutubeApi
  include Oembed::Client

  def endpoint_uri
    'https://www.youtube.com/oembed'
  end

  def fetch(url, options={})
    super url, options.merge(maxwidth: 620)
  end
end

client = YoutubeApi.new
client.fetch('https://www.youtube.com/watch?v=_DRNgL76OLc')

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Supported Ruby versions

This library is tested against the following Ruby implementations:

  • MRI Ruby 2.1
  • MRI Ruby 2.0
  • MRI Ruby 1.9.3
  • JRuby
Something went wrong with that request. Please try again.