Overview

Rating is a simple application developed as a way to demonstrate how to build an IMS LTI tool provider. The application allows teachers to create items which can be rated by students. A separate list of items is maintained for each link from which the tool is launched. If the link has the Outcomes service enabled, then the associated gradebook column will be populated with the proportion of the visible items which each student has rated.

Before downloading the application you can try it out by requesting a free trial consumer key and secret which will be valid for 14 days:

or (further information on LTI Launcher for Windows)

A Java version of this application is also available.

System requirements

The Rating application is written in PHP and has the following dependencies (which are included in the download file):

The download file contains code written for use with a MySQL or SQLite database, but it can be used with any database supported by the LTI classes.

Installation

PHP source files

The download file available from OSCELOT (see Licence section below) includes the following file:

This file contains the PHP source files for the application which should be extracted to a web server:

  1. extract the src.zip file and upload it to the web server;
  2. extract the contents of the lti.zip file to create a directory named rating containing all the application source files.

Restrict access

The admin directory is used to manage access to the application; on a production server, therefore, steps should be taken to prevent unathorised access to this directory. For example, on an Apache web server a .htaccess file with an associated user password file could be used.

Configuration

The following application settings may be specified in the config.php file:

The database connection is configured through the following settings:

(The DB_USERNAME and DB_PASSWORD settings should be left empty for an SQLite database connection.)

The application uses the following database tables:

The table names may also have a prefix (see DB_TABLENAME_PREFIX setting above). The InnoDB database engine is recommended for the tables to ensure support for the integrity constraints.

CREATE TABLE item (
  item_id int(11) NOT NULL AUTO_INCREMENT,
  consumer_key varchar(50) NOT NULL,
  resource_id varchar(50) NOT NULL,
  item_title varchar(200) NOT NULL,
  item_text text,
  item_url varchar(200) DEFAULT NULL,
  max_rating int(2) NOT NULL DEFAULT '5',
  step int(1) NOT NULL DEFAULT '1',
  visible tinyint(1) NOT NULL DEFAULT '0',
  sequence int(3) NOT NULL DEFAULT '0',
  created datetime NOT NULL,
  updated datetime NOT NULL,
  PRIMARY KEY (item_id)
);

CREATE TABLE rating (
  item_id int(11) NOT NULL,
  consumer_key varchar(50) NOT NULL,
  user_id varchar(50) NOT NULL,
  rating decimal(10,2) NOT NULL,
  PRIMARY KEY (item_id,consumer_key,user_id)
);

ALTER TABLE item
  ADD CONSTRAINT item_lti_context_FK1 FOREIGN KEY (consumer_key, resource_id)
  REFERENCES lti_context (consumer_key, context_id)
  ON UPDATE CASCADE;

ALTER TABLE item
  ADD CONSTRAINT item_lti_context_FK1 FOREIGN KEY (consumer_key, resource_id)
  REFERENCES lti_context (consumer_key, context_id);

In addition, the tables used by the LTI Tool Provider classes are also used. When using a MySQL or SQLite database the required database tables are created automatically when calling the Manage tool consumers page (provided the database user has the CREATE privilege).

Usage

Manage tool consumers

Administrators should access the <app_path>/admin/ (where <app_path> is the URL to the application) page to manage the tool consumers which are permitted to use the application. The page displays a list of defined tool consumers in name order.
Sample manage tool consumers page

NameDescriptionRequired?Default value
NameA display name for this tool consumer entryYesNone
KeyA unique string to identify the VLE connecting to the applicationYesNone
SecretA secret used to secure the LTI launchYesA random string
Enabled?Whether launch requests from this tool consumer should be acceptedNoNo
Enable fromDate/time from which launch requests for this consumer key will be accepted (e.g. 1-Jan-2013 00:00NoNone
Enable untilDate/time until which launch requests for this consumer key will be accepted (e.g. 31-Jan-2013 23:59NoNone
Protected?Whether launch requests from this tool consumer should only be accepted if the same GUID value is passedNoNo

For a tool consumer to be marked as available it must be both enabled and the current time must fall between any enable from/until dates specified. If a tool consumer is not available, its row in the table will be displayed with a grey background. The version column is completed with data provided by an LTI launch request; the tool consumer GUID is displayed when placing the mouse over the value.

A new tool consumer can be added by entering its details in the form provided at the bottom of the page. An existing tool consumer definition can be edited by clicking on the edit icon in the Options column of the table. This will add its details in the table at the bottom of the page; click on the Update consumer button to save any changes, or click on Cancel to clear the form. Click on the delete icon in the Options column to delete an existing tool consumer definition.

The launch URL (<app_path>/connect.php, consumer key and secret should be communicated by a secure means to the administrator of the VLE for which they were created so that they can be used to add the Rating application to their system.

Manage rating items

If a teacher launches a link to the Rating application from within their course, a page listing the items to be rated is displayed. The list displayed is specific to the link which was followed.
Sample manage rating items page

NameDescriptionRequired?Default value
TitleThe heading displayed for the itemYesNone
URLA URL used as a hyperlink for the titleNoNone
DescriptionA description of the itemNoNone
Visible?Whether the item is displayed to studentsNoNo
Maximum ratingThe maximum rating value which a student can award the itemYes3
Rating stepThe increment used when awarding ratingsYes1

Alternate rows within the list of items are given a different background colour; hidden items are marked [hidden] and displayed with a grey background. The maximum rating determines the number of stars displayed against the item. The rating value (displayed as red stars) is the average rating awarded by students to the item. Hovering the mouse over a rating will display its numeric value.

A new item can be added by entering its details in the form provided at the bottom of the page. Items can be re-ordered by selecting a new position for an item from the drop-down list provided. An existing item definition can be edited by clicking on the edit icon in the Options column of the table. This will add its details in the table at the bottom of the page; click on the Update item button to save any changes, or click on Cancel to clear the form. Click on the delete icon in the Options column to delete an existing item definition.

Rating items

If a student launches a link to the Rating application from within their course, a page listing the items to be rated is displayed. The list displayed is specific to the link which was followed.
Sample item rating page

A student may rate an item by clicking on the apppropriate star; it an increment step less than one has been selected for the item then the student should click on the appropriate section of the star. The numeric value of the rating is displayed when the mouse is hovered over the stars. A student is only permitted to rate each item once.

Ratings and outcomes

If a resource link supports the LTI Outcomes service then the associated gradebook column is used to record the proportion of visible items each student has rated. This means that the grades column will be updated when the following events occur:

If a change leads to no items being visible then any gradebook entries will be deleted; otherwise the value will be zero (if the user has not rated any of the visible items), one (if all of the visible items have been rated by the user), or a value between zero and one when a user has rated some, but not all, of the visible items.

Note, this is just one way in which the application could link a student's activity to an LTI outcome value between 0 and 1 and has been added to illustrate the use of the Outcomes service.

Content-item messages

The connect.php endpoint for this application also accepts ContentItemSelectionRequest messages. In this situation the normal instructor page has additional buttons at the bottom to save the item to the tool consumer or to cancel the creation of an item. The former button is only enabled when the list has at least one item in it so as to prevent links to empty lists from being created. A placement will be included in the content-item definition returned to the tool consumer if at least one of the following document targets was offered in the message received:

  1. overlay
  2. popup
  3. iframe
  4. frame

The placement selected will be the first one from the above list which was offered. Only a single list can be created at a time.

Version history

VersionDateDescription
1.0.002 January 2013Initial release
1.0.0117 January 2013Minor update
1.1.005 June 2013Added Outcomes service option
1.2.0020 May 2015 Updated to use class method overrides rather than callback functions
LTI endpoint renamed from launch.php to connect.php
Added support for Content-Item selection messages

Licence

Creative Commons License This work is written by Stephen Vickers and is released under a Creative Commons GNU General Public Licence. The Rating application is available for download from OSCELOT where it is also possible to report bugs.

XML descriptor (copy and paste into an LTI tool configuration page)
Valid XHTML 1.0 Strict