learnosity-sdk 0.2.1 → 0.2.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (118) hide show
  1. checksums.yaml +5 -5
  2. data/.github/PULL_REQUEST_TEMPLATE.md +13 -0
  3. data/.gitignore +1 -0
  4. data/.travis.yml +15 -5
  5. data/CONTRIBUTING.md +14 -0
  6. data/ChangeLog.md +14 -0
  7. data/LICENSE.md +141 -0
  8. data/Makefile +69 -0
  9. data/README.md +230 -186
  10. data/REFERENCE.md +249 -0
  11. data/Rakefile +9 -0
  12. data/docs/images/apache-license.svg +20 -0
  13. data/docs/images/downloads.svg +20 -0
  14. data/docs/images/image-assessment-retrieval.png +0 -0
  15. data/docs/images/image-concept-overview.png +0 -0
  16. data/docs/images/image-logo-graphic.png +0 -0
  17. data/docs/images/image-quickstart-examples-assessment.png +0 -0
  18. data/docs/images/image-quickstart-index.png +0 -0
  19. data/docs/images/image-signed-request-creation.png +0 -0
  20. data/docs/quickstart/css/style.css +113 -0
  21. data/{examples → docs/quickstart}/lrn-sdk-rails/Gemfile +2 -2
  22. data/docs/quickstart/lrn-sdk-rails/app/controllers/author_controller.rb +179 -0
  23. data/docs/quickstart/lrn-sdk-rails/app/controllers/index_controller.rb +9 -0
  24. data/docs/quickstart/lrn-sdk-rails/app/controllers/items_controller.rb +33 -0
  25. data/docs/quickstart/lrn-sdk-rails/app/controllers/questions_controller.rb +44 -0
  26. data/docs/quickstart/lrn-sdk-rails/app/controllers/reports_controller.rb +32 -0
  27. data/docs/quickstart/lrn-sdk-rails/app/views/author/index.html.erb +14 -0
  28. data/docs/quickstart/lrn-sdk-rails/app/views/index/index.html.erb +34 -0
  29. data/{examples/lrn-sdk-rails/app/views/index → docs/quickstart/lrn-sdk-rails/app/views/items}/index.html.erb +2 -5
  30. data/docs/quickstart/lrn-sdk-rails/app/views/questions/index.html.erb +6 -0
  31. data/docs/quickstart/lrn-sdk-rails/app/views/reports/index.html.erb +14 -0
  32. data/docs/quickstart/lrn-sdk-rails/config/application.rb +24 -0
  33. data/docs/quickstart/lrn-sdk-rails/config/routes.rb +11 -0
  34. data/examples/simple/init_data.rb +6 -4
  35. data/examples/simple/init_items.rb +6 -4
  36. data/learnosity-sdk.gemspec +14 -14
  37. data/lib/learnosity/sdk/request/init.rb +10 -9
  38. data/lib/learnosity/sdk/version.rb +1 -1
  39. metadata +116 -97
  40. data/LICENSE +0 -201
  41. data/examples/lrn-sdk-rails/README.md +0 -24
  42. data/examples/lrn-sdk-rails/app/controllers/index_controller.rb +0 -106
  43. data/examples/lrn-sdk-rails/config/application.rb +0 -15
  44. data/examples/lrn-sdk-rails/config/routes.rb +0 -5
  45. /data/{examples → docs/quickstart}/lrn-sdk-rails/.gitignore +0 -0
  46. /data/{examples → docs/quickstart}/lrn-sdk-rails/Rakefile +0 -0
  47. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/config/manifest.js +0 -0
  48. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/images/.keep +0 -0
  49. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/javascripts/application.js +0 -0
  50. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/javascripts/cable.js +0 -0
  51. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/javascripts/channels/.keep +0 -0
  52. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/javascripts/index.coffee +0 -0
  53. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/stylesheets/application.css +0 -0
  54. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/assets/stylesheets/index.scss +0 -0
  55. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/channels/application_cable/channel.rb +0 -0
  56. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/channels/application_cable/connection.rb +0 -0
  57. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/controllers/application_controller.rb +0 -0
  58. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/controllers/concerns/.keep +0 -0
  59. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/helpers/application_helper.rb +0 -0
  60. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/helpers/index_helper.rb +0 -0
  61. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/jobs/application_job.rb +0 -0
  62. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/mailers/application_mailer.rb +0 -0
  63. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/models/application_record.rb +0 -0
  64. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/models/concerns/.keep +0 -0
  65. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/views/layouts/application.html.erb +0 -0
  66. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/views/layouts/mailer.html.erb +0 -0
  67. /data/{examples → docs/quickstart}/lrn-sdk-rails/app/views/layouts/mailer.text.erb +0 -0
  68. /data/{examples → docs/quickstart}/lrn-sdk-rails/bin/bundle +0 -0
  69. /data/{examples → docs/quickstart}/lrn-sdk-rails/bin/rails +0 -0
  70. /data/{examples → docs/quickstart}/lrn-sdk-rails/bin/rake +0 -0
  71. /data/{examples → docs/quickstart}/lrn-sdk-rails/bin/setup +0 -0
  72. /data/{examples → docs/quickstart}/lrn-sdk-rails/bin/spring +0 -0
  73. /data/{examples → docs/quickstart}/lrn-sdk-rails/bin/update +0 -0
  74. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/boot.rb +0 -0
  75. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/cable.yml +0 -0
  76. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/database.yml +0 -0
  77. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/environment.rb +0 -0
  78. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/environments/development.rb +0 -0
  79. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/environments/production.rb +0 -0
  80. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/environments/test.rb +0 -0
  81. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/application_controller_renderer.rb +0 -0
  82. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/assets.rb +0 -0
  83. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/backtrace_silencers.rb +0 -0
  84. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/cookies_serializer.rb +0 -0
  85. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/filter_parameter_logging.rb +0 -0
  86. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/inflections.rb +0 -0
  87. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/mime_types.rb +0 -0
  88. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/new_framework_defaults.rb +0 -0
  89. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/session_store.rb +0 -0
  90. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/initializers/wrap_parameters.rb +0 -0
  91. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/locales/en.yml +0 -0
  92. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/puma.rb +0 -0
  93. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/secrets.yml +0 -0
  94. /data/{examples → docs/quickstart}/lrn-sdk-rails/config/spring.rb +0 -0
  95. /data/{examples → docs/quickstart}/lrn-sdk-rails/config.ru +0 -0
  96. /data/{examples → docs/quickstart}/lrn-sdk-rails/db/seeds.rb +0 -0
  97. /data/{examples → docs/quickstart}/lrn-sdk-rails/lib/assets/.keep +0 -0
  98. /data/{examples → docs/quickstart}/lrn-sdk-rails/lib/tasks/.keep +0 -0
  99. /data/{examples → docs/quickstart}/lrn-sdk-rails/log/.keep +0 -0
  100. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/404.html +0 -0
  101. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/422.html +0 -0
  102. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/500.html +0 -0
  103. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/apple-touch-icon-precomposed.png +0 -0
  104. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/apple-touch-icon.png +0 -0
  105. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/favicon.ico +0 -0
  106. /data/{examples → docs/quickstart}/lrn-sdk-rails/public/robots.txt +0 -0
  107. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/controllers/.keep +0 -0
  108. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/controllers/index_controller_test.rb +0 -0
  109. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/fixtures/.keep +0 -0
  110. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/fixtures/files/.keep +0 -0
  111. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/helpers/.keep +0 -0
  112. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/integration/.keep +0 -0
  113. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/mailers/.keep +0 -0
  114. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/models/.keep +0 -0
  115. /data/{examples → docs/quickstart}/lrn-sdk-rails/test/test_helper.rb +0 -0
  116. /data/{examples → docs/quickstart}/lrn-sdk-rails/tmp/.keep +0 -0
  117. /data/{examples → docs/quickstart}/lrn-sdk-rails/vendor/assets/javascripts/.keep +0 -0
  118. /data/{examples → docs/quickstart}/lrn-sdk-rails/vendor/assets/stylesheets/.keep +0 -0
data/README.md CHANGED
@@ -1,250 +1,255 @@
1
- # Learnosity SDK - Ruby
1
+ <p align="center"><img width="50%" height="50%" src="docs/images/image-logo-graphic.png" title="Learnosity logo, an open book with multicolored pages."></p>
2
+ <h1 align="center">Learnosity SDK - Ruby</h1>
3
+ <p align="center">Everything you need to start building your app in Learnosity, with the Ruby programming language.<br>
4
+ (Prefer another language? <a href="https://help.learnosity.com/hc/en-us/sections/360000194318-Server-side-development-SDKs">Click here</a>)<br>
5
+ An official Learnosity open-source project.</p>
2
6
 
3
- [![Gem Version](https://badge.fury.io/rb/learnosity-sdk.svg)](https://badge.fury.io/rb/learnosity-sdk)
7
+ [![Latest Stable Version](https://badge.fury.io/gh/Learnosity%2Flearnosity-sdk-ruby.svg)](https://rubygems.org/gems/learnosity-sdk)
8
+ [![Build Status](https://app.travis-ci.com/Learnosity/learnosity-sdk-ruby.svg?branch=master)](https://app.travis-ci.com/Learnosity/learnosity-sdk-ruby)
9
+ [![License](docs/images/apache-license.svg)](LICENSE.md)
10
+ [![Downloads](docs/images/downloads.svg)](https://github.com/Learnosity/learnosity-sdk-ruby/releases)
11
+ ---
4
12
 
5
- This gem allows to ease integration with the following Learnosity APIs,
13
+ ## Table of Contents
6
14
 
7
- - Author API [author-api-doc]
8
- - Assess API [assess-api-doc]
9
- - Data API [data-api-doc]
10
- - Events API [events-api-doc]
11
- - Items API [items-api-doc]
12
- - Questions API [questions-api-doc]
13
- - Report API [report-api-doc]
15
+ * [Overview: what does it do?](#overview-what-does-it-do)
16
+ * [Requirements](#requirements)
17
+ * [Installation](#installation)
18
+ * [Quick start guide](#quick-start-guide)
19
+ * [Next steps: additional documentation](#next-steps-additional-documentation)
20
+ * [Contributing to this project](#contributing-to-this-project)
21
+ * [License](#license)
22
+ * [Usage tracking](#usage-tracking)
23
+ * [Further reading](#further-reading)
14
24
 
15
- ## Installation
16
-
17
- ### Ruby Gem
25
+ ## Overview: what does it do?
26
+ The Learnosity Ruby SDK makes it simple to interact with Learnosity APIs.
18
27
 
19
- The SDK should be available from RubyGems [learnosity-sdk-rubygems]
28
+ ![image-concept-overview.png](docs/images/image-concept-overview.png "Conceptual overview, showing your app, connecting to the Learnosity SDK, then the Learnosity Items API.")
20
29
 
21
- gem install learnosity-sdk
30
+ It provides a number of convenience features for developers, that make it simple to do the following essential tasks:
22
31
 
23
- ### git clone
32
+ * Creating signed security requests for API initialization, and
33
+ * Interacting with the Data API.
24
34
 
25
- You can build and install the SDK directly from a Git clone, with
35
+ For example, the SDK helps with creating a signed request for Learnosity:
26
36
 
27
- git clone https://github.com/Learnosity/learnosity-sdk-ruby/
28
- cd learnosity-sdk-ruby/
29
- bundle install
30
- rake build
31
- gem install --user-install pkg/learnosity-sdk-0.2.1.gem
37
+ ![image-signed-request-creation.png](docs/images/image-signed-request-creation.png "Diagram showing the flow of information from your app, sending key, secret and parameters to the Learnosity SDK, then the Learnosity SDK sending back a fully formed request.")
32
38
 
33
- If `bundle` is missing, you can install it with
39
+ Once the SDK has created the signed request for you, your app sends that on to an API in the Learnosity cloud, which then retrieves the assessment you are asking for, as seen in the diagram below:
34
40
 
35
- gem install --user-install bundler
41
+ ![image-assessment-retrieval.png](docs/images/image-assessment-retrieval.png "Diagram showing your app sending the fully formed request to the Learnosity cloud, then the cloud retrieving your assessment, which is then rendered in the student's browser.")
36
42
 
37
- ## Usage
43
+ This scenario is what you can see running in the quick start guide example ([see below](#quick-start-guide)).
38
44
 
39
- Some usage examples can be found in the `examples/` subdirectory.
45
+ There's more features, besides. See the detailed list of SDK features on the [reference page](REFERENCE.md).
40
46
 
41
- ### Init
47
+ [(Back to top)](#table-of-contents)
42
48
 
43
- This class generates and signs init options for all supported APIs. Its
44
- constructor takes four mandatory arguments, and one optional argument.
49
+ ## Requirements
45
50
 
46
- - `service`: the name of the API to sign initialisation options for,
47
- - `security_packet`: a hash with at least the `consumer_key`, optionally the
48
- `domain` and `timestamp`; `user_id` is also mandatory for Questions API,
49
- - `consumer_secret`
50
- - `request`: the request you want to get a signature for
51
- - `action` [Data API only]: the action of your request, either `get` or `post`
51
+ 1. Runtime libraries for Ruby installed. ([instructions](https://www.ruby-lang.org/en/downloads/branches/))
52
52
 
53
- The `Init#generate` method can then be used to generate the options. By default,
54
- it will generate a JSON string. It however takes one parameter, `encode` which,
55
- if false, will simply return a native Ruby Hash with the signed options.
53
+ 2. The [RubyGems](https://rubygems.org/) package manager installed. You use this to access the Learnosity Ruby SDK on [RubyGems](https://rubygems.org/gems/learnosity-sdk).
56
54
 
57
- Given your consumer key and secret, and the request you want to run against,
58
- say, the `items` API, you just need to instantiate the
59
- `Learnosity::Sdk::Request::Init`, and call its `generate` method.
55
+ Not using Ruby? See the [SDKs for other languages](https://help.learnosity.com/hc/en-us/sections/360000194318-Server-side-development-SDKs).
60
56
 
61
- ```ruby
62
- require "learnosity/sdk/request/init"
57
+ ### Supported Ruby Versions
58
+ The Ruby SDK supports the “normal maintenance” and “security maintenance” versions listed on the [Ruby home page](https://www.ruby-lang.org/en/downloads/branches/). Please contact our support team if you are having trouble with a specific version.
63
59
 
64
- security_packet = {
65
- # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key
66
- 'consumer_key' => 'yis0TYCu7U9V4o7M',
67
- 'domain' => 'localhost'
68
- }
69
- # XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked in in revision control
70
- consumer_secret = '74c5fd430cf1242a527f6223aebd42d30464be22'
71
- items_request = { 'limit' => 50 }
60
+ [(Back to top)](#table-of-contents)
72
61
 
73
- init = Learnosity::Sdk::Request::Init.new(
74
- 'items',
75
- security_packet,
76
- consumer_secret,
77
- items_request
78
- )
62
+ ## Installation
63
+ ### **Installation via RubyGems**
64
+ Using RubyGems is the recommended way to install the Learnosity SDK for Ruby in production. The easiest way is to run this from your project folder:
79
65
 
80
- puts init.generate
66
+ ``` bash
67
+ gem install learnosity_sdk
81
68
  ```
82
69
 
83
- This will return a string of signed options suitable for initialisation of
84
- the API.
70
+ ### **Alternative method 1: download the zip file**
71
+ Download the latest version of the SDK as a self-contained ZIP file from the [GitHub Releases](https://github.com/Learnosity/learnosity-sdk-ruby/releases) page. The distribution ZIP file contains all the necessary dependencies.
85
72
 
86
- ```html
87
- <html>
88
- <head>
89
- </head>
73
+ Note: after installation, run this command in (docs/quickstart/lrn-sdk-rails/):
90
74
 
91
- <body>
92
- <script src="//items.learnosity.com/"></script>
75
+ ``` bash
76
+ bundle install
77
+ ```
93
78
 
94
- <script>
95
- var itemsApp = LearnosityItems.init(INSERT OPTIONS HERE);
96
- </script>
79
+ ### **Alternative 2: development install from a git clone**
80
+ To install from the terminal, run this command:
97
81
 
98
- </body>
99
- </html>
82
+ ``` bash
83
+ git clone git@github.com:Learnosity/learnosity-sdk-Ruby.git
100
84
  ```
101
85
 
102
- ### Data API
86
+ Note: after installation, run this command in (docs/quickstart/lrn-sdk-rails/):
103
87
 
104
- When the `service` parameter is `data`, the `action` parameter is mandatory.
105
- Moreover, `Init#generate`'s `encode` parameter is ignored, and a native Ruby Hash
106
- with the signed options is unconditionally returned, for use with your favourite
107
- HTTP library (note that, regardless of the `action` parameter, you should always
108
- send `POST` requests).
109
-
110
- ```ruby
111
- require 'net/http'
112
- require "learnosity/sdk/request/init"
88
+ ``` bash
89
+ bundle install
90
+ ```
113
91
 
92
+ Note that these manual installation methods are for development and testing only.
93
+ For production use, you should install the SDK using the RubyGems package manager for Ruby, as described above.
114
94
 
115
- security_packet = {
116
- # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key
117
- 'consumer_key' => 'yis0TYCu7U9V4o7M',
118
- 'domain' => 'localhost'
119
- }
120
- # XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked in in revision control
121
- consumer_secret = '74c5fd430cf1242a527f6223aebd42d30464be22'
122
- data_request = { 'limit' => 50 }
95
+ [(Back to top)](#table-of-contents)
123
96
 
124
- init = Learnosity::Sdk::Request::Init.new(
125
- 'data',
126
- security_packet,
127
- consumer_secret,
128
- data_request,
129
- 'get'
130
- )
97
+ ## Quick start guide
98
+ Let's take a look at a simple example of the SDK in action. In this example, we'll load an assessment into the browser.
131
99
 
132
- request = init.generate
100
+ ### **Start up your web server and view the standalone assessment example**
101
+ To start up your Ruby web server, first find the following folder location under the SDK. Change directory ('cd') to this location on the command line.
133
102
 
134
- Net::HTTP.post_form URI('https://data.learnosity.com/v1/itembank/items'), request
103
+ ``` bash
104
+ cd docs/quickstart/lrn-sdk-rails/
135
105
  ```
136
106
 
137
- ### Recursive Queries
107
+ To start, run this command from that folder:
138
108
 
139
- tl;dr: not currently implemented
109
+ ``` bash
110
+ rails server
111
+ ```
140
112
 
141
- Some requests are paginated to the `limit` passed in the request, or some
142
- server-side default. Responses to those requests contain a `next` parameter in
143
- their `meta` property, which can be placed in the next request to access another
144
- page of data.
113
+ From this point on, we'll assume that your web server is available at this local address (it will report the port being used when you launch it, by default it's port 3000):
145
114
 
146
- For the time being, you can iterate through pages by looping over the
147
- `Init#new`/`Init#generate`/`Net::HTTP#post_form`, updating the `next` attribute
148
- in the request.
115
+ http://localhost:3000
149
116
 
150
- ```ruby
151
- response = JSON.parse(res.body)
152
- if ( !response['meta']['next'].nil? \
153
- and !response['meta']['records'].nil? and response['meta']['records'] > 0)
154
- data_request['next'] = response['meta']['next']
155
- end
156
- ```
117
+ You can now access the APIs using the following URL [click here](http://localhost:3000)
157
118
 
158
- This will `require 'json'` to be able to parse the response.
119
+ <img width="50%" height="50%" src="docs/images/image-quickstart-index.png">
159
120
 
160
- See `examples/simple/init_data.rb` for an example.
121
+ Following are the routes to access our APIs.
161
122
 
162
- ### Generating UUIDs
123
+ * Author API : http://localhost:3000/author/index
124
+ * Questions API : http://localhost:3000/questions/index
125
+ * Items API : http://localhost:3000/items/index
126
+ * Reports API : http://localhost:3000/reports/index
163
127
 
164
- You will likely have to generate UUIDs. You can use the Ruby `securerandom`
165
- module for this purpose.
128
+ Open these pages with your web browser. These are all basic examples of Learnosity's integration. You can interact with these demo pages to try out the various APIs. The Items API example is a basic example of an assessment loaded into a web page with Learnosity's assessment player. You can interact with this demo assessment to try out the various Question types.
166
129
 
167
- ```ruby
168
- require 'securerandom'
130
+ <img width="50%" height="50%" src="docs/images/image-quickstart-examples-assessment.png">
169
131
 
170
- p SecureRandom.uuid
171
- ```
132
+ [(Back to top)](#table-of-contents)
172
133
 
173
- ### Rails
134
+ ### **How it works**
135
+ Let's walk through the code for this standalone assessment example. The source files are included under the `docs/quickstart/lrn-sdk-rails/` folder.
174
136
 
175
- You can bootstrap a Ruby-on-Rails project using this SDK by doing the
176
- following.
137
+ Let's consider the Items API code. The first section is a controller file in Ruby, [items_controller.rb](docs/quickstart/lrn-sdk-rails/app/controllers/items_controller.rb) from `docs/quickstart/lrn-sdk-rails/app/controllers/` and it is executed server-side. It constructs a set of configuration options for Items API, and securely signs them using the consumer key. We also add a few lines to [application.rb](docs/quickstart/lrn-sdk-rails/config/application.rb) for our Learnosity credentials. The second section is HTML and JavaScript in an [ERB](https://docs.ruby-lang.org/en/2.3.0/ERB.html) template [index.html.erb](docs/quickstart/lrn-sdk-rails/app/views/items/index.html.erb) and is executed client-side, once the page is loaded in the browser. It renders and runs the assessment functionality.
177
138
 
178
- Note, this is a quick 0 to 100 in 10s examples of how to use this
179
- SDK with Rails. As such, it takes many unwise shortcuts in the architecture of
180
- the app; do not take this as the example of a good Rails app.
139
+ [(Back to top)](#table-of-contents)
181
140
 
182
- First, generate a skeleton project
141
+ ### **Server-side code**
142
+ We start by including some LearnositySDK helpers in [items_controller.rb](docs/quickstart/lrn-sdk-rails/app/controllers/items_controller.rb) - they'll make it easy to generate and sign the config options, and unique user and session IDs.
183
143
 
184
- rails new lrn-sdk-rails
185
- cd lrn-sdk-rails
144
+ ``` ruby
145
+ require 'learnosity/sdk/request/init' # Learnosity helper.
146
+ require 'securerandom' # Library for generating UUIDs.
147
+ ```
186
148
 
187
- Add the `learnosity-sdk` as a dependency to this project
149
+ Now we'll declare the configuration options for Items API. The following options specify which assessment content should be rendered, how it should be displayed, which user is taking this assessment and how their responses should be stored.
188
150
 
189
- echo "gem 'learnosity-sdk' >> Gemfile
190
- bundle install
151
+ ``` ruby
152
+ class IndexController < ApplicationController
153
+ @@items_request = {
154
+ "user_id" => SecureRandom.uuid,
155
+ "activity_template_id" => "quickstart_examples_activity_template_001",
156
+ "session_id" => SecureRandom.uuid,
157
+ "activity_id" => "quickstart_examples_activity_001",
158
+ "rendering_type" => "assess",
159
+ "type" => "submit_practice",
160
+ "name" => "Items API Quickstart",
161
+ "state" => "initial"
162
+ }
163
+ ```
191
164
 
192
- Create a default controller
165
+ * `user_id`: unique student identifier. Note: we never send or save student's names or other personally identifiable information in these requests. The unique identifier should be used to look up the entry in a database of students accessible within your system only. [Learn more](https://help.learnosity.com/hc/en-us/articles/360002309578-Student-Privacy-and-Personally-Identifiable-Information-PII-).
166
+ * `activity_template_id`: reference of the Activity to retrieve from the Item bank. The Activity defines which Items will be served in this assessment.
167
+ * `session_id`: uniquely identifies this specific assessment attempt for save/resume, data retrieval and reporting purposes. Here, we're using the `Uuid` helper to auto-generate a unique session id.
168
+ * `activity_id`: a string you define, used solely for analytics to allow you run reporting and compare results of users submitting the same assessment.
169
+ * `rendering_type`: selects a rendering mode, `assess` mode is a "standalone" mode (loading a complete assessment player for navigation, as opposed to `inline` for embedding without).
170
+ * `type`: selects the context for the student response storage. `submit_practice` mode means the student responses will be stored in the Learnosity cloud, allowing for grading and review.
171
+ * `name`: human-friendly display name to be shown in reporting, via Reports API and Data API.
172
+ * `state`: Optional. Can be set to `initial`, `resume` or `review`. `initial` is the default.
173
+
174
+ **Note**: you can submit the configuration options either as an array as shown above, or a JSON string.
175
+
176
+ Next, we declare the Learnosity consumer credentials we'll use to authorize this request.
177
+
178
+ We'll now open the file [application.rb](docs/quickstart/lrn-sdk-rails/config/application.rb), under `docs/quickstart/lrn-sdk-rails/config/` to set our Learnosity login credentials. Notice the two values *config.consumer_key* and *config.consumer_secret*.
179
+
180
+ ``` ruby
181
+ require 'rails/all'
182
+ # Require the gems listed in Gemfile, including any gems
183
+ # you've limited to :test, :development, or :production.
184
+ Bundler.require(*Rails.groups)
185
+
186
+ module LrnSdkRails
187
+ class Application < Rails::Application
188
+ # Settings in config/environments/* take precedence over those specified here.
189
+ # Application configuration should go into files in config/initializers
190
+ # -- all .rb files in that directory are automatically loaded.
191
+
192
+ # The consumerKey and consumerSecret are the public & private
193
+ # security keys required to access Learnosity APIs and
194
+ # data. Learnosity will provide keys for your own private account.
195
+ # Note: The consumer secret should be in a properly secured credential store,
196
+ # and *NEVER* checked into version control.
197
+ # The keys listed here grant access to Learnosity's public demos account.
198
+ config.consumer_key = 'yis0TYCu7U9V4o7M'
199
+ config.consumer_secret = '74c5fd430cf1242a527f6223aebd42d30464be22'
200
+ end
201
+ end
202
+ ```
193
203
 
194
- rails generate controller Index index
204
+ The consumer key and consumer secret in this example are for Learnosity's public "demos" account. Once Learnosity provides your own consumer credentials, your Item bank and assessment data will be tied to your own consumer key and secret.
205
+ <i>(of course, you should never normally put passwords into version control)</i>
195
206
 
196
- Add the `require` for the SDK at the top of the newly created controller,
197
- `app/controllers/index_controller.rb`, and insert the assessment configuration
198
- there (taken from [items-api-demo], and truncated for legibility).
207
+ Now, back in [index_controller.rb](docs/quickstart/lrn-sdk-rails/app/controllers/index_controller.rb), we reference the key and secret, and also construct security settings that ensure the report is initialized on the intended domain. The value provided to the domain property must match the domain from which the file is actually served.
199
208
 
200
- ```ruby
201
- require 'learnosity/sdk/request/init'
209
+ ``` ruby
210
+ @@security_packet = {
211
+ # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key
212
+ 'consumer_key' => Rails.configuration.consumer_key,
213
+ 'domain' => 'localhost'
214
+ }
215
+ # XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked into version control
216
+ @@consumer_secret = Rails.configuration.consumer_secret
217
+ ```
202
218
 
203
- class IndexController < ApplicationController
204
- @@security_packet = {
205
- # XXX: This is a Learnosity Demos consumer; replace it with your own consumer key
206
- 'consumer_key' => 'yis0TYCu7U9V4o7M',
207
- 'domain' => 'localhost'
208
- }
209
- # XXX: The consumer secret should be in a properly secured credential store, and *NEVER* checked in in revision control
210
- @@consumer_secret = '74c5fd430cf1242a527f6223aebd42d30464be22'
211
- @@items_request = {
212
- [...]
213
- }
219
+ Now we call LearnositySDK's `Init()` helper to construct our Items API configuration parameters, and sign them securely with the `security_packet`, `consumerSecret` and `items_request` parameters.
214
220
 
221
+ ``` ruby
215
222
  def index
216
- init = Learnosity::Sdk::Request::Init.new(
223
+ @init = Learnosity::Sdk::Request::Init.new(
217
224
  'items',
218
225
  @@security_packet,
219
226
  @@consumer_secret,
220
227
  @@items_request
221
228
  )
222
229
  end
223
- end
224
230
  ```
225
231
 
226
- Add the HTML/Javascript boilerplate to the view, `app/views/index/index.html.erb`
232
+ [(Back to top)](#table-of-contents)
227
233
 
228
- ```erb
229
- <h1>Index#index</h1>
234
+ ### **Web page content**
235
+ We've got our set of signed configuration parameters, so now we can set up our page content for output. The page can be as simple or as complex as needed, using your own HTML and JavaScript to render the desired product experience.
230
236
 
231
- <div id="learnosity_assess"></div>
237
+ This example uses plain HTML in an ERB template, served by Rails.
232
238
 
233
- <script src="//items.learnosity.com"></script>
239
+ ``` html
240
+ <h1>Standalone Assessment Example</h1>
241
+ <div id="learnosity_assess"></div>
242
+ <script src="https://items.learnosity.com/?latest-lts"></script>
234
243
  <script>
235
244
  var eventOptions = {
236
245
  readyListener: init
237
246
  },
238
- itemsApp = LearnosityItems.init(<%= raw(@init.generate) %>);
239
-
247
+ itemsApp = LearnosityItems.init(<%= raw @init.generate %>);
240
248
  function init () {
241
249
  var assessApp = itemsApp.assessApp();
242
-
243
-
244
250
  assessApp.on('item:load', function () {
245
251
  console.log('Active item:', getActiveItem(this.getItems()));
246
252
  });
247
-
248
253
  assessApp.on('test:submit:success', function () {
249
254
  toggleModalClass();
250
255
  });
@@ -252,27 +257,66 @@ Add the HTML/Javascript boilerplate to the view, `app/views/index/index.html.erb
252
257
  </script>
253
258
  ```
254
259
 
255
- Finally, you can serve the project with
260
+ The important parts to be aware of in this HTML are:
261
+
262
+ * A div with `id="learnosity_assess"`. This is where the Learnosity assessment player will be rendered to deliver the assessment.
263
+ * The `<script src="https://items.learnosity.com/?latest-lts"></script>` tag, which includes Learnosity's Items API on the page and makes the global `LearnosityItems` object available. The version specified as `latest-lts` will retrieve the latest version supported. To know more about switching to a specific LTS version, visit our [Long Term Support (LTS) page](https://help.learnosity.com/hc/en-us/articles/360001268538-Release-Cadence-and-Version-Lifecycle). In production, you should always pin to a specific LTS version to ensure version compatibility.
264
+ * The call to `LearnosityItems.init()`, which initiates Items API to inject the assessment player into the page.
265
+ * The variable `<%= raw @init.generate %>` dynamically sends the contents of our init options to JavaScript, so it can be passed to `init()`.
266
+
267
+ The call to `init()` returns an instance of the ItemsApp, which we can use to programmatically drive the assessment using its methods. We pull in our Learnosity configuration in a variable `<%= raw @init.generate %>`, that the ERB template will import from the Ruby controller file.
268
+
269
+ This marks the end of the quick start guide. From here, try modifying the example files yourself, you are welcome to use this code as a basis for your own projects.
256
270
 
257
- rails serve
271
+ Take a look at some more in-depth options and tutorials on using Learnosity assessment functionality below.
258
272
 
273
+ [(Back to top)](#table-of-contents)
259
274
 
260
- It will become available at http://localhost:3000/index/index
275
+ ## Next steps: additional documentation
261
276
 
262
- For reference you can find the result of these steps in
263
- `examples/lrn-sdk-rails`.
277
+ ### **SDK reference**
278
+ See a more detailed breakdown of all the SDK features, and examples of how to use more advanced or specialised features on the [SDK reference page](REFERENCE.md).
264
279
 
265
- ## Testing
280
+ ### **Additional quick start guides**
281
+ There are more quick start guides, going beyond the initial quick start topic of loading an assessment, these further tutorials show how to set up authoring and analytics:
266
282
 
267
- Just run
283
+ * [Authoring Items quick start guide](https://help.learnosity.com/hc/en-us/articles/360000754958-Getting-Started-With-the-Author-API) (Author API) - create and edit new Questions and Items for your Item bank, then group your assessment Items into Activities, and
284
+ * [Analytics / student reporting quick start guide](https://help.learnosity.com/hc/en-us/articles/360000755838-Getting-Started-With-the-Reports-API) (Reports API) - view the results and scores from an assessment Activity.
268
285
 
269
- rake spec
286
+ ### **Learnosity demos repository**
287
+ On our [demo site](https://demos.learnosity.com/), browse through many examples of Learnosity API integration. You can also download the entire demo site source code, the code for any single demo, or browse the codebase directly on GitHub.
270
288
 
271
- to exercise the testsuite.
289
+ ### **Learnosity reference documentation**
290
+ See full documentation for Learnosity API init options, methods and events in the [Learnosity reference site](https://reference.learnosity.com/).
272
291
 
273
- ## Tracking
292
+ ### **Technical use-cases documentation**
293
+ Find guidance on how to select a development pattern and arrange the architecture of your application with Learnosity, in the [Technical Use-Cases Overview](https://help.learnosity.com/hc/en-us/articles/360000757777-Technical-Use-Cases-Overview).
274
294
 
275
- In version v0.2.0, we introduced code to track the following information by adding it to the request being signed:
295
+ ### **Deciding what to build or integrate**
296
+ Get help deciding what application functionality to build yourself, or integrate off-the-shelf with the [Learnosity "Golden Path" documentation](https://help.learnosity.com/hc/en-us/articles/360000754578-Recommended-Deployment-Patterns-Golden-Path-).
297
+
298
+ ### **Key Learnosity concepts**
299
+ Want more general information about how apps on Learnosity actually work? Take a look at our [Key Learnosity Concepts page](https://help.learnosity.com/hc/en-us/articles/360000754638-Key-Learnosity-Concepts).
300
+
301
+ ### **Glossary**
302
+ Need an explanation for the unique Learnosity meanings for Item, Activity and Item bank? See our [Glossary of Learnosity-specific terms](https://help.learnosity.com/hc/en-us/articles/360000754838-Glossary-of-Learnosity-and-Industry-Terms).
303
+
304
+ [(Back to top)](#table-of-contents)
305
+
306
+ ## Contributing to this project
307
+
308
+ ### Adding new features or fixing bugs
309
+ Contributions are welcome. See the [contributing instructions](CONTRIBUTING.md) page for more information. You can also get in touch via our support team.
310
+
311
+ [(Back to top)](#table-of-contents)
312
+
313
+ ## License
314
+ The Learnosity Ruby SDK is licensed under an Apache 2.0 license. [Read more](LICENSE.md).
315
+
316
+ [(Back to top)](#table-of-contents)
317
+
318
+ ## Usage tracking
319
+ Our SDKs include code to track the following information by adding it to the request being signed:
276
320
 
277
321
  - SDK version
278
322
  - SDK language
@@ -280,15 +324,15 @@ In version v0.2.0, we introduced code to track the following information by addi
280
324
  - Host platform (OS)
281
325
  - Platform version
282
326
 
283
- We use this data to enable better support and feature planning. All subsequent versions of the SDK shall include this usage tracking.
327
+ We use this data to enable better support and feature planning.
328
+
329
+ [(Back to top)](#table-of-contents)
330
+
331
+ ## Further reading
332
+ Thanks for reading to the end! Find more information about developing an app with Learnosity on our documentation sites:
284
333
 
334
+ * [help.learnosity.com](http://help.learnosity.com/hc/en-us) -- general help portal and tutorials,
335
+ * [reference.learnosity.com](http://reference.learnosity.com) -- developer reference site, and
336
+ * [authorguide.learnosity.com](http://authorguide.learnosity.com) -- authoring documentation for content creators.
285
337
 
286
- [author-api-doc]: https://docs.learnosity.com/authoring/author
287
- [assess-api-doc]: https://docs.learnosity.com/assessment/assess
288
- [data-api-doc]: https://docs.learnosity.com/analytics/data
289
- [events-api-doc]: https://docs.learnosity.com/analytics/events
290
- [items-api-doc]: https://docs.learnosity.com/assessment/items
291
- [questions-api-doc]: https://docs.learnosity.com/assessment/questions
292
- [report-api-doc]: https://docs.learnosity.com/analytics/report
293
- [learnosity-sdk-rubygems]: https://rubygems.org/gems/learnosity-sdk
294
- [items-api-demo]: http://demos.learnosity.com/assessment/items/itemsapi_assess.php
338
+ [(Back to top)](#table-of-contents)