GUI Development

This page describes how the 3X GUI code is structured for people who want to contribute code to the graphical user interface.

Overview

The 3X GUI is a web application written in CoffeeScript with LESS for styling and HTML for boilerplates. Its backend, also written in CoffeeScript, is a Express.js/node.js application that exposes 3X's core functionality to the GUI by making the CLI (command-line interface) available as simple REST-style HTTP APIs. JSON is used for all data exchange: between GUI frontend and backend as well as between the GUI backend and the CLI. Socket.io is used for notifying the GUI about the changes to the experiment repository, which are first detected with Python's watchdog package.

Frontend Code Structure

The code for the frontend of 3X GUI resides under gui/client/ directory of the source tree. Any *.coffee file under it is compiled into JavaScript and staged onto @prefix@/gui/files/resource/ at build-time with their source maps (by GUI's .module.build script). Dependencies between the files, or more accurately "modules", are handled by Require.js, allowing the use of the require function. For example, TableView = require "TableView" line in ResultsSection.coffee loads the class declared in TableView.coffee. The configuration for Require.js is in the entry point script main.coffee.in, which also loads all the sections in the GUI defined by the *Section.coffee files. Here, *.in files, which have shell script to generate content at build-time, are first compiled into the files without the .in suffix, then follow the rest of the build process.

To add a new module for the frontend, it could be as simple as just adding a new *.coffee file. Here are a few things to note:

• Any *.coffee file added under the gui/client/ directory will be automatically compiled and staged.
• The directory hierarchy for *.coffee files is ignored, so a unique file name must be used.
• The convention is to end every CoffeeScript file with a class declaration, so other files that requires the file can easily use the declared class.
• When adding an *.in file, some implicit-dependency declarations might be necessary in GUI's .module.build script for correct builds.

External Libraries

All external libraries used by the frontend of 3X GUI have their Git repos linked under the gui/extern/. At build-time, the external libraries are compiled, and necessary files are copied into gui/.build/client/resource/ directory, then eventually staged onto @prefix@/gui/files/resource/. On the other hand, all external packages used by the backend of 3X GUI are declared in gui/package.json that is handled by npm at build-time.

To add a new external library for the frontend, here are the steps to take:

1. Add the library's Git repo with the desired commit as a submodule under gui/extern/.
2. Add relsymlink commands to bring the wanted files to GUI's .module.build script. Also, add commands to build the new library before them if necessary.
3. If there are implicit dependencies between the new files in the library, declare them as shim configuration for Require.js in main.coffee.in.