Rating

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:

Request free 14-day trial access or Open in LTI Launcher for Windows (further information on LTI Launcher for Windows) or, in Moodle, dynamically register the tool for LTI 1.3 using the URL https://lti.app/rating/connect.php

A Java version of this application is also available.

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

• PHP LTI Tool Provider classes - for handling the LTI-related connections
• RateIt - a JQuery (star) rating plugin
• JQuery - JavaScript library

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.

PHP source files

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

• src.zip

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:

• APP_NAME - the name of the application is used in the HTML page headers
• SESSION_NAME - a session cookie is used to manage access to the application, it may be given any name
• LTI_FOLDER - relative path to the LTI Tool Provider classes folder (this may be changed if another copy is available on the web server)

The database connection is configured through the following settings:

• DB_NAME - a PDO connection string such as 'mysql:dbname=MyDb;host=localhost' or 'sqlite:php-rating.sqlitedb'
• DB_USERNAME - the database username with SELECT, INSERT, UPDATE and DELETE privileges for the database tables used by the application
• DB_PASSWORD - the password for the database user
• DB_TABLENAME_PREFIX - an optional prefix to insert before each table name

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

The application uses the following database tables:

• item - a record for each item to be rated
• rating - a record for each rating made by a student

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
  ON DELETE CASCADE;

ALTER TABLE rating
  ADD CONSTRAINT rating_item_FK1 FOREIGN KEY (item_id)
  REFERENCES item (item_id)
  ON UPDATE CASCADE
  ON DELETE CASCADE;

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).

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.

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.

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.

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:

• a new or existing item is made visible;
• an item's visibility is disabled;
• a user rates an item

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.

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.