oembed_provider_engine 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 XING AG
+
+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,82 @@
+= OembedProviderEngine
+
+Turns your rails app into an {oembed}[http://oembed.com/] provider
+
+== About
+{Oembed}[http://oembed.com/] is an open format for embedding media from third-party providers. This gem is a mountable engine that turns your rails 3 app into an oembed provider allowing oembed consumers to easily embed your media resources into their site.
+
+== Usage
+=== Installation
+Add the following to your Gemfile:
+
+  gem "oembed-provider-engine"
+
+=== Provider Settings
+Add a config/initializers/oembed_provider.rb file to configure your provider settings:
+
+  OembedProviderEngine::OembedProvider.provider_name = "Example Provider"
+  OembedProviderEngine::OembedProvider.provider_url  = "http://example.com"
+
+If a controller doesn't map to model name as per tablize convention, map it like this:
+
+  OembedProviderEngine::OembedProvider.controller_model_maps = { 'example' => 'FooBar' }
+
+=== Providable Model
+To declare your model providable, include the following:
+
+  include OembedProvider::OembedProvidable
+  # the first argument is the oembed type, that is one of :rich, :link, :photo, or :video
+  oembed_providable_as :rich
+
+Your model has to provide methods to give what oembed_provider expects for your oembed type. Those methods need to make sure that request parameters maxheight and maxwidth are obeyed, see {oembed specs}[http://oembed.com/] for details. 
+
+If the methods have names different from the respective oembed attributes, you need to match them here:
+
+  # data for the oembed attribute 'title' is provided by a method named 'label'
+  oembed_providable_as :link, title: :label
+
+You can also override the provider settings from the initializer:
+
+  oembed_providable_as :link, provider_name: 'Example'
+
+=== Discovery
+If you want to allow for oembed discovery, you can use the helper function from this engine to add links to the HTML head:
+
+  <%= oembed_provider_links %>
+
+=== Routing
+The engine adds a route +/oembed+ to your app, which is your oembed api endpoint. By default, it returns json, but it may as well return xml or json-p. Following the oembed specs, a request parameter format can be used to specify the requested format (xml or json). If you add request parameters variable or callback, json-p is returned instead of json. The engine also provides the additional endpoints +/oembed.xml+ and +/oembed.json+ which return the respective format.
+
+== Security
+The current implementation directly accesses your application's model to fetch the data for the response. This may bypass your applicaton's authorization and expose non-public data via oembed if your model does not take this into account! 
+
+== TODO
+* proper handling of unauthorized
+* migrate from shoulda to rspec
+* caching
+* allow the providable model to omit methods corresponding to optional oembed fields
+
+== Contribute
+Feel free to fork the project and send us pull requests.
+
+
+== Credits
+This gem is heavily based upon the rails 2 gem {oembed-provider}[https://github.com/kete/oembed_provider/] originally developed by {Walter McGinnis}[https://github.com/walter] for {kete}[https://github.com/kete].
+
+== Authors
+
+{Kerstin Puschke}[http://github.com/titanoboa],
+{Hinnerk Altenburg}[http://github.com/hinnerk-a],
+{George Avramidis}[http://github.com/tdgs] and
+{Ömür Özkir}[http://github.com/oem]
+
+You can find out more about our work on our {dev blog}[http://devblog.xing.com].
+
+== Contributors
+
+Thanks to all who have made contributions {to this gem}[https://github.com/xing/oembed-provider-engine/contributors] as well as {its rails 2 predecessor}[https://github.com/kete/oembed_provider/contributors].
+
+Copyright (c) 2012 {XING AG}[http://www.xing.com/]
+
+Released under the MIT license. For full details see MIT-LICENSE included in this
+distribution.

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'OembedProviderEngine'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/oembed_provider_engine/application_controller.rb

@@ -0,0 +1,2 @@
+class OembedProviderEngine::ApplicationController < ApplicationController
+end

data/app/controllers/oembed_provider_engine/oembed_provider_controller.rb

@@ -0,0 +1,56 @@
+module OembedProviderEngine
+  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 = ::OembedProviderEngine::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
+end

data/app/helpers/oembed_provider_engine/application_helper.rb

@@ -0,0 +1,4 @@
+module OembedProviderEngine
+  module ApplicationHelper
+  end
+end

data/app/helpers/oembed_provider_engine/oembed_provider_helper.rb

@@ -0,0 +1,20 @@
+module OembedProviderEngine
+  # 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
+end

data/app/models/oembed_provider_engine/oembed_providable.rb

@@ -0,0 +1,204 @@
+require 'builder'
+require 'nokogiri'
+
+module OembedProviderEngine
+  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 ![: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(opts = {}, &block)
+              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 = {}
+
+              self.class.providable_all_attributes.each do |attr|
+                next if attr.to_s.include?("max")
+                v = self.send(attr)
+                as_json[attr] = self.send(attr) if v.present?
+              end
+
+              as_json
+            end
+          end
+        end
+
+        def oembed_type
+          self::OembedResponse.providable_oembed_type
+        end
+      end
+
+      module InstanceMethods
+        # FIXME: There is a bug here. Do we really want to memoize?
+        def oembed_response(options = {})
+          @oembed_response ||= self.class::OembedResponse.new(self, options)
+        end
+
+        def oembed_max_dimensions=(options)
+          @oembed_max_dimensions = options
+        end
+
+        def oembed_max_dimensions
+          @oembed_max_dimensions || { :height => nil, :width => nil }
+        end
+      end
+    end
+  end
+end

data/app/models/oembed_provider_engine/oembed_provider.rb

@@ -0,0 +1,95 @@
+require 'addressable/uri'
+
+module OembedProviderEngine
+  # set OembedProvider.provider_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,
+         :type,
+         :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)
+        #TODO smell
+        submitted_url_params = Rails.application.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
+end

data/app/views/layouts/oembed_provider_engine/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>OembedProvider</title>
+  <%= stylesheet_link_tag    "oembed_provider/application", :media => "all" %>
+  <%= javascript_include_tag "oembed_provider/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,3 @@
+OembedProviderEngine::Engine.routes.draw do
+  match "/(.:format)" => "oembed_provider#endpoint"
+end

data/lib/oembed_provider_engine/engine.rb

@@ -0,0 +1,11 @@
+module OembedProviderEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace OembedProviderEngine
+
+    initializer 'oembed_provider_engine.action_controller' do |app|
+      ActiveSupport.on_load :action_controller do
+        helper ::OembedProviderEngine::OembedProviderHelper
+      end
+    end
+  end
+end

data/lib/oembed_provider_engine/version.rb

@@ -0,0 +1,3 @@
+module OembedProviderEngine
+  VERSION = "0.0.1"
+end

data/lib/oembed_provider_engine.rb

@@ -0,0 +1,4 @@
+require "oembed_provider_engine/engine"
+
+module OembedProviderEngine
+end

data/lib/tasks/oembed_providerengine_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :oembed_provider do
+#   # Task goes here
+# end