An unnoficial university class timetabler
Tags: js, tools, webdev
Status: retired

Bojangles timetabler

Bojangles was a class timetabler I made in 2014 while studying at UNSW. I maintained bojangles until mid 2018, however it is now retired as it did not perform well with the new class layouts as a result of the change to trimesters. If you’re looking for a timetabler Crossangles is an up-to-date replacement.

Why the name?

UNSW has had a number of unofficial timetablers, starting with rectangles and then octangles. I wanted to keep to the -angles theme, hence bojangles. The next in line, crossangles, also kept to this theme.


The main features I aimed for were:

  • Interactive drag and drop interface
  • Flexible timetable generation
  • Responsive design, work down to phone sized devices

The earlier timetablers worked by generating a sorted list of example timetables which you could look through but could not interact with. The downside of this approach is that you cannot easily explore changing classes around and if there were many options for class times you would only see a small subset of the thousands of possibilities. Bojangles improved on this by adding drag and drop capabilities so you could click on a class and all the possible locations it could be moved to would be highlighted. Then you can drag the class around and drop it into new places letting you try new timetables quickly.

Bojangles drag and drop functionality

Fun facts
  • Bojangles saw approximately 100K hits per year, the majority of these were in two three week periods corresponding to the enrollment period
  • Surprisingly the frontend was not updated at all since 2014
  • Over the 4 years I received about 50 emails with feature requests or bug reports. One person found out where I worked (presumably from linkedin), called my office, got my work email address from my boss and emailed me to ask me to update the class times. My personal email address was on the site, I guess they missed that.

Timetable generation

The earlier timetablers generated timetables on the server while instead for bojangles I opted to generate timetables on the client. This was mostly because I wanted hosting to be cheap and by timetabling on the client the backend was mostly just static files which could be served from almost anything.

To generate timetables I used a recursive backtracking algorithm, although originally this was just planned to be a quick proof of concept. I had ultimately intended to use a genetic algorithm, however in practice the recursive backtracker was relatively fast so I decided to stick with it. At UNSW you are allowed to have classes overlap up to a certain number of hours, so the algorithm would backtrack when the overlap hours were exceeded. To get the backtracker to perform well I did some research on how the JS JIT compiler in chrome worked and how to optimise for it, this resulted in some ugly code with a lot of nested, fixed sized lists of ints but it did perform well even on mobile platforms. The minimum spec platform I aimed for was an iPad 2 and on this platform the backtracking algorithm could generate about 1K timetables per second.

Bojangles had a slightly more flexible timetable generation system than the earlier timetablers. Like earlier timetablers you could choose to optimise for:

  • Least days at uni
  • Least hours at uni
  • Later wakeup time
  • Earlier finish time

However you could also rank your preferences in this list, for example ‘least days at uni’ and ‘later wakeup time’ would first rank timetables by least days at uni, then rank by latest wakeup time within this.

One area where bojangles didn’t do so well was that it didn’t separate different weeks, instead opting to flatten them together. Earlier timetablers somewhat handled this by allowing timetable generation only for certain weeks. This is the main area where bojangles fell down with the switch to trimesters as courses could be scheduled quite differently in different weeks, leading to many overlapping classes.

Other details

Bojangles used fabric.js to provide interactivity using a HTML5 canvas. When released fabric.js did not have good support for high DPI displays so I had to tweak the library a bit to get it working in that case.

To get class data it was mostly scraped from classutil using a python script. Unfortunately at the end of the year classutil was slow to roll over to the new year, so a scraper using had to be maintained too. This was inconvenient as only updates once a day and has a different page per subject, compared to classutil updating 4 times a day and having one page per faculty.