active_public_resources 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3f82492f1e5cfc67fee25365b48d83ce58efa170
+  data.tar.gz: f45c20c7330389c2f59b8f3aad0e03b558780a7a
+SHA512:
+  metadata.gz: 06100044d338f7837c23684f3ea49f7803242300a08497f90e45bceb1ed00826090dbc8e122d5ef2eeced25eb95019a2959473eccdc2c6baa63edd618d092e15
+  data.tar.gz: bbbbe5c9448f2b80ffcd3c2f51f8a72a5f258b8437a4fd91d066ae78220bc15130c9cc4af4a12a17e64f390076f42d6e9b2701d30cd420a2b99e16605497df59

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+active_public_resources_config.yml

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - "2.0.0"

data/Gemfile

@@ -0,0 +1,24 @@
+source 'https://rubygems.org'
+
+gem 'yard'
+gem 'rake'
+
+group :test do
+  gem 'rspec',       '~> 2.14.1'
+  # gem 'rspec-mocks', '~> 2.14.4'
+  gem 'vcr'
+  gem 'webmock'
+  gem 'simplecov',   '~> 0.8.1', :require => false
+  gem 'growl'
+  gem 'growl-rspec'
+end
+
+group :development do
+  gem 'guard-rspec'
+end
+
+group :development, :test do
+  gem 'pry'
+end
+
+gemspec

data/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cli: '--color --format nested' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright (c) 2013 Instructure
+
+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.md

@@ -0,0 +1,326 @@
+# Active Public Resources
+
+[![Build Status](https://travis-ci.org/instructure/active_public_resources.png)](https://travis-ci.org/instructure/active_public_resources)
+[![Code Climate](https://codeclimate.com/github/instructure/active_public_resources.png)](https://codeclimate.com/github/instructure/active_public_resources)
+
+Active Public Resources is a collection of resources online which return embeddable or linkable
+resources. This gem normalizes the requests and responses into response type objects.
+
+For example, you can search for videos via YouTube, Vimeo and SchoolTube. Each of these
+requests will use a common interface (RequestCriteria) and a common response (DriverResponse).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'active_public_resources'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_public_resources
+
+## Concepts
+
+There are several components that make up the full request/response circle with this gem:
+
+* **Request Criteria** - The object which contains the criteria that is passed to the driver to make the request.
+* **Driver Response** - The response object which contains the request criteria, next request criteria and a list of resulting response type objects.
+* **Response Types** - Objects which are returned in the driver response. Includes Exercise, Folder, Image, Quiz and Video.
+* **Return Types** - The linkable, downloadable or embeddable results of the response type.
+
+## Request Criteria
+
+A request criteria in this context is a ruby object which contains the criteria that is to be
+passed to the driver.
+
+| Name           | Required? | Description 
+| -------------- |:---------:| ----------- 
+| query          |     No    | Search term
+| page           |     No    | Page of results. Defaults to 0
+| per_page       |     No    | Items to return per page. Defaults to 25
+| content_filter |     No    | Filter flag. Can either be `none` or `strict`. Defaults to `none`
+| sort           |     No    | Sort filter. Can be `relevance`, `recent` or `popular`. Defaults to `relevance`
+| folder         |     No    | Current folder. This is used for folder-based requests (e.g. Khan Academy). Defaults to `root`
+
+Examples:
+
+```ruby
+# Search-based criteria
+criteria = APR::RequestCriteria.new(
+  :query          => "education",
+  :page           => 3,
+  :per_page       => 15,
+  :sort           => APR::RequestCriteria::SORT_RELEVANCE,
+  :content_filter => APR::RequestCriteria::CONTENT_FILTER_NONE
+)
+
+# Folder-based criteria
+criteria = APR::RequestCriteria.new(
+  :folder => "engineering"
+)
+```
+
+## Driver Response (and Response Types)
+
+A driver response is the object which encapsulates the results of the driver's `perform_request` method. It contains the following data:
+
+* **items**         - Array of Response Types
+* **criteria**      - Original search criteria which was used to perform the request
+* **next_criteria** - Next criteria which can be used to get the next set of results (e.g. page 2)
+* **total_items**   - Total number of results for search criteria
+
+### Folder
+
+A folder is returned from API's which are browsable (e.g. Khan Academy).
+
+* **id**          - ID of folder
+* **title**       - Folder name
+* **description** - Folder description
+* **parent_id**   - ID of parent folder (or `nil` for root)
+* **items**       - Array of Response Types for this folder (can include folders as well)
+
+### Image
+
+* **id**          - ID of image
+* **title**       - Image name
+* **description** - Image description
+* **url**         - Image URL (used in HREF)
+* **width**       - Image width
+* **height**      - Image height
+
+### Quiz
+
+* **id**           - ID of quiz
+* **title**        - Quiz name
+* **description**  - Quiz description
+* **url**          - URL of quiz
+* **term_count**   - Number of items in quiz
+* **created_date** - Date quiz was created
+* **has_images**   - Boolean flag to indicate if quiz has images
+* **subjects**     - Array of tags
+
+### Video
+
+* **id**            - ID of video
+* **title**         - Video name
+* **description**   - Video description
+* **thumbnail_url** - Thumbnail image url
+* **url**           - URL to video
+* **duration**      - Duration in seconds
+* **width**         - Video width
+* **height**        - Video height
+* **username**      - Username of creator
+* **num_views**     - Number of views
+* **num_likes**     - Number of likes
+* **num_comments**  - Number of comments
+* **created_date**  - Date created
+
+### Exercise
+
+* **id**            - ID of exercise
+* **title**         - Exercise name
+* **description**   - Exercise description
+* **thumbnail_url** - Thumbnail image url
+* **url**           - URL to exercise
+
+## Return Types
+
+Return types are the embeddable, linkable or downloadable parts of the response type.
+For example, if you have a video response type, you can either embed the video (oembed),
+embed the video (iframe) or link to the video (url).
+
+### File
+
+* **url**          - this is a URL to the file that can be retrieved without requiring any additional authentication (no sessions, cookies, etc.)
+* **text**         - the filename
+* **content_type** - content or MIME type of the file to be retrieved
+
+### IFrame
+
+* **url**    - this is used as the 'src' attribute of the embedded iframe
+* **title**  - this is used as the 'title' attribute of the embedded iframe
+* **width**  - this is used as the 'width' style of the embedded iframe
+* **height** - this is used as the 'height' style of the embedded iframe
+
+### Image URL
+
+* **url**    - this is used as the 'src' attribute of the embedded image tag
+* **text**   - this is used as the 'alt' attribute of the embedded image tag
+* **width**  - this is used as the 'width' style of the embedded image tag
+* **height** - this is used as the 'height' style of the embedded image tag
+
+### OEmbed
+
+* **url**      - this is the oEmbed resource URL
+* **endpoint** - this is the oEmbed API endpoint URL
+
+### URL
+
+* **url**    - The url. Likely used as the 'href' attribute of the inserted link
+* **text**   - this is the suggested text for the inserted link. If the user has already selected 
+               some content before opening this dialog, the link will wrap that content and this 
+               value may be ignored
+* **title**  - this is used as the 'title' attribute of the inserted link
+* **target** - this is used as the 'target' attribute of the inserted link
+
+## Drivers
+
+A driver in this context is a ruby class which performs requests and returns a response.
+
+### Vimeo
+
+To use the Vimeo API, you must have credentials already. This requires a Vimeo app to
+be registered. You can do it at [https://developer.vimeo.com/apps](https://developer.vimeo.com/apps). 
+There are 4 params which are necessary to perform the requests: 
+
+| Name                | Required? | Description 
+| ------------------- |:---------:| ------------- 
+| consumer_key        |    Yes    | Vimeo API Client ID 
+| consumer_secret     |    Yes    | Vimeo API Client Secret
+| access_token        |    Yes    | Vimeo API OAuth Access Token
+| access_token_secret |    Yes    | Vimeo API OAuth Access Token Secret
+
+#### Return Types
+
+Vimeo returns **Iframe** and **URL** return types.
+
+#### Example:
+
+```ruby
+criteria = APR::RequestCriteria.new( query: "education" )
+
+vimeo = APR::Drivers::Vimeo.new(
+  :consumer_key        => 'VIMEO_CONSUMER_KEY',
+  :consumer_secret     => 'VIMEO_CONSUMER_SECRET',
+  :access_token        => 'VIMEO_ACCESS_TOKEN',
+  :access_token_secret => 'VIMEO_ACCESS_TOKEN_SECRET'
+)
+
+results = vimeo.perform_request( criteria )
+results.items.length          # => 25
+results.total_items           # => 145063
+results.next_criteria         # => #<ActivePublicResources::RequestCriteria:0x007fa48392d388 @query="education", @page=2, @per_page=25>
+results.items.first.title     # => "Kynect 'education'"
+
+more_results = vimeo.perform_request( results.next_criteria )
+# ...
+```
+
+### YouTube
+
+There are no credentials needed to query YouTube.
+
+#### Return Types
+
+YouTube returns **Iframe** and **URL** return types.
+
+#### Example:
+
+```ruby
+criteria = APR::RequestCriteria.new( query: "education" )
+
+youtube = APR::Drivers::Youtube.new
+
+results = youtube.perform_request( criteria )
+results.items.length          # => 25
+results.total_items           # => 1000000
+results.next_criteria         # => #<ActivePublicResources::RequestCriteria:0x007fa48392d388 @query="education", @page=2, @per_page=25>
+results.items.first.title     # => "Why I Hate School But Love Education||Spoken Word"
+
+more_results = youtube.perform_request( results.next_criteria )
+# ...
+```
+
+### SchoolTube
+
+There are no credentials needed to query SchoolTube.
+
+#### Return Types
+
+SchoolTube returns **Iframe** and **URL** return types.
+
+#### Example:
+
+```ruby
+criteria = APR::RequestCriteria.new( query: "education" )
+
+schooltube = APR::Drivers::Schooltube.new
+
+results = schooltube.perform_request( criteria )
+results.items.length          # => 25
+results.total_items           # => nil (API does not offer total items)
+results.next_criteria         # => #<ActivePublicResources::RequestCriteria:0x007fa48392d388 @query="education", @page=2, @per_page=25>
+results.items.first.title     # => "Fun - Educational School Trips - Call American Tours & Travel"
+
+more_results = schooltube.perform_request( results.next_criteria )
+# ...
+```
+
+### Quizlet
+
+Quizlet requires and Client ID to perform API requests. You can get this by visiting
+[https://quizlet.com/api-dashboard](https://quizlet.com/api-dashboard).
+
+| Name      | Required? | Description 
+| --------- |:---------:| ------------- 
+| client_id |    Yes    | Quizlet Client ID (used for public and user access)
+
+#### Return Types
+
+Quizlet returns **Iframe** and **URL** return types.
+
+#### Example:
+
+```ruby
+criteria = APR::RequestCriteria.new( query: "education" )
+
+quizlet = APR::Drivers::Quizlet.new(
+  :client_id => 'rTHYaHnXTz'
+)
+
+results = quizlet.perform_request( criteria )
+results.items.length          # => 25
+results.total_items           # => 5001
+results.next_criteria         # => #<ActivePublicResources::RequestCriteria:0x007fa48392d388 @query="education", @page=2, @per_page=25>
+results.items.first.title     # => "Education"
+
+results.items.first.return_types.map(&:url)
+# => [ "http://quizlet.com/8572574/education-flash-cards/",
+       "https://quizlet.com/8572574/flashcards/embedv2",
+       "https://quizlet.com/8572574/learn/embedv2",
+       "https://quizlet.com/8572574/scatter/embedv2",
+       "https://quizlet.com/8572574/speller/embedv2",
+       "https://quizlet.com/8572574/test/embedv2",
+       "https://quizlet.com/8572574/spacerace/embedv2" ]
+
+more_results = quizlet.perform_request( results.next_criteria )
+...
+```
+
+## Testing
+
+Tests can be run with the rake task `spec`
+
+    $ rake spec
+
+If you would like to test actual live API's you can do so as well. You need to
+create the file `active_public_resources_config.yml` and populate it with actual
+credentials for the different services. Once that is done, run the following
+command:
+
+    $ rspec --tag live_api
+
+This will run much slower because it is hitting the live API's, but a pass on these
+tests means everything is working great!
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec
+task :test => :spec

data/active_public_resources.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_public_resources/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "active_public_resources"
+  spec.version       = ActivePublicResources::VERSION
+  spec.authors       = ["Eric Berry"]
+  spec.email         = ["cavneb@gmail.com"]
+  spec.description   = %q{ Normalized searching and browsing of public resources }
+  spec.summary       = %q{ Normalized searching and browsing of public resources }
+  spec.homepage      = "https://github.com/instructure/active_public_resources"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "active_support", ">= 3.0.0"
+
+  # Drivers
+  spec.add_dependency "vimeo", "~> 1.5.3"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+end

data/active_public_resources_config.yml.example

@@ -0,0 +1,10 @@
+vimeo:
+  consumer_key: VIMEO_CONSUMER_KEY
+  consumer_secret: VIMEO_CONSUMER_SECRET
+  access_token: VIMEO_ACCESS_TOKEN
+  access_token_secret: VIMEO_ACCESS_TOKEN_SECRET
+youtube:
+schooltube:
+khan_academy:
+quizlet:
+  client_id: QUIZLET_CLIENT_ID

data/lib/active_public_resources/base_response_type.rb

@@ -0,0 +1,11 @@
+module ActivePublicResources
+  module ResponseTypes
+    class BaseResponseType
+      attr_accessor :id, :title, :description, :return_types
+
+      def initialize
+        @return_types = []
+      end
+    end
+  end
+end

data/lib/active_public_resources/base_return_type.rb

@@ -0,0 +1,17 @@
+module ActivePublicResources
+  module ReturnTypes
+    class BaseReturnType
+      attr_accessor :url
+
+      def initialize(args)
+        args.each do |k,v|
+          instance_variable_set("@#{k}", v) unless v.nil?
+        end
+      end
+
+      def return_type
+        raise NotImplementedError.new("You must implement return_type.")
+      end
+    end
+  end
+end

data/lib/active_public_resources/client.rb

@@ -0,0 +1,22 @@
+module ActivePublicResources
+  class Client
+    def initialize(config={})
+      raise ArgumentError.new("key/value pair must be provided") if config.blank?
+
+      @drivers = {}
+      ActivePublicResources.symbolize_keys(config).each do |k, v|
+        klass = "ActivePublicResources::Drivers::#{k.to_s.split('_').map(&:capitalize).join}".constantize
+        @drivers[k] = (v.present? ? klass.new(v) : klass.new)
+      end
+    end
+
+    def perform_request(driver_name, request_criteria)
+      @drivers[driver_name.to_sym].perform_request(request_criteria)
+    end
+
+    def initialized_drivers
+      @drivers.keys
+    end
+
+  end
+end

data/lib/active_public_resources/driver.rb

@@ -0,0 +1,21 @@
+module ActivePublicResources
+  module Drivers
+    class Driver
+      
+      def perform_request(*args)
+        raise NotImplementedError.new("You must implement perform_request.")
+      end
+
+      protected
+
+      def validate_options(opts, req=[])
+        req.each do |k|
+          if opts.blank? || opts[k].blank?
+            raise ArgumentError.new("must include #{req.join(', ')}, instead received #{opts.inspect}")
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/active_public_resources/driver_response.rb

@@ -0,0 +1,15 @@
+module ActivePublicResources
+  module Drivers
+    class DriverResponse
+      attr_accessor :items, :criteria, :next_criteria, :total_items
+
+      def initialize(args)
+        args.each do |k,v|
+          instance_variable_set("@#{k}", v) unless v.nil?
+        end
+        @items ||= []
+      end
+
+    end
+  end
+end