1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
# ruby-oembed
[](https://rubygems.org/gems/ruby-oembed)
[](https://github.com/ruby-oembed/ruby-oembed/actions/workflows/ruby.yml)
[](https://codeclimate.com/github/ruby-oembed/ruby-oembed)
[](https://coveralls.io/github/ruby-oembed/ruby-oembed?branch=coveralls)
An oEmbed consumer library written in Ruby, letting you easily get embeddable HTML representations of supported web pages, based on their URLs. See [oembed.com](http://oembed.com) for more about the protocol.
# Installation
gem install ruby-oembed
# Get Started
## Built-in Providers
The easiest way to use this library is to make use of the built-in providers.
```ruby
OEmbed::Providers.register_all
resource = OEmbed::Providers.get('http://www.youtube.com/watch?v=2BYXBC8WQ5k')
resource.video? #=> true
resource.thumbnail_url #=> "http://i3.ytimg.com/vi/2BYXBC8WQ5k/hqdefault.jpg"
resource.html #=> <<-HTML
<object width="425" height="344">
<param name="movie" value="http://www.youtube.com/v/2BYXBC8WQ5k?fs=1"></param>
<param name="allowFullScreen" value="true"></param>
<param name="allowscriptaccess" value="always"></param>
<embed src="http://www.youtube.com/v/2BYXBC8WQ5k?fs=1" type="application/x-shockwave-flash" width="425" height="344" allowscriptaccess="always" allowfullscreen="true"></embed>
</object>
HTML
```
### Providers requiring an access token
Some built-in providers require authorization in order to work. These providers won't be registered unless an access token is provided. You can either pass access tokens to the `register_app` method.
```ruby
OEmbed::Providers.register_all(access_tokens: { facebook: @my_facebook_token })
```
Or you can provide access tokens via environment variable
```ruby
ENV['OEMBED_FACEBOOK_TOKEN'] #=> 'my-access-token'
OEmbed::Providers.register_all
```
#### Currently supported access tokens
| access_token | environment variable | Associated Providers |
|--------------|-------------------------|----------------------|
| `:facebook` | `OEMBED_FACEBOOK_TOKEN` | `FacebookPost`, `FacebookVideo`, `Instagram` |
## Custom Providers
If you'd like to use a provider that isn't included in the library, it's easy to create one. Just provide the oEmbed API endpoint and URL scheme(s).
```ruby
my_provider = OEmbed::Provider.new("http://my.cool-service.com/api/oembed_endpoint.{format}")
my_provider << "http://*.cool-service.com/image/*"
my_provider << "http://*.cool-service.com/video/*"
```
You can then use your new custom provider *or* you can register it along with the rest of the built-in providers.
```ruby
resource = my_provider.get("http://a.cool-service.com/video/1") #=> OEmbed::Response
resource.provider.name #=> "My Cool Service"
OEmbed::Providers.register(my_provider)
resource = OEmbed::Providers.get("http://a.cool-service.com/video/2") #=> OEmbed::Response
```
## Fallback Providers
Last but not least, ruby-oembed supports [Noembed](https://noembed.com/), [Embedly](http://embed.ly), provider discovery. The first two are provider aggregators. Each supports a wide array of websites ranging from [Amazon.com](http://www.amazon.com) to [xkcd](http://www.xkcd.com). The later is part of the oEmbed specification that allows websites to advertise support for the oEmbed protocol.
```ruby
OEmbed::Providers.register_fallback(
OEmbed::ProviderDiscovery,
OEmbed::Providers::Noembed
)
OEmbed::Providers.get('https://www.xkcd.com/802/') #=> OEmbed::Response
```
## Formatters
This library works wonderfully on its own, but can get a speed boost by using 3rd party libraries to parse oEmbed data. To use a 3rd party Formatter, just be sure to require the library _before_ ruby-oembed (or include them in your Gemfile before ruby-oembed).
```ruby
require 'json'
require 'xmlsimple'
require 'oembed'
OEmbed::Formatter::JSON.backend #=> OEmbed::Formatter::JSON::Backends::JSONGem
OEmbed::Formatter::XML.backend #=> OEmbed::Formatter::XML::Backends::XmlSimple
```
The following, optional, backends are currently supported:
* The [JSON implementation for Ruby](http://flori.github.com/json/)
* Rails' ActiveSupport::JSON (confirmed to work with Rails 3.0.x and should work with Rails 2.0+)
* [XmlSimple](http://xml-simple.rubyforge.org/)
# Lend a Hand
Code for the ruby-oembed library is [hosted on GitHub](https://github.com/ruby-oembed/ruby-oembed).
```bash
# Get the code.
git clone git://github.com/ruby-oembed/ruby-oembed.git
cd ruby-oembed
# Install all development-related gems.
gem install bundler
bundle install
# Run the tests.
bundle exec rake
# or run the test continually
bundle exec guard
```
If you encounter any bug, feel free to [create an Issue](https://github.com/ruby-oembed/ruby-oembed/issues).
We gladly accept pull requests! Just [fork](http://help.github.com/forking/) the library and commit your changes along with relevant tests. Once you're happy with the changes, [send a pull request](http://help.github.com/pull-requests/).
We do our best to [keep our tests green](https://github.com/ruby-oembed/ruby-oembed/actions/workflows/ruby.yml)
# Contributors
Thanks to [all who have made contributions](https://github.com/ruby-oembed/ruby-oembed/contributors) to this gem, both large and small.
# License
This code is free to use under the terms of the MIT license.
|
