soulim/oembed

View on GitHub
README.md

Summary

Maintainability
Test Coverage
# oembed gem
[![Build Status](http://img.shields.io/travis/soulim/oembed.svg?style=flat)](http://travis-ci.org/soulim/oembed)  [![Code Climate](http://img.shields.io/codeclimate/github/soulim/oembed.svg?style=flat)](https://codeclimate.com/github/soulim/oembed)

[**oEmbed**](http://oembed.com/) 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](http://speakerdeck.com). 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.

```ruby
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.

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

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

```ruby
{
  "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.

```ruby
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:

```ruby
{
  "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.

```ruby
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.

```ruby
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
- JRuby