onebox
Onebox is a library for turning media URLs into simple HTML previews of the resource.
Onebox currently has support for page, image, and video URLs for many popular sites.
It's great if you want users to input URLs and have your application convert them into rich previews for display. For example, a link to a YouTube video would be automatically converted into a video player.
It was originally created for Discourse but has since been extracted into this convenient gem for all to use!
Usage
Using onebox is fairly simple! First, make sure the library is required:
require "onebox"
Then pass a link to the library's interface:
require "onebox"
url = "http://www.amazon.com/gp/product/B005T3GRNW/ref=s9_simh_gw_p147_d0_i2"
preview = Onebox.preview(url)
This will contain a simple Onebox::Preview object that handles all the transformation.
From here you either call Onebox::Preview#to_s
or just pass the object to a string:
require "onebox"
url = "http://www.amazon.com/gp/product/B005T3GRNW/ref=s9_simh_gw_p147_d0_i2"
preview = Onebox.preview(url)
"#{preview}" == preview.to_s #=> true
Onebox has its own caching system but you can also provide (or turn off) your own system:
require "onebox"
url = "http://www.amazon.com/gp/product/B005T3GRNW/ref=s9_simh_gw_p147_d0_i2"
preview = Onebox.preview(url, cache: Rails.cache)
"#{preview}" == preview.to_s #=> true
In addition you can set your own options with this handy interface:
require "onebox"
Onebox. = {
cache: Rails.cache
}
url = "http://www.amazon.com/gp/product/B005T3GRNW/ref=s9_simh_gw_p147_d0_i2"
preview = Onebox.preview(url)
"#{preview}" == preview.to_s #=> true
Adding Support for a new URL
Check if the site supports oEmbed or Open Graph. If it does, you can probably get away with just whitelisting the URL in
Onebox::Engine::WhitelistedGenericOnebox
. If the site does not support open standards, you can create a new engine.Create new onebox engine
# in lib/onebox/engine/name_onebox.rb module Onebox module Engine class NameOnebox include LayoutSupport include HTML private def data { url: @url, name: raw.css("h1").inner_text, image: raw.css("#main-image").first["src"], description: raw.css("#postBodyPS").inner_text } end end end end
Create new onebox spec using FakeWeb
# in spec/lib/onebox/engine/name_spec.rb require "spec_helper" describe Onebox::Engine::NameOnebox do let(:link) { "http://example.com" } let(:html) { described_class.new(link).to_html } before do fake(link, response("name.response")) end it "has the video's title" do expect(html).to include("title") end it "has the video's still shot" do expect(html).to include("photo.jpg") end it "has the video's description" do expect(html).to include("description") end it "has the URL to the resource" do expect(html).to include(link) end end
Create new mustache template
# in templates/name.mustache <div class="onebox"> <a href="{{url}}"> <h1>{{name}}</h1> <h2 class="host">example.com</h2> <img src="{{image}}" /> <p>{{description}}</p> </a> </div>
Create new fixture from HTML response for your FakeWeb request(s)
curl --output spec/fixtures/oneboxname.response -L -X -GET http://example.com
Require in Engine module
# in lib/onebox/engine.rb require_relative "engine/name_onebox"
Installing
Add this line to your application's Gemfile:
gem "onebox", "~> 1.2"
And then execute:
$ bundle
Or install it yourself as:
$ gem install onebox
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request