VitalSource supports outcome-rich ePubs where grades (outcomes) for activities within a digital textbook can be reported back to the user's LMS or tracking system, depending on the implementation. The steps below highlight the requirements for how to successfully create your ePub file(s) to support outcome-rich environments agnostic of the LMS or tracking system.
There are three main parts to setting up your ePub to support outcomes:
- Content Markup
- Manifest Markup
- Bookshelf LTI API (VST.Book)
Content Markup:
In order to report outcomes, activities must be identified using the following markup:
<div epub:type=”vst:activity” id=”unique_activity_id”></div>
The attribute id must be unique to the EPUB. The value of this attribute should be used to identify the activity when submitting outcome data. Activities should report scores using the Javascript APIs documented above.
When adding outcome support to an activity asset, there are no additional Javascript files necessary in order to use the reporting APIs. VitalSource recommends that you check for the availability of the VST.Book object before executing the reportScores and getScores function calls. This allows for safer testing outside of Bookshelf when those APIs are not available. Having a fallback to alert the outcome information is one way to confirm that the proper data is being collected by the activity asset.
In order to use the vst: prefix with epub:type in an HTML file, it must first be declared by using the epub:prefix attribute in the html element. For example:
<html xmlns=”http://www.w3.org/1999/xht- ml” xmlns:epub=”http://www.idpf.org/2007/ops” epub:prefix=”vst: http://vitalsource.com/” >
This ensures uniqueness of the prefix by mapping the vst: prefix to the http://vitalsource.com/ URL, similar to an XML namespace declaration.
Manifest Markup:
Elements that are gradable must be identified in the TOC specifying their max score and location. VitalSource provides a service that the LMS (or a custom UI) exposes to allow selection of the activity via its position in the TOC. This allows the LTI connections to be created, so that the outcome result can flow back to the LMS. This document assumes a basic knowledge of EPUB standards and formatting. For more information review the ePub Standards documentation to get started.
.OPF File
The <manifest> XML element within the ePubs .OPF file must contain the following <item> information:
- id: must be “nav” to identify the file path as the TOC/navigation
- href: The file path for the TOC in the ePub file
- properties: must be “nav”
- media-type: set to “application/xhtml+xml”
Example:
<item id="nav" href="nav.xhtml" properties="nav" media-type="application/xhtml+xml"/>
nav.xhtml:
For outcomes to function and be identified inside of the table of contents of the book and the LMS, the nav.xhtml links must contain the following information:
- href: The XHTML page containing the asset and the location of the asset in the page.
- data-maxscore: Max possible score for the activity.
- data-graded: 1 if graded. 0 if not graded.
- data-location: Unique identifier of the activity. This should be equal to the value of the containing <div> element’s id attribute.
- Each outcomes specific activity must have it’s own item in the nav/TOC file.
Example:
<a epub:type=”toc” href="chapter_003.xhtml#test" data-location="multiple_choice_01_01_01" data-maxscore="1" data-graded="1"> Gradable activity</a>
Bookshelf LTI API:
The JavaScript APIs are intrinsically available within each book page rendered by the Bookshelf clients. These APIs all exist under the VST.Book namespace.
VST.Book.reportScores([scores], callback);
- Description: Report outcomes to Bookshelf client for transfer to Launch
- Parameters:
- scores: Array of score objects containing score, maxscore, location and optional metadata for the outcome.
- callback (optional): Function to be called when outcome has been received by the Bookshelf client but not necessarily processed by Launch.
All score objects will be in the following format:
{
score: number,
maxscore: number,
location: string,
metadata: {...}
}
- score: Value between 0 and maxscore representing the user’s score for the activity.
- location: Unique identifier of the activity. This should be equal to the value of the containing <div> element’s id attribute.
- metadata: (optional) JSON object containing activity result data.
The callback function parameter is optional. The function call returned will pass one parameter signaling if the score was a success: callback(err). Err is of type VST.Error. The message text of the error can be accessed via the property err.message.
VST.Book.getScores([location IDs], callback);
- Description: Retrieve one or more outcome results from Launch via the Bookshelf client.
- Parameters:
- [location IDs]: Array of location IDs. Example: [“01_01_01”,”01_01_02”].
- callback: Function to be called with results of outcome request.
The callback function parameter is required. The function call returned will pass two parameters: an error code and an array containing the last saved scored object for each location ID.
[{
score: number,
maxscore: number,
location: string,
timestamp: UTCTimeStamp,
metadata: {...}
}...]
Comments
Please sign in to leave a comment.