James Jones

Course Roster Enhancements

Blog Post created by James Jones Expert on Sep 3, 2015

Synopsis

Add functionality to your course Roster page by 1) sorting on any column, 2) generating a PDF of the roster, or 3) creating a Photo Roster.

 

Although this is placed in the Higher Education group, it's only because Canvas requires blogs to be put somewhere and I teach at a community college. K-12  can benefit and Canvas Admins  should be aware in case their faculty want to do these things. It deals with programming, although not specifically API, LTI, or SIS, so maybe the Canvas Developers would want to know about it. Basically, share it with anyone who you think can benefit from it.

 

Introduction

Several people have asked for features related to the Course Roster page.

I have been having some success installing user scripts to work with Firefox and Greasemonkey, although those were short enough that I could display and explain the code in my blog posts.

I had also added the ability to sort tables to pages before, so I thought ... how hard can this be? Well, it turns out that things are much harder than I anticipated, but that is perhaps a topic for another blog post. For this one, I'll get to the point.

 

Available Scripts

In the end, I had three scripts, depending on how much functionality you want. All three of them are attached linked to this blog post. The words basic, intermediate, and advanced refer to the functionality provided by the script, not the user level required.

 

Canvas only loads 50 users on the roster page until you scroll down. I couldn't find a way to tell if all of the users had been loaded or not yet, but I set up a MutationObserver to check to see if new content is added and place a warning if you try to generate a PDF and there is exactly 50 users in the list (that can be suppressed if it gets in your way). Pagination was, by the way, a huge obstacle to overcome, but not as much as the photo roster.

 

1. Canvas Roster Sorter (Basic functionality)

This script allows you to sort by clicking at the top of any column on the Canvas Roster page. If you click again, it will reverse the order of the sort. If you click a third time, it will restore the table to its original order.

 

This is based off of an enhanced jQuery Tablesorter plugin, so read there for more information.

 

2. Canvas Roster Download (Intermediate functionality)

This script includes everything in the Roster Sorter and adds the ability to generate a PDF of the roster. By default, it only includes students. It displays the name, login information (if available), the section (if there is more than one in a course), the last activity date and total activity amounts (if available).

 

It adds a button to the right-side menu to download a PDF of the roster.

 

This uses the PDFMake routines to generate the PDF. They are a higher level attempt to create PDFs to avoid the normal hassle of specifying sizes, but that means some functionality may not be there. I did offer the ability to set the default font size and there are some other options you can use.

 

3. Canvas Photo Roster (Advanced functionality)

This was the nightmare that wouldn't end. It includes the roster sorter and the roster PDF download as well. It also uses the PDFmake routines to create a photo roster of four students wide. Under the photo is the student's name and section (unless there is only one section in the course). Images are resized to fit the avatar dimensions of 128x128.

 

It adds a button ot the right-side menu to download a Photo roster.

 

This one was the hardest to write and it's also the hardest to get working. The first two don't need any special privileges, but the avatars, which are displayed on the page, are part of the CSS background-images and not part of the document object model (DOM), which means that I couldn't get access to them without re-downloading them. Some of the sites hosting them were using cross domain restrictions to make sure that I couldn't download them. And if I could download them, they had a flag set that wouldn't allow them to be added to the HTML5 Canvas (not to be confused with the Instructure Canvas) to create an image out of it.

 

I'm beginning to see why Canvas said it wouldn't be happening in the next six months.

 

I worked around all that by using the internal greasemonkey routines rather than jQuery's, but that means I had to enable some options that threw the whole thing into a sandbox and the normal stuff stopped working. The first two scripts don't need this functionality and they load much faster. It turns out that the pdfmake routines don't load in the sandbox, so I had to add them through a getscript() function, which means that sometimes they're not fully loaded when it's ready to create the PDF. Occasionally, a photo will timeout before it gets downloaded (it seems that Canvas may do some throttling).  A warning will pop up if some of the images don't correctly download so that you can decide whether or not you want to go ahead and print. If you don't, usually trying the report again will fix it.

 

The bottom line is - click the button, but don't expect it to work the first time, especially if you have a large class. Give it about 10 seconds and then try again. Maybe a couple of times. It seems to work fairly well for small classes where no pagination is needed.

 

Instructions

Installing Greasemonkey

The key to getting all this to work is Greasemonkey, which is a Firefox add-on. For Chrome users, there is Tampermonkey. These scripts are tested with Firefox. I had them working in Chrome, but then as I added more features, I broke something, so for right now, it's Firefox only.

 

Here is a short video on how to install Greasemonkey. Ignore the part at the very end about installing a user a script - I found a better way.

 

Install the desired script(s)

After you have enabled Greasemonkey, then click on the appropriate attachment below. Greasemonkey recognizes the extension .user.js and automatically intercepts it. You need to click Install a couple of times (once to install it and once to activate it), but then it should work.

 

The only configuration that is necessary is if your site isn't hosted on instructure.com. I've set up the // @include in the header to work on any site matching *.instructure.com/courses/*/users but you will need changed if you are using a custom domain.

 

You should only install one script, although it's possible they might work if you install more than one. It's more likely that you'll run into issues.

 

Notes

  • If it doesn't work the first time, wait about 10 seconds and try again. This is especially true with the photo roster where it has to download a bunch of stuff. But after you download it, it's in your browser's cache so it should go faster the next time.
  • If you notice Firefox starting to act slowly, you might want to restart it.
  • Patience is key. If you can't find the Patience key on your keyboard, try F12 and click on console. Some messages are logged to the console that might help you track down what's going on.
  • I have tried to automatically determine the columns rather than hard-coding the order, but I have admin rights and see everything on the course users page. If you find something doesn't work, let me know. If you're not using US-English, I did code the headings at the top of the files so you can change those to match the text.
  • Everything is loaded from the users page except for the photos, no API calls are made. If it's not visible on the roster page, it's not going to show up in my stuff.
  • Chrome isn't working yet. I had it working with Tampermonkey, then I added a lot of features and things stopped working. The last error I got was that MutationObserver wasn't a function. Rather than take the time to get it working with Chrome, I thought I would make it available to people and hopefully work some of the other kinks out.
  • I am not turning this into a full-featured roster tool. If you write and ask for features like "Can you make it randomize the order of the students on the photo roster?" I'm going to say, "You've got the source code, have at!". Like most of what I write, I won't use it myself, I'm writing it to contribute stuff to the community and hopefully spark some ideas in other people who will then give back to the community.
  • I'm not a JavaScript programmer. I don't know how to put stuff on GitHub, although that would be a much better way to manage that than using Blog Posts in Canvas.
  • The code is yours to do with as you like. If you do enhance it, you might consider changes back to me to make it available -- or set up a GitHub repository and let me know about it. Since I obviously don't consider myself an expert, I would love to collaborate with people, but so far, no one has stepped up to volunteer. If we could setup a repository of user scripts for Canvas, that would be awesome.
  • Use at your own risk. I've done extensive testing (pagination, GIF images, corrupt images, only downloading the default avatar once, etc.) It's currently handling everything I've thrown at it, but that's no guarantee that I didn't miss something. If you find a bug, find a solution, and then let me know.
  • Only use one of the scripts below. You can install all of them if you like, but you should only enable one of them on a particular page. The first two (sorting and downloading) play well, it's the photo roster that acts up and I would avoid it unless you need it.

January 5, 2016 Update

Canvas has split the Login/SIS ID into two separate columns. I've updated the code to accommodate for this. However, the original attachments are no longer valid, so I've linked to the Canvancement site that will hold the latest versions of the software I'm contributing to the Canvas Community.

Outcomes