Open Source & Secret Santa with Santulator

By Adam Carroll

Introduction

It’s time for a festive post on the King Tech Blog! A few weeks ago I released the first full version of Santulator, a fun, Open Source program to help you to run Secret Santa draws. I’m from a big family and I initially wrote this with families in mind but it has since proven to be useful for office Secret Santa draws too. It’s completely free, so download it and give it a try yourself. Santulator is a personal project and not a King project.

Since this is a technology blog, I’d like to share some details about how Santulator works. The project is under active development so I’ve fixed all the links to v1.1.0 to avoid them becoming stale as changes are made in the project on a regular basis.

Open Source

Open Source projects encapsulate an open technology exchange, collaborative participation, rapid prototyping, transparency, and community development. Santulator is entirely Open Source and is available on GitHub. If you are interested, I’d encourage you to fork the project and play around with the code yourself.

Internally, Santulator is built on lots of other great Open Source software, too many projects to mention them all here. I’ll highlight a few in this post to give you a flavour of what is available.

Personally, I’m a big fan of Open Source and it’s fun to participate in the various software development communities. I’m also the author of another Open Source project, VocabHunter and through my work on that, I have developed my enthusiasm for the world of Open Source software development.

User Interface

The Santulator user interface is built using JavaFX 11. This makes it possible to build a cross-platform desktop application on Mac, Linux and Windows. You can see the main Santulator screen here with the list of participants in the draw:

Another article I wrote for the King Tech Blog, “How JavaFX was used to build a desktop application”, explains in detail how this can be done.

The user interface itself is relatively simple. It consists of the main screen that I presented above along with a guided “wizard” that you use for running the draw. Here’s the wizard, in action:

The ControlsFX Open Source library provides the components for the wizard, along with those used in various other parts of the Santulator user interface.

Festive Colours

Corporate colour schemes in business applications have their place but that place is probably not in a Secret Santa program. One of the things that I wanted to achieve with Santulator is a festive look and feel I want it to look fun and not like a productivity tool. JavaFX makes it easy to change the colours and styles of user interface components using a dialect of Cascading Style Sheets (CSS). I took advantage of this by applying a festive colour scheme to the user interface:

A couple of years ago I went to the JavaOne conference (now renamed to Oracle Code One) through my job at King. There I attended a presentation “JavaFX Tips and Tricks” by Dirk Lemmermann. One of Dirk’s tips was to get to know the JavaFX default Modena style sheet and to learn from that. This tip proved to be very useful to this work as it was the key to finding exactly the styles that I needed to change. You can see the Modena style sheet in the JavaFX repository on GitHub here.

I chose a set of three base colours based on ideas of Christmas trees and wrapping paper. You can see them here:

I define these three basic colours in colours.css, as follows:

-colour-principal: #4FB684;
-colour-bow: #FFDA90;
-colour-significant: #B21118;

I then derive most of the other colours in the user interface, based on these three. For example, the colours for the “About” dialogue, are defined in colours.css by overriding styles from the Modena style sheet. The definition of the background colour for this dialogue looks like this:

.about {
  -fx-base: derive(-colour-principal, -40%);
}

Overall we ended up with what I think is a nice festive “About” dialogue:

Packaging Santulator

Just as it was important for me to try to make using Santulator fun and simple, I also wanted to make it easy to install. Santulator is a cross-platform application that runs on Mac, Linux and Windows and I was keen to include an appropriate installer for each of those systems. For example, a Mac user should feel comfortable installing Santulator just as they would any other Mac application without needing to know that underneath it is implemented in Java.

I was able to achieve my goal of creating “native” installable bundles for Santulator using the Java Packager. These bundles include everything that the user needs to run the program, including Java itself. Also, thanks to JLink, only those Java 11 modules that are actually needed are included in the bundles. JLink was introduced in Java 9 and can be used to build a custom Java runtime image containing a specific set of modules. If you’re thinking about doing this in your own project, have a look at my article “Using the Java Packager with JDK 11”.

The Draw Results

When you run your Secret Santa draw, Santulator creates a collection of PDF files containing the draw results. One PDF is created for each participant telling them who they will buy a present for. Just for fun and to maintain the secret of the draw, the files can be protected with a password. That way you won’t accidentally see all of the draw results if you’re distributing the files.

Behind the scenes, Santulator uses the OpenPDF library to generate the PDF files and Bouncy Castle for the password protection. Thanks to these Open Source libraries, the Santulator code to generate the PDF files is nice and simple, as you can see here in PdfGiverAssignmentWriter.

Testing

As any software engineer will tell you, good automated tests are the foundation on which high-quality software is built. Santulator includes a suite of JUnit 5 tests that run automatically whenever the Gradle build is executed. In addition to the unit tests, Santulator also includes an automated GUI test. I have found that this is a great way to catch problems that might otherwise have slipped through the net. The GUI test is built using TestFX and to learn more about this, see my article “User Interface Testing with TestFX”.

The Santulator automated GUI test normally runs in “headless” mode. This means that the test doesn’t take over your display while you’re running the build. Sometimes, it’s useful to switch off headless mode while developing. Just for fun, here’s a video of the test in action with headless mode disabled. See if you can keep up with the testing robot!

Plans and Ideas for the Future

I’m really pleased to have released this first version of Santulator and to see people using it and sharing it with others. I also hope that the ideas in the Open Source Santulator code and in this article will be useful to people working on other projects. I’ve received a lot of feedback and some good ideas for future directions so I’ll have to see what I have time for in the new year. And being Open Source, I welcome technical contributions in the form of issue reporting and pull requests on GitHub.

Several users of the system have mentioned that it would be great to be able to email the results of the draw directly to the participants from within the program. Each email could contain an attachment with the password-protected PDF file that Santulator generates, personalised for the participant, containing the name of the person for whom they will buy a present.

Another thing I’d like to do is to make the system available in other languages. To make a start at this, all of the messages that the user sees have already been extracted to the Java Resource Bundle file, SantulatorBundle.properties. Since I live and work in Barcelona, it would seem natural to start with Spanish and Catalan language versions of Santulator.

I have lots of other ideas so if you’d like to keep up with the progress, use the “watch” function on the Santulator GitHub project.

Happy Holidays!

I hope you’ve enjoyed this quick run through of the technology behind Santulator. Feel free to fork the repository on GitHub and experiment with the code. It’s all Open Source and available free of charge.

And if you’re going to run your own Secret Santa draw, why not download Santulator and give it a try?

Have fun and a very happy holiday everyone!