Skip to content

Latest commit

 

History

History
135 lines (83 loc) · 5.24 KB

README.rdoc

File metadata and controls

135 lines (83 loc) · 5.24 KB
Raw

oembed_provider ↑

A Rails engine to answer oEmbed requests for application media asset models.

In other words, this gem allows your application, after configuring the gem and the relevant models, to act as an oEmbed Provider by providing a controller that returns JSON or XML for a given oEmbed consumer request for the specified media asset.

The gem creates one unified oEmbed endpoint for all the oEmbed provided models via OembedProviderController.

This gem does not offer oEmbed consumer functionality.

Project homepage: github.com/kete/oembed_provider

Project issue tracker: kete.lighthouseapp.com/projects/69994-oembed_provider/

More details of oEmbed and its specification can be found at oembed.com/

IMPORTANT: Currently only known to work with Rails 2.3.5. Feel free to fork and get working with later versions of Rails. I’ll happily add this as long as it stills works with Rails 2.3.5.

Usage ↑

Installing Gem ↑

gem install oembed_provider

Installing from Source ↑

Get source from git and checkout submodules:
  git clone http://github.com/kete/oembed_provider.git
  cd oembed_provider
  git submodule init
  git submodule update

Installing Gem:
  rake gemspec
  gem build {generated gemspec file}
  gem install {generated gem file}

  Running rake will check that you have the dependencies installed correctly.

OembedProvider settings ↑

Add a config/initializers/oembed_provider.rb file with something like this:

OembedProvider.provider_name = "Your Site Name"
OembedProvider.provider_url = "http://your_site/"

# if a controller doesn't map to model name as per tablize convention
# map it here
OembedProvider.controller_model_maps = { 'images' => 'StillImage' }

Declare your model oEmbed providable ↑

Simple examples:

include OembedProvidable
# the first argument to oembed_providable_as is required
# and is the oembed type, can be :photo, :video, :link, or :rich
oembed_providable_as :link

If your model has methods that match the oEmbed method names relevant to your oembed type, you are done. Otherwise change your oembed_providable_as like so:

include OembedProvidable
oembed_providable_as :link, :title => :label

The second argument is hash where keys are names of oembed attributes needed and the value is the name of model’s method for giving the corresponding value. Adjust to suit. Of course, you may need to implement methods to give what oembed_provider expects for your oembed type.

You’ll also need to include logic in your methods that deals with maxheight and maxwidth if they are passed in as parameters to your oembed_response for photo, video, and rich types (for thumbnails for video and rich types).

For :link type, unless you do webpage thumbnails, you’ll want to do something like this:

%w(url height width).each do |method_stub|
  define_method('thumbnail_' + method_stub) do
    nil
  end
end

More complex example: ↑

In Kete, we use oembed_provider with the StillImage model which maps to the images controller (exact line number links may be inaccurate in future):

github.com/kete/kete/blob/master/config/initializers/oembed_provider.rb#L11

github.com/kete/kete/blob/master/lib/kete_common_oembed_support.rb

github.com/kete/kete/blob/master/app/models/still_image.rb#L56

github.com/kete/kete/blob/master/app/views/layouts/application.rhtml#L45

github.com/kete/kete/blob/master/test/unit/still_image_test.rb#L135

Functional and integration testing defers to the testing done in this gem.

Get oEmbed requests ↑

A route is installed by the engine to answer requests at /oembed. It will answer json (when no format is specifed), json-p (callback and/or variable), and xml requests.

Discoverability helper ↑

You can optionally add links to the HTML head of relevant pages by adding this to your appropriate helper modules (i.e. in something under app/helpers/ that suits):

include OembedProviderHelper

and then adding this to the appropriate layout file (i.e. something under app/views/layout that matchs):

<%= oembed_provider_links %>

TODO: ↑

  • a caching system

Thank yous ↑

This gem was developed for the Kete open source application (kete.net.nz) and was funded by pledge campaign to improve media selection from with the rich text editor (i.e. the TinyMCE plugin).

Horowhenua Library Trust, Wellington City Libraries, Te Reo o Taranaki, Environmental Earth Sciences, CALYX, and many individual contributors.

Thanks to all contributors.

Note on Patches/Pull Requests ↑

  • Fork the project.

  • Make your feature addition or bug fix to a branch following this convention: enhancement_[ticket #]_short_description or bugfix_[ticket #]_short_description replace [ticket #] with ticket number from kete.lighthouseapp.com/projects/69994-oembed_provider

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright ↑

Copyright © 2011 Horowhenua Library Trust. See LICENSE for details.