Developer Details

The following describes the development process for the application, both the mechanisms of developing code and the philosophy/intent behind the various portions of the application.

Development cycle

Despite the majority of the application being a web server and a large quantity of HTML/CSS/Javascript, it is not possible to edit web content and then refresh the browser to see the changes. The entire application must be re-built and re-launched in order to try out changes (an obvious requirement for the Java portion of the application, but not so obvious for the web content).

There are two VS Code build tasks to ease the development cycle:

  • run - This builds the application and then runs it. This is the most common task to use.

  • build - This builds a new JAR file that can be run manually, or shared with someone else.

The process is therefore edit code, use the run build task, test the code, close the application window, repeat.

A third VS Code build task exists; the docs build task; it is used to generate this documentation.

UX design

There are three main “display” targets for the application, each of which guides the design of the corresponding sections of the application.

  • Desktop - This is where the main adminstration and configuration occurs. The Admin page, with all of its sub-pages, is intended for desktop use, and is therefore designed with that as a target (meaning that it is not necessarily mobile-friendly). Given that the activities handled within the Admin page are typically performed on the same computer that runs the application (and are much easier to accomplish with a physical keyboard), this is not seen as overly problematic.

  • Mobile - This is where the majority of the work during the running of an event takes place. The Judge page, Referee page, and Time Keeper pages are all used by the corresponding volunteers during an event, and are therefore designed to work well on a modile device (following mobile-first design practices). CSS media queries (@media) are used to adjust these pages to better utilize larger displays (such as a tablet, or desktop, instead of a phone), but the design is done first for a phone in portrait mode (the most horizontally-space restrictive environment).

  • Projector - There are two audience displays, allowing the attendees to see pertinent information about the event. These are the Scoreboard page and the Timer page. Additionally, there is the Standings page for displaying the league standings, if that feature is utilized by an organizer (and would normally be displayed at the end of the event). Similar to desktop, they are intended for projection onto a large screen (or wall), and are not necessarily mobile-friendly.

There are a common set of colors in the base CSS file (styles.css) that are used throughout the remainder of the CSS to select colors. The web interface is primarily black and white, with a accent and error colors (defined as such in the CSS); utilizing the accent and error color names allows those colors to be changed across the entire web interface with a one-line change in the base CSS.

Configuration conveniences

There are three configuration values that can be stored in the config table in the database to assist with development:

  • bypassSecurity - If this is set to 1, all of the security in the web interface (logins and roles) are bypassed. In this case, anyone can access anything; helpful when developing! If this value is set to 0 or is missing, the normal login and role controls are present.

  • dbDebug - If this is set to 1, every SQL statement that is executed on the SQLite database is printed out to the terminal (System.out.println()). This can be helpful when trying to get data into or out of the database, and making sure that the correct SQL is used. If this value is set to 0 or is missing, no logging occurs.

  • httpDebug - If this is set to 1, every HTTP request that is received is printed out to the terminal (System.out.println()). This can be helpful when trying to validate web requests that are generated by the application’s Javascript in the browser. If this value is set to 0 or is missing, no logging occurs.

When run from within a development environment (the build task), there are check boxes on the main application allowing these to be easily toggled.