JavaScript Extensions for Carnap

Including JavaScript

Carnap allows you to incorporate external JavaScript to an assignment, in order to add extra interactive behavior to your problem sets. This can be done using the raw_html pandoc extension to include a <script> tag, or by including the JS in a metadata block. Like a CSS entry, a JS entry entry can include either a url for a single script, like so:

---
js: https://carnap.io/shared/myemail@university.edu/myjs.js
--- 

or for several scripts, like so:

---
js:
- https://carnap.io/shared/myemail@university.edu/myjs1.js
- https://carnap.io/shared/myemail@university.edu/myjs2.js
--- 

The scripts can be hosted anywhere, including on the Carnap server. As with stylesheets, scripts can be uploaded as normal documents so long as they're given the proper filetype extension (in this case, ".js" rather than ".css")

Advanced Usage

Interacting with the Server

JavaScript running as part of an assignment will have access to an object called CarnapServerAPI, which lets your JavaScript interact with the server, to retrieve information about the current student and assignment, and to save information on the server for later retrieval.

Currently, the useful properties of CarnapServerAPI are as follows:

Property Data
CarnapServerAPI.user.firstName Student's first name
CarnapServerAPI.user.lastName Student's first name
CarnapServerAPI.assignment.dueDate Assignment due date ECMAScript epoch time (milliseconds since midnight 1/1/1970 UTC, for use with the Date constructor).
CarnapServerAPI.assignment.description Assignment description

There are two methods for dealing with saving data, one for saving and one for retrieving. Data is always saved under a "namespace", so that different JavaScript extensions can avoid overwriting one another's saved information. Each student has their own saved state for each assignment - state is not shared between students or between assignments.

Method Result
CarnapServerAPI.putAssignmentState(ns,state) Serializes state and inserts it under namespace ns on the server.
CarnapServerAPI.getAssignmentState() Retrieves the assignment state asynchronously, as a Promise.

The first call to CarnapServerAPI.getAssignmentState retrieves the state from the server, and subsequent calls return a locally cached state that's updated by CarnapServerAPI.putAssignmentState. So, while the first call to CarnapServerAPI.getAssignmentState might take a moment, subsequent calls should be quite fast.

Events

In order to make it possible for interactive JS behavior to be triggered by successful or unsuccessful completion of exercises, Carnap provides a few events that you can listen for.

When Carnap finishes its initial loading, and exercise elements are properly formatted and loaded, it will fire a global carnap-loaded event, which can be observed with document.addEventListener("carnap-loaded", ...).

Whenever an exercise is successfully checked or submitted, an exercise-success event will fire on the main exercise element (the one carries the data-carnap-* attributes). An exercise-failure event fires when an exercise is checked and detected as incorrect, or a submission is rejected. Both exercise-success and exercise-failure are disabled if an exercise has the exam option set.

Finally, a problem-submision event fires on the submission button when a problem is submitted.