aj-ims-lti 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9f32c54ad351ceea8603402a48cb3f7c0c5314469a569595a548d1fe80f50a8
+  data.tar.gz: 44257dc66d6311cc408ffd5a3dab25efb8f69bff75c7ee17e998574879500966
+SHA512:
+  metadata.gz: 44861b8a0a8d07907568019d8355bfc6e01e046f4a8a98990a0d1924a2c82b0aeeb73a66b002487dbcd65c732bd6aa8cc8fa36223a0ff370aa01261a594499ea
+  data.tar.gz: 40d50fb420bd0128e291593ab56a0a09c02f2b8677afae0a4a28900b04f73b3529c3a419aaf7aff6a195ab2f6a277cea9257857ba5e80fccf9ec3a1519a977ed

data/Changelog

@@ -0,0 +1,34 @@
+2013-04-24 Version 1.1.3
+
+    * Corrected lti_version launch parameter
+
+2012-09-05 Version 1.1.2
+
+    * Added better role checking and convenience methods
+
+2012-09-04 Version 1.1.1
+
+    * Added cdata value for outcome data extension
+
+2012-08-14 Version 1.1.0
+
+    * Added framework for LTI extensions
+    * Added LTI outcome data extension
+    * Fix tests reliant on random ordering
+    * Add rails 3 note to readme install docs
+    * Create Changelog
+    
+
+2012-03-14 Version 1.0.2
+
+    * Refactor OAuth validation into its own module
+    
+    
+2012-03-13 Version 1.0.1
+
+    * Add gem dependencies to gemspec
+
+
+2012-03-11 Version 1.0.0
+
+    * Publish fully functional and operational IMS LTI library

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2012 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,117 @@
+# AJ IMS LTI
+
+This ruby library is to help create Tool Providers and Tool Consumers for the
+[IMS LTI standard](http://www.imsglobal.org/lti/index.html).
+
+Nearly a fork of the Instructure IMS LTI gem. Top level namespace has been
+changed in order to allow concurrent use of Instructure IMS LTI gem, and this
+gem. Instructure has expressed disinterest in supporting grade writeback, which
+this version of the gem does support.
+
+## Installation
+This is packaged as the `aj-ims-lti` rubygem, so you can just add the dependency to
+your Gemfile or install the gem on your system:
+
+    gem install aj-ims-lti
+
+To require the library in your project:
+
+    require 'ajims/lti'
+
+To validate the OAuth signatures you need to require the appropriate request
+proxy for your application. For example:
+
+    # For a Sinatra or a Rails 3 app:
+    require 'oauth/request_proxy/rack_request'
+    # You also need to explicitly enable OAuth 1 support in the environment.rb or an initializer:
+    OAUTH_10_SUPPORT = true
+
+    # For a Rails 2.3 app:
+    require 'oauth/request_proxy/action_controller_request'
+
+For further information see the [oauth-ruby](https://github.com/oauth-xx/oauth-ruby) project.
+
+## Usage
+This readme won't cover the LTI standard, just how to use the library. It will be
+very helpful to read the [LTI documentation](http://www.imsglobal.org/lti/index.html)
+
+In LTI there are Tool Providers (TP) and Tool Consumers (TC), this library is
+useful for implementing both. Here is an overview of the communication process:
+[LTI 1.1 Introduction](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649680)
+
+This library doesn't help you manage the consumer keys and secrets. The POST
+headers/parameters will contain the `oauth_consumer_key` and your app can use
+that to look up the appropriate `oauth_consumer_secret`.
+
+Your app will also need to manage the OAuth nonce to make sure the same nonce
+isn't used twice with the same timestamp. [Read the LTI documentation on OAuth](http://www.imsglobal.org/LTI/v1p1pd/ltiIMGv1p1pd.html#_Toc309649687).
+
+### Tool Provider
+As a TP your app will receive a POST request with a bunch of
+[LTI launch data](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684)
+and it will be signed with OAuth using a key/secret that both the TP and TC share.
+This is covered in the [LTI security model](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649685)
+
+Here is an example of a simple TP Sinatra app using this gem:
+[LTI Tool Provider](https://github.com/instructure/lti_tool_provider_example)
+
+Once you find the `oauth_consumer_secret` based on the `oauth_consumer_key` in
+the request, you can initialize a `ToolProvider` object with them and the post parameters:
+
+```ruby
+# Initialize TP object with OAuth creds and post parameters
+provider = AJIMS::LTI::ToolProvider.new(consumer_key, consumer_secret, params)
+
+# Verify OAuth signature by passing the request object
+if provider.valid_request?(request)
+  # success
+else
+  # handle invalid OAuth
+end
+```
+
+Once your TP object is initialized and verified you can load your tool. All of the
+[launch data](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684)
+is available in the TP object along with some convenience methods like `provider.username`
+which will try to find the name from the 3 potential name launch data attributes.
+
+#### Returning Results of a Quiz/Assignment
+If your TP provides some kind of assessment service you can write grades back to
+the TC. This is documented in the LTI docs [here](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649690).
+
+You can check whether the TC is expecting a grade write-back:
+
+```ruby
+if provider.outcome_service?
+  # ready for grade write-back
+else
+  # normal tool launch without grade write-back
+end
+```
+
+To write the grade back to the TC your tool will do a POST directly back to the
+URL the TC passed in the launch data. You can use the TP object to do that for you:
+
+```ruby
+# post the score to the TC, score should be a float >= 0.0 and <= 1.0
+# this returns an OutcomeResponse object
+response = provider.post_replace_result!(score)
+if response.success?
+  # grade write worked
+elsif response.processing?
+elsif response.unsupported?
+else
+  # failed
+end
+```
+
+You can see the error code documentation
+[here](http://www.imsglobal.org/gws/gwsv1p0/imsgws_baseProfv1p0.html#1639667).
+
+### Tool Consumer
+As a Tool Consumer your app will POST an OAuth-signed launch requests to TPs with the necessary
+[LTI launch data](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649684).
+This is covered in the [LTI security model](http://www.imsglobal.org/lti/v1p1pd/ltiIMGv1p1pd.html#_Toc309649685)
+
+Here is an example of a simple TC Sinatra app using this gem:
+[LTI Tool Consumer](https://github.com/instructure/lti_tool_consumer_example)

data/lib/ajims.rb

@@ -0,0 +1 @@
+require 'ajims/lti'

data/lib/ajims/lti.rb

@@ -0,0 +1,51 @@
+require 'oauth'
+require 'builder'
+require "rexml/document"
+require 'uuid'
+require 'cgi'
+
+module AJIMS # :nodoc:
+
+  # :main:IMS::LTI
+  # LTI is a standard defined by IMS for creating eduction Tool Consumers/Providers.
+  # LTI documentation: http://www.imsglobal.org/lti/index.html
+  #
+  # When creating these tools you will work primarily with the ToolProvider and
+  # ToolConsumer classes.
+  #
+  # For validating OAuth request be sure to require the necessary proxy request
+  # object. See IMS::LTI::RequestValidator#valid_request? for more documentation.
+  #
+  # == Installation
+  # This is packaged as the `ims-lti` rubygem, so you can just add the dependency to
+  # your Gemfile or install the gem on your system:
+  #
+  #    gem install ims-lti
+  #
+  # To require the library in your project:
+  #
+  #    require 'ims/lti'
+  module LTI
+    
+    # The versions of LTI this library supports
+    VERSIONS = %w{1.0 1.1}
+    
+    class InvalidLTIConfigError < StandardError
+    end
+
+    # Generates a unique identifier
+    def self.generate_identifier
+      UUID.new
+    end
+  end
+end
+
+require 'ajims/lti/exceptions'
+require 'ajims/lti/extensions'
+require 'ajims/lti/launch_params'
+require 'ajims/lti/request_validator'
+require 'ajims/lti/tool_provider'
+require 'ajims/lti/tool_consumer'
+require 'ajims/lti/outcome_request'
+require 'ajims/lti/outcome_response'
+require 'ajims/lti/tool_config'

data/lib/ajims/lti/exceptions.rb

@@ -0,0 +1,15 @@
+module AJIMS::LTI
+  class XmlParseException < StandardError
+    attr_reader :original_exception, :content
+    def initialize(content, msg = "Failed to parse XML")
+      super(msg)
+      @content = content
+    end
+
+    def to_s
+      error = super
+      error << "\nDOCUMENT:\n#{@content}\nEND OF DOCUMENT\n"
+      error
+    end
+  end
+end

data/lib/ajims/lti/extensions.rb

@@ -0,0 +1,45 @@
+
+module AJIMS::LTI
+  module Extensions
+    
+    # Base functionality for creating LTI extension modules
+    # See the test for this class for a simple example of how to create an extension module
+    module Base
+      def outcome_request_extensions
+        []
+      end
+      
+      def outcome_response_extensions
+        []
+      end
+      
+      def extend_outcome_request(request)
+        outcome_request_extensions.each do |ext|
+          request.extend(ext)
+        end
+        request
+      end
+      
+      def extend_outcome_response(response)
+        outcome_response_extensions.each do |ext|
+          response.extend(ext)
+        end
+        response
+      end
+    end
+
+    module ExtensionBase
+      def outcome_request_extensions
+        super
+      end
+
+      def outcome_response_extensions
+        super
+      end
+    end
+  end
+end
+
+require 'ajims/lti/extensions/outcome_data'
+require 'ajims/lti/extensions/content'
+require 'ajims/lti/extensions/canvas'

data/lib/ajims/lti/extensions/canvas.rb

@@ -0,0 +1,122 @@
+module AJIMS::LTI
+  module Extensions
+    # Module that adds Canvas specific LTI extensions
+    #
+    # It adds convenience methods for generating common canvas use case LTI configurations
+    #
+    # == Usage
+    # To generate an XML configuration:
+    #
+    #    # Create a config object and set some options
+    #    tc = IMS::LTI::ToolConfig.new(:title => "Example Sinatra Tool Provider", :launch_url => url)
+    #    tc.description = "This example LTI Tool Provider supports LIS Outcome pass-back."
+    #
+    #    # Extend the Canvas Tool config and add canvas related extensions
+    #    tc.extend IMS::LTI::Extensions::Canvas::ToolConfig
+    #    tc.homework_submission! 'http://someplace.com/homework', 'Find Homework'
+    #
+    #    # generate the XML
+    #    tc.to_xml
+    #
+    # Or to create a config object from an XML String:
+    #
+    #    tc = IMS::LTI::ToolConfig.create_from_xml(xml)
+
+    module Canvas
+      module ToolConfig
+        PLATFORM = 'canvas.instructure.com'
+
+        # Canvas extension defaults
+        # These properties will cascade down to any options that are configured
+        def set_canvas_ext_param(key, value)
+          set_ext_param(PLATFORM, key, value)
+        end
+
+        def get_canvas_param(param_key)
+          get_ext_param PLATFORM, param_key
+        end
+
+        def canvas_privacy_public!()
+          set_canvas_ext_param(:privacy_level, 'public')
+        end
+
+        def canvas_privacy_name_only!()
+          set_canvas_ext_param(:privacy_level, 'name_only')
+        end
+
+        def canvas_privacy_anonymous!()
+          set_canvas_ext_param(:privacy_level, 'anonymous')
+        end
+
+        def canvas_domain!(domain)
+          set_canvas_ext_param(:domain, domain)
+        end
+
+        def canvas_text!(text)
+          set_canvas_ext_param(:text, text)
+        end
+
+        def canvas_icon_url!(icon_url)
+          set_canvas_ext_param(:icon_url, icon_url)
+        end
+
+        def canvas_tool_id!(tool_id)
+          set_canvas_ext_param(:tool_id, tool_id)
+        end
+
+        def canvas_selector_dimensions!(width, height)
+          set_canvas_ext_param(:selection_width, width)
+          set_canvas_ext_param(:selection_height, height)
+        end
+
+        # Canvas options
+        # These configure canvas to expose the tool in various locations.  Any properties that are set
+        # at this level will override the defaults for this launch of the tool
+
+        # Enables homework submissions via the tool
+        # Valid properties are url, text, selection_width, selection_height, enabled
+        def canvas_homework_submission!(params = {})
+          set_canvas_ext_param(:homework_submission, params)
+        end
+
+        # Adds the tool to canvas' rich text editor
+        # Valid properties are url, icon_url, text, selection_width, selection_height, enabled
+        def canvas_editor_button!(params = {})
+          set_canvas_ext_param(:editor_button, params)
+        end
+
+        # Adds the tool to canvas' resource selector
+        # Valid properties are url, text, selection_width, selection_height, enabled
+        def canvas_resource_selection!(params = {})
+          set_canvas_ext_param(:resource_selection, params)
+        end
+
+        # Adds the tool to account level navigation in canvas
+        # Valid properties are url, text, enabled
+        def canvas_account_navigation!(params = {})
+          set_canvas_ext_param(:account_navigation, params)
+        end
+
+        # Adds the tool to course level navigation in canvas
+        # Valid properties are url, text, visibility, default, enabled
+        # Visibility describes who will see the navigation element.  Possible values are "admins", "members", and nil
+        # Default determines if it is on or off by default.  Possible values are "admins", "members", and nil
+        def canvas_course_navigation!(params = {})
+          set_canvas_ext_param(:course_navigation, params)
+        end
+
+        # Adds the tool to user level navigation in canvas
+        # Valid properties are url, text, enabled
+        def canvas_user_navigation!(params = {})
+          set_canvas_ext_param(:user_navigation, params)
+        end
+
+        # Adds canvas environment configurations options
+        # Valid properties are launch_url, domain, test_launch_url, test_domain, beta_launch_url, beta_domain
+        def canvas_environments!(params = {})
+          set_canvas_ext_param(:environments, params)
+        end
+      end
+    end
+  end
+end

data/lib/ajims/lti/extensions/content.rb

@@ -0,0 +1,209 @@
+module AJIMS::LTI
+  module Extensions
+
+    # An LTI extension that adds support for content back to the consumer
+    #
+    #     # Initialize TP object with OAuth creds and post parameters
+    #     provider = IMS::LTI::ToolProvider.new(consumer_key, consumer_secret, params)
+    #     # add extension
+    #     provider.extend IMS::LTI::Extensions::Content::ToolProvider
+    #
+    # If the tool was launched as an content request and it supports the content extension
+    # you can redirect the user to the tool consumer using the return url helper methods.
+    # The tool consumer is then responsible for consuming the content.
+    #
+    #     #Check if a certain response type is available
+    #     if provider.accepts_url? do
+    #       #Generate the URL for the user
+    #       redirect provider.url_content_return_url(url)
+    #     end
+    #
+    module Content
+      module ToolProvider
+        include AJIMS::LTI::Extensions::ExtensionBase
+        include Base
+
+        # a list of the supported outcome data types
+        def accepted_content_types
+          return @content_types if @content_types
+          @content_types = []
+          if val = @ext_params["content_return_types"]
+            @content_types = val.split(',').map {|i| i.to_sym}
+          end
+
+          @content_types
+        end
+
+        def accepted_file_extensions
+          return @file_extensions if @file_extensions
+          @file_extensions = []
+          if val = @ext_params["content_file_extensions"]
+            @file_extensions = val.split(',').map {|i| i.downcase.strip}
+          end
+
+          @file_extensions
+        end
+
+        def accepts_file?(file_name = nil)
+          accepted_content_types.include?(:file) &&
+            ( file_name.nil? ||
+              accepted_file_extensions.empty? ||
+              accepted_file_extensions.any?{|ext| file_name.downcase[/#{ext}$/]} )
+        end
+
+        def accepts_url?
+          accepted_content_types.include?(:url)
+        end
+
+        def accepts_lti_launch_url?
+          accepted_content_types.include?(:lti_launch_url)
+        end
+
+        def accepts_image_url?
+          accepted_content_types.include?(:image_url)
+        end
+
+        def accepts_iframe?
+          accepted_content_types.include?(:iframe)
+        end
+
+        def accepts_oembed?
+          accepted_content_types.include?(:oembed)
+        end
+
+        def content_intended_use
+          @ext_params["content_intended_use"].to_sym if  @ext_params["content_intended_use"]
+        end
+
+        # check if the content extension is supported
+        def accepts_content?
+          !!@ext_params["content_return_types"]
+        end
+
+        # check if the consumer accepts a given type of content
+        def accepts_content_type?(content_type)
+          accepted_content_types.include? content_type.to_sym
+        end
+
+        #check the use of the content
+        def is_content_for? (intended_use)
+          content_intended_use == intended_use
+        end
+
+        def content_return_url
+          @ext_params["content_return_url"]
+        end
+
+        #generates the return url for file submissions
+        def file_content_return_url(url, text, content_type = nil)
+          url = CGI::escape(url)
+          text = CGI::escape(text)
+          content_type = CGI::escape(content_type) if content_type
+
+          return_url = "#{content_return_url}?return_type=file&url=#{url}&text=#{text}"
+          return_url = "#{return_url}&content_type=#{content_type}" if content_type
+
+          return return_url
+        end
+
+        #generates the return url for url submissions
+        def url_content_return_url(url, title = nil, text = 'link', target = '_blank')
+          url = CGI::escape(url)
+          text = CGI::escape(text)
+          target = CGI::escape(target)
+
+          return_url = "#{content_return_url}?return_type=url&url=#{url}&text=#{text}&target=#{target}"
+          return_url = "#{return_url}&title=#{CGI::escape(title)}" if title
+
+          return return_url
+        end
+
+        #generates the return url for lti launch submissions
+        def lti_launch_content_return_url(url, text='link', title=nil)
+          url = CGI::escape(url)
+          text = CGI::escape(text)
+
+          return_url = "#{content_return_url}?return_type=lti_launch_url&url=#{url}&text=#{text}"
+          return_url = "#{return_url}&title=#{CGI::escape(title)}" if title
+
+          return return_url
+        end
+
+        #generates the return url for image submissions
+        def image_content_return_url(url, width, height, alt = '')
+          url = CGI::escape(url)
+          width = CGI::escape(width.to_s)
+          height = CGI::escape(height.to_s)
+          alt = CGI::escape(alt)
+
+          "#{content_return_url}?return_type=image_url&url=#{url}&width=#{width}&height=#{height}&alt=#{alt}"
+        end
+
+        #generates the return url for iframe submissions
+        def iframe_content_return_url(url, width, height, title = nil)
+          url = CGI::escape(url)
+          width = CGI::escape(width.to_s)
+          height = CGI::escape(height.to_s)
+
+          return_url = "#{content_return_url}?return_type=iframe&url=#{url}&width=#{width}&height=#{height}"
+          return_url = "#{return_url}&title=#{CGI::escape(title)}" if title
+
+          return return_url
+        end
+
+        #generates the return url for oembed submissions
+        def oembed_content_return_url(url, endpoint)
+          url = CGI::escape(url)
+          endpoint = CGI::escape(endpoint)
+
+          "#{content_return_url}?return_type=oembed&url=#{url}&endpoint=#{endpoint}"
+        end
+      end
+
+      module ToolConsumer
+        include AJIMS::LTI::Extensions::ExtensionBase
+        include Base
+        
+        # a list of the content types accepted
+        #
+        #    tc.add_content_return_types=(['url', 'text'])
+        #    tc.add_content_return_types=("url,text")
+        def content_return_types=(val)
+          val = val.join(',') if val.is_a? Array
+          set_ext_param('content_return_types', val)
+        end
+
+        # a comma-separated string of the supported outcome data types
+        def content_return_types
+          get_ext_param('content_return_types')
+        end
+
+        def content_intended_use=(val)
+          set_ext_param('content_intended_use', val)
+        end
+
+        def content_intended_use
+          get_ext_param('content_intended_use')
+        end
+
+        # convenience method for setting support for homework content
+        def support_homework_content!
+          self.content_intended_use = 'homework'
+          self.content_return_types = 'file,url'
+        end
+
+        # convenience method for setting support for embed content
+        def support_embed_content!
+          self.content_intended_use = 'embed'
+          self.content_return_types = 'oembed,lti_launch_url,url,image_url,iframe'
+        end
+
+        # convenience method for setting support for navigation content
+        def support_navigation_content!
+          self.content_intended_use = 'navigation'
+          self.content_return_types = 'lti_launch_url'
+        end
+      end
+    end
+  end
+end