README.md in onebox-1.1.0 vs README.md in onebox-1.2.0
- old
+ new
@@ -8,11 +8,19 @@
- [](https://coveralls.io/r/dysania/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](http://discourse.org) 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:
@@ -49,37 +57,41 @@
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 defaults with this handy interface:
+In addition you can set your own options with this handy interface:
``` ruby
require "onebox"
-Onebox.defaults = {
+Onebox.options = {
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
```
-Setup
-=====
+Adding Support for a new URL
+============================
- 1. Create new onebox engine
+ 1. Check if the site supports [oEmbed](http://oembed.com/) or [Open Graph](https://developers.facebook.com/docs/opengraph/).
+ 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.
+ 2. Create new onebox engine
+
``` ruby
# in lib/onebox/engine/name_onebox.rb
module Onebox
module Engine
class NameOnebox
- include Engine
+ include LayoutSupport
include HTML
private
def data
@@ -93,11 +105,11 @@
end
end
end
```
- 2. Create new onebox spec
+ 3. Create new onebox spec
``` ruby
# in spec/lib/onebox/engine/name_spec.rb
require "spec_helper"
@@ -125,11 +137,11 @@
expect(html).to include(link)
end
end
```
- 3. Create new handlebars template
+ 4. Create new handlebars template
``` html
# in templates/name.handlebars
<div class="onebox">
<a href="{{url}}">
@@ -139,63 +151,29 @@
<p>{{description}}</p>
</a>
</div>
```
- 4. Create new fixture from HTML response
+ 5. Create new fixture from HTML response
``` bash
curl --output spec/fixtures/oneboxname.response -L -X -GET http://example.com
```
- 5. Require in Engine module
+ 6. Require in Engine module
``` ruby
# in lib/onebox/engine/engine.rb
require_relative "engine/name_onebox"
```
-
-Onebox currently has support for page, image, and video URLs from these sites:
- - Amazon
- - Android App Store
- - Apple Store
- - BlipTV
- - Clikthrough
- - College Humor
- - Dailymotion
- - Dotsub
- - Flickr
- - Funny or Die
- - GitHub
- - Blob
- - Commit
- - Gist
- - Pull Request
- - Hulu
- - Imgur
- - Kinomap
- - NFB
- - Open Graph
- - Qik
- - Revision
- - Rotten Tomatoes
- - Slideshare
- - SmugMug
- - SoundCloud
- - Stack Exchange
- - TED
- - Twitter
- - Wikipedia
- - yFrog
-
Installing
==========
Add this line to your application's Gemfile:
- gem "onebox". "~> 1.0"
+ gem "onebox". "~> 1.2"
And then execute:
$ bundle