RubyGems - learnosity-sdk - Versions diffs - 0.2.1 → 0.2.2 - Mend

learnosity-sdk 0.2.1 → 0.2.2

Files changed (118) hide show

data/REFERENCE.md ADDED Viewed

@@ -0,0 +1,249 @@
+# Learnosity Ruby-SDK: Reference Guide
+## Usage
+Some usage examples can be found in the `examples/simple` subdirectory. A working Rails project can be found under `docs/quickstart/lrn-sdk-rails/`.
+### Init
+This class generates and signs init options for all supported APIs. Its
+constructor takes four mandatory arguments, and one optional argument.
+- `service`: the name of the API to sign initialisation options for,
+- `security_packet`: a hash with at least the `consumer_key`, optionally the
+  `domain` and `timestamp`; `user_id` is also mandatory for Questions API,
+- `consumer_secret`
+- `request`: the request you want to get a signature for
+- `action` [Data API only]: the action of your request, either `get` or `post`
+The `Init#generate` method can then be used to generate the options. By default,
+it will generate a JSON string. It however takes one parameter, `encode` which,
+if false, will simply return a native Ruby Hash with the signed options.
+Given your consumer key and secret, and the request you want to run against,
+say, the `items` API, you just need to instantiate the
+`Learnosity::Sdk::Request::Init`, and call its `generate` method.
+```ruby
+require "learnosity/sdk/request/init"
+security_packet = {
+    # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key.
+    # Add the demo consumer key and secret to application.rb in your Rails project: docs/quickstart/lrn-sdk-rails/config/
+    # application.rb -- this path shows a file from the quick start example project, which is explained in README.md.
+    'consumer_key'   => Rails.configuration.consumer_key,
+    'domain'         => 'localhost'
+}
+# XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked into version control.
+# Add the demo consumer key and secret to application.rb in your Rails project: docs/quickstart/lrn-sdk-rails/config/
+# application.rb -- this path shows a file from the quick start example project, which is explained in README.md.
+consumer_secret = Rails.configuration.consumer_secret
+items_request = { 'limit' => 50 }
+init = Learnosity::Sdk::Request::Init.new(
+        'items',
+        security_packet,
+        consumer_secret,
+        items_request
+)
+puts init.generate
+```
+This will return a string of signed options suitable for initialisation of
+the API.
+```html
+<html>
+    <head>
+    </head>
+    <body>
+	    <script src="//items.learnosity.com/"></script>
+	    <script>
+	    var itemsApp = LearnosityItems.init(INSERT OPTIONS HERE);
+	    </script>
+    </body>
+</html>
+```
+### Data API
+When the `service` parameter is `data`, the `action` parameter is mandatory.
+Moreover, `Init#generate`'s `encode` parameter is ignored, and a native Ruby Hash
+with the signed options is unconditionally returned, for use with your favourite
+HTTP library (note that, regardless of the `action` parameter, you should always
+send `POST` requests).
+```ruby
+require 'net/http'
+require "learnosity/sdk/request/init"
+security_packet = {
+    # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key.
+    # Add the demo consumer key and secret to application.rb in your Rails project: docs/quickstart/lrn-sdk-rails/config/
+    # application.rb -- this path shows a file from the quick start example project, which is explained in README.md.
+    'consumer_key'   => Rails.configuration.consumer_key,
+    'domain'         => 'localhost'
+}
+# XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked into version control.
+# Add the demo consumer key and secret to application.rb in your Rails project: docs/quickstart/lrn-sdk-rails/config/
+# application.rb -- this path shows a file from the quick start example project, which is explained in README.md.
+consumer_secret = Rails.configuration.consumer_secret
+data_request = { 'limit' => 50 }
+init = Learnosity::Sdk::Request::Init.new(
+        'data',
+        security_packet,
+        consumer_secret,
+        data_request,
+	'get'
+)
+request = init.generate
+Net::HTTP.post_form URI('https://data.learnosity.com/v1/itembank/items'), request
+```
+### Recursive Queries
+tl;dr: not currently implemented
+Some requests are paginated to the `limit` passed in the request, or some
+server-side default. Responses to those requests contain a `next` parameter in
+their `meta` property, which can be placed in the next request to access another
+page of data.
+For the time being, you can iterate through pages by looping over the
+`Init#new`/`Init#generate`/`Net::HTTP#post_form`, updating the `next` attribute
+in the request.
+```ruby
+response = JSON.parse(res.body)
+if ( !response['meta']['next'].nil? \
+		and !response['meta']['records'].nil? and response['meta']['records'] > 0)
+	data_request['next'] = response['meta']['next']
+end
+```
+This will `require 'json'` to be able to parse the response.
+See `examples/simple/init_data.rb` for an example.
+### Generating UUIDs
+You will need to generate UUIDs. You can use the Ruby `securerandom`
+module for this purpose.
+```ruby
+require 'securerandom'
+p SecureRandom.uuid
+```
+### Rails
+You can bootstrap a Ruby-on-Rails project using this SDK by doing the
+following.
+Note, this is a quick 0 to 100 in 10s examples of how to use this
+SDK with Rails. As such, it takes many unwise shortcuts in the architecture of
+the app; do not take this as the example of a good Rails app.
+First, generate a skeleton project
+    rails new lrn-sdk-rails
+    cd lrn-sdk-rails
+Add the `learnosity-sdk` as a dependency to this project
+    echo "gem 'learnosity-sdk' >> Gemfile
+    bundle install
+Create a default controller
+    rails generate controller Index index
+Add the `require` for the SDK at the top of the newly created controller,
+`app/controllers/index_controller.rb`, and insert the assessment configuration
+there (taken from [items-api-demo](examples/simple/init_items.rb), and truncated for legibility). Add the demo
+consumer key and secret to [[application.rb](docs/quickstart/lrn-sdk-rails/config/application.rb) (link shows the file from the quick start example, which is referenced in [README.md](README.md)).
+```ruby
+require 'learnosity/sdk/request/init'
+class IndexController < ApplicationController
+  @@security_packet = {
+    # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key.
+    # Add the demo consumer key and secret to application.rb in your Rails project: docs/quickstart/lrn-sdk-rails/config/
+    # application.rb -- this path shows a file from the quick start example project, which is explained in README.md.
+    'consumer_key'   => Rails.configuration.consumer_key,
+    'domain'         => 'localhost'
+  }
+# XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked into version control.
+# Add the demo consumer key and secret to application.rb in your Rails project: docs/quickstart/lrn-sdk-rails/config/
+# application.rb -- this path shows a file from the quick start example project, which is explained in README.md.
+consumer_secret = Rails.configuration.consumer_secret
+  @@items_request = {
+	[...]
+  }
+  def index
+    init = Learnosity::Sdk::Request::Init.new(
+      'items',
+      @@security_packet,
+      @@consumer_secret,
+      @@items_request
+    )
+  end
+end
+```
+Add the HTML/Javascript boilerplate to the view, `app/views/index/index.html.erb`
+```erb
+<h1>Index#index</h1>
+<div id="learnosity_assess"></div>
+<script src="//items.learnosity.com"></script>
+<script>
+  var eventOptions = {
+    readyListener: init
+  },
+    itemsApp = LearnosityItems.init(<%= raw(@init.generate) %>);
+  function init () {
+    var assessApp = itemsApp.assessApp();
+    assessApp.on('item:load', function () {
+      console.log('Active item:', getActiveItem(this.getItems()));
+    });
+    assessApp.on('test:submit:success', function () {
+      toggleModalClass();
+    });
+  }
+</script>
+```
+Finally, you can serve the project with
+    rails server
+It will become available at http://localhost:3000/index/index
+For reference you can find the result of these steps in
+`docs/quickstart/lrn-sdk-rails/`.
+## Further reading
+Thanks for reading to the end! Find more information about developing an app with Learnosity on our documentation sites:
+<ul>
+<li><a href="http://help.learnosity.com">help.learnosity.com</a> -- general help portal and tutorials,
+<li><a href="http://reference.learnosity.com">reference.learnosity.com</a> -- developer reference site, and
+<li><a href="http://authorguide.learnosity.com">authorguide.learnosity.com</a> -- authoring documentation for content creators.
+</ul>
+Back to [README.md](README.md)

data/Rakefile CHANGED Viewed

@@ -1,6 +1,15 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "./lib/learnosity/sdk/version"
 RSpec::Core::RakeTask.new(:spec)
 task :default => :spec
+task :version do
+    puts Learnosity::Sdk::VERSION
+end
+task :clean do
+    ["Gemfile.lock", ".rspec_status"].each {|f| File.delete(f) rescue nil}
+end

data/docs/images/apache-license.svg ADDED Viewed

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="122" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="a">
+        <rect width="122" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#a)">
+        <rect width="48" height="20" fill="#555"/>
+        <rect x="48" width="74" height="20" fill="#428F7E"/>
+        <rect width="122" height="20" fill="url(#b)"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="25" y="15" fill="#010101" fill-opacity=".3">license</text>
+        <text x="25" y="14">license</text>
+        <text x="84" y="15" fill="#010101" fill-opacity=".3">Apache-2.0</text>
+        <text x="84" y="14">Apache-2.0</text>
+    </g>
+</svg>

data/docs/images/downloads.svg ADDED Viewed

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="132" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="a">
+        <rect width="132" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#a)">
+        <rect width="70" height="20" fill="#555"/>
+        <rect x="70" width="62" height="20" fill="#007ec6"/>
+        <rect width="132" height="20" fill="url(#b)"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="36" y="15" fill="#010101" fill-opacity=".3">downloads</text>
+        <text x="36" y="14">downloads</text>
+        <text x="100" y="15" fill="#010101" fill-opacity=".3">102.49 k </text>
+        <text x="100" y="14">102.49 k </text>
+    </g>
+</svg>

data/docs/images/image-assessment-retrieval.png ADDED Viewed

Binary file

data/docs/images/image-concept-overview.png ADDED Viewed

Binary file

data/docs/images/image-logo-graphic.png ADDED Viewed

Binary file

data/docs/images/image-quickstart-examples-assessment.png ADDED Viewed

Binary file

data/docs/images/image-quickstart-index.png ADDED Viewed

Binary file

data/docs/images/image-signed-request-creation.png ADDED Viewed

Binary file

data/docs/quickstart/css/style.css ADDED Viewed

@@ -0,0 +1,113 @@
+html,
+body,
+.main {
+    padding: 0;
+    margin: 0;
+    color: #333;
+}
+body {
+    height: auto;
+    margin: 20px;
+    font-family: Helvetica, Arial, sans-serif;
+}
+h1, h2, h3, h4, h5, h6 {
+    font-weight: normal;
+    margin: 2em 0 .3em 0;
+    padding: 0;
+}
+h1 { font-size: 2.0em; margin: .3em 0 .3em; }
+h2 { font-size: 1.6em; }
+h3 { font-size: 1.4em; }
+h4 { font-size: 1.2em; }
+h5 { font-size: 1.1em; }
+h6 { font-size: 1.0em; }
+ul {
+    margin-top: 0;
+    margin-bottom: 1em;
+}
+a         { color: #3498DB; }
+a:visited { color: #3498DB; }
+a:hover   { color: #2979AF; }
+.quickstart-index {
+    margin: 0;
+    background-color: #efefef;
+}
+.quickstart-index h1 {
+    padding-bottom: 1em;
+    margin-bottom: 1em;
+    border-bottom: 1px dashed rgba(0, 0, 0, .3);
+}
+.container {
+    padding: 20px;
+}
+.lrn-logo {
+    width: 150px;
+}
+.header-nav,
+.footer-nav {
+    position: fixed;
+    width: 100%;
+}
+.header-nav {
+    top: 0;
+    background-color: #ffffff;
+    border-bottom: 2px solid #222;
+    height: 80px;
+}
+.footer-nav {
+    color: #f3f3f3;
+    background-color: #222;
+    padding: 1em 0;
+    text-align: center;
+    bottom: 0em;
+}
+.footer-nav a {
+    color: #fff;
+    padding: 0 0.5em;
+    text-decoration: none;
+}
+.footer-nav a:hover {
+    color: #ccc;
+    text-decoration: underline;
+}
+.module-block {
+    background: #ffffff;
+    max-width: 800px;
+    margin: 80px auto 40px;
+    padding: 20px;
+}
+.api-list li {
+    margin-top: 1em;
+}
+.api-list p {
+    margin: 3px 0 6px 6px;
+}
+.hero-icon {
+    position: relative;
+    top: 7px;
+    height: 42px;
+    width: 42px;
+    background-repeat: no-repeat;
+    background-position: center;
+    background-size: 80%;
+}
+.li-authorapi {
+    background-image: url(https://docs.learnosity.com/static/img/icons/authorapi.svg);
+}
+.li-itemsapi {
+    background-image: url(https://docs.learnosity.com/static/img/icons/itemsapi.svg);
+}
+.li-reportsapi {
+    background-image: url(https://docs.learnosity.com/static/img/icons/reports.svg);
+}
+.li-dataapi {
+    background-image: url(https://docs.learnosity.com/static/img/icons/dataapi.svg);
+}
+[class^="li-"], [class*=" li-"] {
+    background-color: #0d5786;
+    color: #ffffff;
+    width: 36px;
+    height: 36px;
+    border-radius: 50%;
+    display: inline-block;
+}

data/{examples → docs/quickstart}/lrn-sdk-rails/Gemfile RENAMED Viewed

@@ -11,7 +11,7 @@ gem 'rails', '~> 5.0.2'
 # Use sqlite3 as the database for Active Record
 gem 'sqlite3', '~> 1.3.6'
 # Use Puma as the app server
-gem 'puma', '~> 3.0'
+gem 'puma', '~> 4.3.8'
 # Use SCSS for stylesheets
 gem 'sass-rails', '~> 5.0'
 # Use Uglifier as compressor for JavaScript assets
@@ -54,4 +54,4 @@ gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
 # The :path allows us to use the local code, you'll likely not need that in a
 # normal project
-gem 'learnosity-sdk', :path => '../..'
+gem 'learnosity-sdk', :path => '../../..'

data/docs/quickstart/lrn-sdk-rails/app/controllers/author_controller.rb ADDED Viewed

@@ -0,0 +1,179 @@
+require 'learnosity/sdk/request/init' # Learnosity helper.
+require 'securerandom'
+class AuthorController < ApplicationController
+@@security_packet = {
+    # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key. Set values in application.rb.
+    'consumer_key'   => Rails.configuration.consumer_key,
+    'domain'         => 'localhost',
+    'user_id'        => SecureRandom.uuid
+  }
+  # XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked into version control
+  @@consumer_secret = Rails.configuration.consumer_secret
+  @@author_request =  {
+          "mode"=> "item_edit",
+          "reference"=> "a15ac409-f6d5-42de-a491-a1e4ab03c826",
+          "user"=> {
+              "id" => "brianmoser",
+              "firstname" => "Test",
+              "lastname" => "Test",
+              "email" => "test@test.com"
+          },
+          "config"=> {
+              "global"=> {
+                  "disable_onbeforeunload"=> true,
+                  "hide_tags"=>
+                  [
+                    {
+                      "type"=> "internal_category_uuid"
+                    }
+                  ]
+              },
+              "item_edit"=> {
+                  "item"=> {
+                      "back"=> true,
+                      "columns"=> true,
+                      "answers"=> true,
+                      "scoring"=> true,
+                      "reference"=> {
+                          "edit"=> false,
+                          "show"=> false,
+                          "prefix"=> "LEAR_"
+                      },
+                      "save"=> true,
+                      "status"=> false,
+                      "dynamic_content"=> true,
+                      "shared_passage"=> true
+                  },
+                  "widget"=> {
+                      "delete"=> false,
+                      "edit"=> true
+                  }
+              },
+              "item_list"=> {
+                  "item"=> {
+                      "status"=> true,
+                      "url"=> "http://myApp.com/items/:reference/edit"
+                  },
+                  "toolbar"=> {
+                      "add"=> true,
+                      "browse"=> {
+                        "controls"=> [
+                          {
+                            "type"=> "hierarchy",
+                            "hierarchies"=> [
+                              {
+                                "reference"=> "CCSS_Math_Hierarchy",
+                                "label"=> "CCSS Math"
+                              },
+                              {
+                                "reference"=> "CCSS_ELA_Hierarchy",
+                                "label"=> "CCSS ELA"
+                              },
+                              {
+                                "reference"=> "Demo_Items_Hierarchy",
+                                "label"=> "Demo Items"
+                              }
+                            ]
+                          },
+                          {
+                            "type"=> "tag",
+                            "tag"=> {
+                               "type"=> "Alignment",
+                               "label"=> "def456"
+                            }
+                          },
+                          {
+                            "type"=> "tag",
+                            "tag"=> {
+                               "type"=> "Course",
+                               "label"=> "commoncore"
+                            }
+                          }
+                        ]
+                      }
+                  },
+                  "filter"=> {
+                      "restricted"=> {
+                          "current_user"=> true,
+                          "tags"=> {
+                              "all"=> [
+                                  {
+                                      "type"=> "Alignment",
+                                      "name"=> ["def456", "abc123"]
+                                  },
+                                  {
+                                      "type"=> "Course"
+                                  }
+                              ],
+                              "either"=> [
+                                  {
+                                      "type"=> "Grade",
+                                      "name"=> "4"
+                                  },
+                                  {
+                                      "type"=> "Grade",
+                                      "name"=> "5"
+                                  },
+                                  {
+                                      "type"=> "Subject",
+                                      "name"=> ["Math", "Science"]
+                                  }
+                              ],
+                              "none"=> [
+                                  {
+                                      "type"=> "Grade",
+                                      "name"=> "6"
+                                  }
+                              ]
+                          }
+                      }
+                  }
+              },
+              "dependencies"=> {
+                  "question_editor_api"=> {
+                      "init_options"=> {}
+                  },
+                  "questions_api"=> {
+                      "init_options"=> {}
+                  }
+              },
+              "widget_templates"=> {
+                  "back"=> true,
+                  "save"=> true,
+                  "widget_types"=> {
+                      "default"=> "questions",
+                      "show"=> true
+                  }
+              },
+              "container"=> {
+                  "height"=> "auto",
+                  "fixed_footer_height"=> 0,
+                  "scroll_into_view_selector"=> "body"
+              },
+              "label_bundle"=> {
+                  "backButton"=> "Zurück",
+                  "loadingText"=> "Wird geladen",
+                  "modalClose"=> "Schließen",
+                  "saveButton"=> "Speichern",
+                  "duplicateButton"=> "Duplikat",
+                  "dateTimeLocale"=> "en-us",
+                  "toolTipDateTimeSeparator"=> "um",
+                  "toolTipDateFormat"=> "DD-MM-YYYY",
+                  "toolTipTimeFormat"=> "HH:MM:SS",
+              }
+          },
+  }
+  def index
+    @init = Learnosity::Sdk::Request::Init.new(
+      'author',
+      @@security_packet,
+      @@consumer_secret,
+      @@author_request
+    )
+  end
+end

data/docs/quickstart/lrn-sdk-rails/app/controllers/index_controller.rb ADDED Viewed

@@ -0,0 +1,9 @@
+require 'learnosity/sdk/request/init' # Learnosity helper.
+require 'securerandom'                # Library for generating UUIDs.
+class IndexController < ApplicationController
+  def index
+  end
+end

data/docs/quickstart/lrn-sdk-rails/app/controllers/items_controller.rb ADDED Viewed

@@ -0,0 +1,33 @@
+require 'learnosity/sdk/request/init' # Learnosity helper.
+require 'securerandom'                # Library for generating UUIDs.
+class ItemsController < ApplicationController
+  @@security_packet = {
+    # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key. Set values in application.rb.
+    'consumer_key'   => Rails.configuration.consumer_key,
+    'domain'         => 'localhost'
+  }
+  # XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked into version control
+  @@consumer_secret = Rails.configuration.consumer_secret
+  @@items_request = {
+    "user_id" => SecureRandom.uuid,
+    "activity_template_id" => "quickstart_examples_activity_template_001",
+    "session_id" => SecureRandom.uuid,
+    "activity_id" => "quickstart_examples_activity_001",
+    "rendering_type" => "assess",
+    "type" => "submit_practice",
+    "name" => "Items API Quickstart",
+    "state" => "initial"
+  }
+  def index
+    @init = Learnosity::Sdk::Request::Init.new(
+      'items',
+      @@security_packet,
+      @@consumer_secret,
+      @@items_request
+    )
+  end
+end