oembed_provider 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Horowhenua Library Trust
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,104 @@
+= 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: https://github.com/kete/oembed_provider
+
+Project issue tracker: http://kete.lighthouseapp.com/projects/69994-oembed_provider/
+
+More details of oEmbed and its specification can be found at http://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.
+
+=== 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:
+
+Links to commits to how oembed_provider is used in Kete application (http://kete.net.nz) coming soon...
+
+=== 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
+   
+== 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 http://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 (c) 2011 Horowhenua Library Trust. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "oembed_provider"
+    gem.summary = %Q{A Rails engine to answer oEmbed requests for application media asset models.}
+    gem.description = %Q{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. This gem does not offer oEmbed consumer functionality. (Rails 2.3.5 only for now)}
+    gem.email = "walter@katipo.co.nz"
+    gem.homepage = "https://github.com/kete/oembed_provider"
+    gem.authors = ["Walter McGinnis"]
+    gem.add_dependency "addressable"
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  puts "This gem includes a full rails app for running tests (and staging development not yet extracted to the gem proper). Run tests there by changing to test/full_[RAIlS_VERSION_#_with_underscores]_app_with_tests and doing 'rake test'."
+end
+
+# require 'rake/testtask'
+# Rake::TestTask.new(:test) do |test|
+#   test.libs << 'lib' << 'test'
+#   test.pattern = 'test/**/test_*.rb'
+#   test.verbose = true
+# end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "oembed_provider #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/app/controllers/oembed_provider_controller.rb

@@ -0,0 +1,55 @@
+class OembedProviderController < ApplicationController
+  # Prevents the following error from showing up, common in Rails engines
+  # A copy of ApplicationController has been removed from the module tree but is still active!
+  unloadable
+
+  # GET /oembed?url=... json by default
+  # GET /oembed.json?url=...
+  # GET /oembed.json?url=...&callback=myCallback
+  # GET /oembed.xml?url=...
+  def endpoint
+    # get object that we want an oembed_response from
+    # based on url
+    # and get its oembed_response
+    media_item = OembedProvider.find_provided_from(params[:url])
+    options = Hash.new
+    max_dimensions = [:maxwidth, :maxheight]
+
+    unless media_item.class::OembedResponse.providable_oembed_type == :link
+      max_dimensions.each { |dimension| options[dimension] = params[dimension] if params[dimension].present? }
+    end
+
+    @oembed_response = media_item.oembed_response(options)
+
+    # to_xml and to_json overidden in oembed_providable module
+    # to be properly formatted
+    # TODO: handle unauthorized case
+    respond_to do |format|
+      if @oembed_response
+        format.html { render_json @oembed_response.to_json } # return json for default
+        format.json { render_json @oembed_response.to_json }
+        format.xml  { render :xml => @oembed_response }
+      else
+        format.all { render_404 }
+      end
+    end
+  end
+
+  protected
+  # thanks to http://blogs.sitepoint.com/2006/10/05/json-p-output-with-rails/
+  def render_json(json, options={})
+    callback, variable = params[:callback], params[:variable]
+    response = begin
+                 if callback && variable
+                   "var #{variable} = #{json};\n#{callback}(#{variable});"
+                 elsif variable
+                   "var #{variable} = #{json};"
+                 elsif callback
+                   "#{callback}(#{json});"
+                 else
+                   json
+                 end
+               end
+    render({:content_type => :js, :text => response}.merge(options))
+  end
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+# extend routes for oembed provider endpoint
+ActionController::Routing::Routes.draw do |map|
+  # only one route needed
+  map.with_options :controller => 'oembed_provider' do |oembed_provider|
+    oembed_provider.connect 'oembed.:format', :action => 'endpoint'
+    oembed_provider.connect 'oembed', :action => 'endpoint'
+  end
+end

data/lib/oembed_providable.rb

@@ -0,0 +1,201 @@
+require 'oembed_provider'
+require 'builder'
+
+module OembedProvidable #:nodoc:
+  def self.included(base)
+    base.send(:include, OembedProvidable::Provided)
+  end  
+
+  # use this to make your model able to respond to requests
+  # against the OembedProviderController
+  module Provided
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def oembed_providable_as(*args)
+        # don't allow multiple calls
+        return if self.included_modules.include?(OembedProvidable::Provided::InstanceMethods)
+
+        send :include, OembedProvidable::Provided::InstanceMethods
+
+        specs = args.last.is_a?(Hash) ? args.pop : Hash.new
+        
+        oembed_type = args.first
+
+        if !oembed_type.is_a?(Symbol) || ![:photo, :video, :link, :rich].include?(oembed_type)
+            raise ArgumentError, "oEmbed type must be :photo, :video, :link, or :rich"
+        end
+
+        # create the scoped oembed_response model
+        const_set("OembedResponse", Class.new).class_eval do
+          cattr_accessor :providable_class
+          self.providable_class = self.name.split('::').first.constantize
+
+          cattr_accessor :providable_specs
+          self.providable_specs = specs
+
+          cattr_accessor :oembed_version
+          self.oembed_version = OembedProvider.version
+
+          cattr_accessor :providable_oembed_type
+          self.providable_oembed_type = oembed_type
+
+          the_provider_name = specs[:provider_name].present? ? specs[:provider_name] : OembedProvider.provider_name
+          raise ArgumentError, "Missing provider_name setting in either OembedProvider.provider_name or oembed_providable_as spec." unless the_provider_name.present?
+          cattr_accessor :providable_provider_name
+          self.providable_provider_name = the_provider_name
+
+          the_provider_url = specs[:provider_url].present? ? specs[:provider_url] : OembedProvider.provider_url
+          raise ArgumentError, "Missing provider_url setting in either OembedProvider.provider_url or oembed_providable_as spec." unless the_provider_url.present?
+          cattr_accessor :providable_provider_url
+          self.providable_provider_url = the_provider_url
+
+          # cache_age is optional and can be nil
+          the_cache_age = specs[:cache_age].present? ? specs[:cache_age] : OembedProvider.cache_age
+          cattr_accessor :providable_cache_age
+          self.providable_cache_age = the_cache_age
+
+          # these are what the response should return
+          # as per the oEmbed Spec
+          # http://oembed.com/#section2 - 2.3.4
+          # :type is required, but is model wide and set via oembed_providable_as
+          # :version is required and is handled below
+          attributes_to_define = OembedProvider.optional_attributes
+
+          attributes_to_define += OembedProvider.required_attributes[oembed_type]
+
+          # site wide values
+          # :provider_name, :provider_url, :cache_age
+          # can be set via oembed_providable_as
+          # or set via OembedProvider initialization
+          attributes_to_define += OembedProvider.base_attributes
+
+          # not relevant to links, but everything else
+          attributes_to_define += [:maxheight, :maxwidth] unless oembed_type == :link
+
+          cattr_accessor :providable_all_attributes
+          self.providable_all_attributes = attributes_to_define
+
+          attributes_to_define.each do |attr|
+            attr_accessor attr
+          end
+
+          # datastructure is hash
+          # with attribute name as key
+          # and method to call on providable as value
+          # both as symbol
+          # oembed_providable_as can specify method to call for an attribute
+          def self.method_specs_for(attributes)
+            method_specs = Hash.new
+            attributes.each do |attr|
+              if providable_specs.keys.include?(attr)
+                method_specs[attr] = providable_specs[attr]
+              else
+                method_specs[attr] = attr
+              end
+            end
+            method_specs
+          end
+
+          cattr_accessor :optional_attributes_specs
+          self.optional_attributes_specs = method_specs_for(OembedProvider.optional_attributes)
+
+          cattr_accessor :required_attributes_specs
+          self.required_attributes_specs = method_specs_for(OembedProvider.required_attributes[oembed_type])
+
+          # options are added to handle passing maxwidth and maxheight
+          # relevant to oembed types photo, video, and rich
+          # if they have a thumbnail, then these also much not be bigger
+          # than maxwidth, maxheight
+          def initialize(providable, options = {})
+            self.version = self.class.oembed_version
+
+            # we set maxwidth, maxheight first
+            # so subsequent calls to providable.send(some_method_name)
+            # can use them to adjust their values
+            unless type == :link
+              self.maxheight = options[:maxheight].to_i if options[:maxheight].present?
+              self.maxwidth = options[:maxwidth].to_i if options[:maxwidth].present?
+
+              providable.oembed_max_dimensions = { :height => maxheight, :width => maxwidth }
+            end
+
+            self.class.required_attributes_specs.each do |k,v|
+              value = providable.send(v)
+              raise ArgumentError, "#{k} is required for an oEmbed response." if value.blank?
+
+              send(k.to_s + '=', value)
+            end
+
+            self.class.optional_attributes_specs.each do |k,v|
+              send(k.to_s + '=', providable.send(v))
+            end
+
+            self.provider_name = self.class.providable_provider_name
+            self.provider_url =  self.class.providable_provider_url
+            self.cache_age = self.class.providable_cache_age
+          end
+
+          def type
+            self.class.providable_oembed_type
+          end
+
+          # because this isn't an AR record, doesn't include to_xml
+          # plus we need a custom
+          # root node needs to replaced with oembed rather than oembed_response
+          def to_xml
+            attributes = self.class.providable_all_attributes
+
+            builder = Nokogiri::XML::Builder.new do |xml|
+              xml.oembed {
+                attributes.each do |attr|
+                  next if attr.to_s.include?('max')
+                  value = self.send(attr)
+                  xml.send(attr, value) if value.present?
+                end
+              }
+            end
+
+            builder.to_xml
+          end
+
+          # override default to_json
+          def as_json(options = {})
+            as_json = super(options)
+
+            attributes = self.class.providable_all_attributes
+
+            as_json.delete_if { |k,v| v.blank? }
+
+            as_json.delete_if { |k,v| k.include?('max') }
+
+            as_json
+          end
+
+
+        end
+      end
+
+      def oembed_type
+        self::OembedResponse.providable_oembed_type
+      end
+    end
+
+    module InstanceMethods
+      def oembed_response(options = {})
+        @oembed_response ||= self.class::OembedResponse.new(self, options)
+      end
+
+      def oembed_max_dimensions=(options)
+        options = { :height => nil, :width => nil } if options.blank?
+        @oembed_max_dimensions = options
+      end
+
+      def oembed_max_dimensions
+        @oembed_max_dimensions || { :height => nil, :width => nil }
+      end
+    end
+  end
+end

data/lib/oembed_provider.rb

@@ -0,0 +1,91 @@
+require 'addressable/uri'
+require 'oembed_providable'
+# set OembedProvider.provide_name, etc. in your config/initializers or somewhere
+class OembedProvider
+  class << self
+    def provider_url
+      @@provider_url ||= String.new
+    end
+
+    def provider_url=(url)
+      @@provider_url = url
+    end
+
+    def provider_name
+      @@provider_name ||= String.new
+    end
+
+    def provider_name=(name)
+      @@provider_name = name
+    end
+
+    def cache_age
+      @@cache_age ||= nil
+    end
+
+    def cache_age=(age)
+      @@cache_age = age
+    end
+
+    def version
+      "1.0"
+    end
+
+    # every request has these, mostly required
+    # mostly site wide
+    # version is special case
+    def base_attributes
+      [:provider_url,
+       :provider_name,
+       :cache_age,
+       :version]
+    end
+
+    # optional attributes
+    # that are specific to an instance of the providable model
+    def optional_attributes
+      [:title,
+       :author_name,
+       :author_url,
+       :thumbnail_url,
+       :thumbnail_width,
+       :thumbnail_height]
+    end
+
+    # these may be required depending on type
+    # see 2.3.4.1 - 2.3.4.4 of spec
+    # type specific attributes
+    # all attributes listed for these types are required
+    # the empty link array shows that nothing is required
+    def required_attributes
+      { :photo => [:url, :width, :height], 
+        :video => [:html, :width, :height],
+        :link => [],
+        :rich => [:html, :width, :height] }
+    end
+
+    def controller_model_maps
+      @@controller_model_maps ||= Hash.new
+    end
+
+    def controller_model_maps=(hash_map)
+      @@controller_model_maps = hash_map
+    end
+
+    def find_provided_from(url)
+      url = Addressable::URI.parse(url)
+      submitted_url_params = ActionController::Routing::Routes.recognize_path(url.path, :method=>:get)
+    
+      controller = submitted_url_params[:controller]
+      id = submitted_url_params[:id]
+
+      # handle special cases where controllers are directly configured to point at a specific model
+      model = OembedProvider.controller_model_maps[controller]
+
+      # otherwise we use convention over configuration to determine model
+      model = controller.singularize.camelize unless model
+    
+      model.constantize.find(id)
+    end
+  end
+end

data/lib/oembed_provider_helper.rb

@@ -0,0 +1,18 @@
+# include this in your relevant helpers
+# to add discoverability link, etc.
+module OembedProviderHelper
+  # hardcodes http as protocol
+  # http is specified in http://oembed.com/
+  def oembed_provider_links
+    host_url = request.host
+    escaped_request_url = request.url.sub('://', '%3A//')
+    html = tag(:link, :rel => "alternate",
+               :type => "application/json+oembed",
+               :href => "http://#{host_url}/oembed?url=#{escaped_request_url}",
+               :title => "JSON oEmbed for #{@title}")
+    html += tag(:link, :rel => "alternate",
+               :type => "application/xml+oembed",
+               :href => "http://#{host_url}/oembed.xml?url=#{escaped_request_url}",
+               :title => "XML oEmbed for #{@title}")
+  end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'oembed_provider'

data/test/full_2_3_5_app_with_tests/.gitignore

@@ -0,0 +1,27 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+webrat*
+test.sqlite3
+test/debug.log
+db/development.sqlite3
+db/test.sqlite3
+log/*.log

data/test/full_2_3_5_app_with_tests/README

@@ -0,0 +1 @@
+This is a full Rails app used to test the gem's functionality.

data/test/full_2_3_5_app_with_tests/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/test/full_2_3_5_app_with_tests/app/controllers/application_controller.rb

@@ -0,0 +1,7 @@
+# Filters added to this controller apply to all controllers in the application.
+# Likewise, all the methods added will be available for all controllers.
+
+class ApplicationController < ActionController::Base
+  helper :all # include all helpers, all the time
+  protect_from_forgery # See ActionController::RequestForgeryProtection for details
+end