SOP: Development work on the GUI client

Updated 2024-10-28

The Rule Game (a.k.a. GOHR) software is deployed in the form of two separate, but closely interacting, web applications: the Rule Game server and the Rule Game GUI client. Typically, the two are developed to the same web server; for example, the former may be installed in /opt/tomcat/webapps/w2020, and the latter in /opt/tomcat/webapps/rule-game. This, for example, is the arrangement for the production software on action.rutgers.edu.

However, it is also possible to install the client on one server and the server on the other. This is convenient during development: when you're working on modifying the client, you can keep it on your personal computer (either deployed to a locally run web server, e.g. localhost:3000 or localhost:8080, or simply accessing it via a file: URL), and have it work with the server deployed on some remote machine (such as action.rutgers.edu).

This document descirbes the process for doing GUI client development in this way. The file paths and command in the illustrative examples are given as if you are using a Linux or MacOS computer; minor changes may be needed on an MS Windows machine.

Preliminaries

Make sure you have the Typescript compiler (npm) on your machine. If you don't, you can install it with sudo apt-get install npm (if using Ubuntu), or a similar command for your OS.

It is also desirable, although not strictly necessary, to have a web server (an HTTP server) of some kind on your computer. I usually use Tomcat, although any other server, e.g. one built into IDEs such as Visual Studio or Eclipse would do as well.

The jar tool, which comes with the Java Development Kit (along with a Java compiler etc) would be handy when you're preparing the web app for deployment, although not strictly necessary either.

Getting the client source code

For the rest of the discussion, we'll assume that you'll be doing the development in the directory named w2020/client under your home directory; we'll refer to that location as your main work directory. Obviously, it can be anywhere else; just change the paths accordingly.

Download the GUI client source from GitHub https://github.com/RuleGame/Rule-Game . This can be done e.g. as follows:

	    cd
	    mkdir w2020
	    cd w2020
	    mkdir client
	    cd client/
	    git init
	    git remote add origin https://github.com/RuleGame/RuleGame.git
	    git pull origin master

Install the Node.js programming language https://nodejs.org/en/ (version 14 LTS version)

Install all the necessary TypeScript/React packages. They are listed in the file package.json that has come with the GUI client's code. To install all these packages, run

	    npm install

There likely will be lots of warnings, but as long as there are no error, you are good to go. (Of course, as one of your tasks in the future, you can consider improving the package.json package so that the package-installation process produces fewer warning messages, while still building a good enough set of packages for the GUI client app to compile and run well!)

Compilation

In the terminal window where you are going to carry out the compilation, set up two environment variables:

Variable name Variable value Comments
REACT_APP_DEBUG_MODE_ENABLED true or false Use true if compiling the production version of the client (which looks the same way as what our Prolific subjects use) or false for the development version (which will show more debugging information)

REACT_APP_APP_API_HOST_ORIGIN The Game Server URL E.g. http://action.rutgers.edu/w2020 (in the assumption that you will use your client with the Rule Game server on our Rutgers host). This variable is optional, but if you don't set it, you must use the parameter server=http://action.rutgers.edu/w2020

Variable name	Variable value	Comments
`REACT_APP_DEBUG_MODE_ENABLED`	`true` or `false`	Use `true` if compiling the production version of the client (which looks the same way as what our Prolific subjects use) or `false` for the development version (which will show more debugging information)
`REACT_APP_APP_API_HOST_ORIGIN`	The Game Server URL	E.g. `http://action.rutgers.edu/w2020` (in the assumption that you will use your client with the Rule Game server on our Rutgers host). This variable is optional, but if you don't set it, you must use the parameter `server=http://action.rutgers.edu/w2020`

The way you set environment variables depends on what shell you use; it's usually something like setenv in shells such as csh or tcsh, and export in some other shells. For example, when we compile the client on our own server (see compile.sh), we may do this:

	    setenv REACT_APP_DEBUG_MODE_ENABLED false
	    setenv REACT_APP_APP_API_HOST_ORIGIN http://action.rutgers.edu/w2020

Compile the TypeScript code by running

npm run build

See if there are any compilation errors...

If the compilation has been successful, the compiler will create subdirectory build under your main work directory; in that directory, a number of files will be located, including index.html, which contains the top-level part (entry point) of your compiled TypeScript program.

Testing using a `file:` URL

Assuming your web browser support file: URLs, you can test your client (working with the main Rule Game server at Rutgers) without deploying it to any web server at all!

If you are not familiar with file: URLs, see if your favorite web browser has the File > Open File menu item, and then, using this menu item, try to open the file index.html in the build subdirectory under your main work directory. The browser will open the file successfully, although your TypeScript program will likely report an error of some kind. Remember what the URL in the Location bar of your web browser looks like!

You need to compose the test URL, which would look somewhat like this:

file:///Users/vmenkov/w2020/gui/build/index.html?server=http://action.rutgers.edu/w2020&exp=vm/colorVshape&workerId=vm-2024-10-30-a

In your test URL:

replace the file location part (/Users/vmenkov/w2020/gui/build/index.html) with the location of build/index.html produced by the compilation (see above);
if desired, replace the experiment plan name, in the part exp=vm/colorVshape with the name of any other experiment plan. (Any of the plan listed in the table in the launch page)
replace the player ID, vm-2024-10-30-a, in the section workerId=vm-2024-10-30-a with some unique player ID which can, for example, include your name, the calendar date, and a sequential number (a different number for every test you undertake on this date)
if desired, add the section
```
  &intro=skip
```
That will cause the Rule Game server to skip the introduction pages (the IRB consent page and the instructon booklet) of the game.

Once you have created a test URL, paste it into the Location bar of your web browser; this should start your GUI client (a JavaScript program in your browser) which will interact with the Rule Game server at the location specified in the server=... part of the URL.

Testing using a local web server

You can also test the GUI client by deploying it to some location on your locally running web server. For example, if your run Tomcat on part 8080, and its webapps directory is in /opt/tomcat/webapps, you can do this (starting in your main work directory)

    mv build prod
    mkdir /opt/tomcat/webapps/rule-game
    cp -pa prod /opt/tomcat/webapps/rule-game

(Depending on the file ownership situation, you may need some sudo and chown or chmod added to the above commands). After that, the index.html file produced by npm run build will be located at /opt/tomcat/webapps/rule-game/prod/index.html , and will be served to you by your web server if you go to the URL http://localhost:8080/rule-game/prod in your web browser. (Once the file is loaded, your TypeScript app will report an error though, since some parameters are missing in the URL). A complete test URL may look something like this:

http://localhost:8080/rule-game/prod/index.html?server=http://action.rutgers.edu/w2020&exp=vm/colorVshape&workerId=vm-2024-10-30-a

where you replace vm-2024-10-30-a with some unique player ID, as discussed in the previous section.

If you run a different web server (e.g. one built into Visual Studio), copy the files to the appropriate location, and use an appropriate URL to get the server to serve index.html to you.

Once you know what the URL for your client's index.html on the local host is, you can go to the special page Rule Game launch page for testing the local client, where you can specify the location of your client to have it run while working with the Rutgers server.