# Scoreboard Operations using tsh

How to enhance your tsh experience.

Updated Mon 29 Jul 2024 16:05:11 EDT for tsh 3.340.

This section discusses specific issues related to the operation of the scoreboard using tsh and may safely be ignored if your tournament does not use the scoreboard.

## What is the Scoreboard?

The scoreboard is a web page, called the Enhanced Scoreboard in the event HTML index, which periodically checks for updated score information and presents it in a browser page in a variety of formats.

## How does the Scoreboard Work?

Here's an overview.

1. You initially create a scoreboard document for each division using the “`ESB A`”, “`ESB B`”, etc. commands.
2. These documents, along with the rest of your web files, must be accessible on an actual webserver and not just being viewed from your desktop (or else most browsers will prevent the code in the scoreboard from running for security reasons).
3. You arrange for the data file that the scoreboard checks to be automatically updated using triggered/hooked invocation of the “`JSON`” command, and remember to run it manually in other unusual situations.
4. If you are hosting your web files on another server, you make sure that they are copied there on a regular basis, e.g., using the “`util/mirror-ftp`” command.

## Step-by-Step

### 1. Create Scoreboard Documents

First, add a line like the following to your configuration file:

    begin esb a; esb b; esb c; json

This tells tsh that when it starts running, it should create the scoreboard document for divisions A, B and C (change that part if you have different divisions), then update the scoreboard data file. If the scoreboard documents or data file already exist, they will just be updated.

Check the results of the first step by running tsh and using the “`Browse`” command to show you the event index. You should see your enhanced scoreboards listed at the top. Don’t worry about clicking to see their content yet.

### 2. Set up a Webserver

Next, you need to get the files onto a webserver. If possible, you should always try to run a webserver locally on your data entry machine, even if you are also mirroring files to a public webserver, because it will result in faster updates to your scoreboard without waiting for your data to make a round-trip off-site.

I may eventually include operating-system specific instructions for how to enable the webserver that comes with your computer. In the meantime, if you use Windows, try Googling for "Internet Information Server", "install", and the name of your version of Windows; if you use macOS, Google for "apache" or "web server", "enable", and the name of your version of Windows; if you use Linux, ""apache", "configure", and the name of your version of Linux. In each case, you'll eventually end up with a local directory where your webserver expects to find your files. Use the “`config html_directory`” configuration option to specify this to tsh.

If you cannot set up a local webserver (e.g., because it violates a security policy, or it is too difficult), you should find someone who can provide you with FTP access to a public webserver. If you are a NASPA-certified tournament director, you are entitled to a free FTP-based webserver account on the NASPA server; contact John Chew at <poslfit@gmail.com> to ask for one to be set up. You may also find it easier just to run tsh remotely on the NASPA server in this case.

### 3. Set up Data Updates

Add lines like the following to your configuration file:

    config hook_addscore_flush = 'json'
    config hook_autopair = 'json'
    config hook_division_update ='json'

These tell tsh to run the “`JSON`” command respectively whenever the “`Addscore`” command saves its data, whenever new pairings are created automatically or by default, and whenever the division data files are updated.

If you notice at any point later on that the scoreboard's data does not reflect a recent change (especially one that you made by hand), you can run the “`JSON`” command to update the data. Note though that the scoreboard checks for data only once every 10 seconds (see the countdown at the top right), and that if you are copying data to a remote webserver, it may take up to a few minutes for it to reach its destination.

### 4. Copy Files Off-site

If you are using an off-site webserver, you should use the “`util/mirror-ftp`” command to automatically copy (mirror) your web files to it. (See also the MIRROR, PAUSEMirror, RESumeMirror, and STOPMirror commands.) This command runs separately from tsh, in a different window, and how you launch it depends on your operating system. Like tsh, if you run it without specifying an event folder, it will work with the event that has the most recently changed configuration file. Unlike tsh, you can specify multiple events on its command line, and it will mirror all of them.

Before you start the mirror process, you need to add lines like the following to your configuration file:

    config ftp_host ='www.scrabbleplayers.org'
    config ftp_path ='tsh'

These specify the name of the host that will receive the data files, and where the files should be placed on that host. The files will actually end up in a subdirectory of the path that you specify, where the subdirectory has the same name as your local event folder. For this reason, you should avoid using characters other than letters, numbers, hyphens and underscores in your event folder name.

Then, when you are sure that you have a working Internet connection, try launching the command. If you can open a command window and navigate (using your operating system’s “`cd`” command to change directories), you can then enter one of:

    perl util\mirror-ftp REPLACE-THIS-WITH-EVENT-FOLDER-NAME
    util/mirror-ftp REPLACE-THIS-WITH-EVENT-FOLDER-NAME

Use the first one for Windows, the second for everyone else. You may omit the part about the folder name if you are using your most recent event folder. You may also find a clickable script icon in the utility folder that saves you having to do all of the above, depending on your operating system.

If all goes well, you should at this point be prompted for your username and password. These are the ones that you use to connect to your FTP server. The password will not be displayed on the screen as you type; it will be accepted when you press enter. Then, if your username and password match, you will see your files start transferring. Leave the window open for as long as you need them to keep mirroring. Restart the command/window if your network connection changes.

## Scoreboard Banners

You may wish to display a banner above the scoreboard, showing things like a legend or sponsor logos. To do so, make the banner content publicly available on a webserver, then specify its location and height with lines that look like:

    config sb_banner_url = "http://event.poslfit.com/2017/kingscup/banner.html"
    config sb_banner_height = 128

## Scoreboard Messages

You can have a floating message scroll around your scoreboard, giving urgent information to players, such as the start time of the next round, using the “`setESBMeSsaGe`” command.

If you have a browser session where you never want to see these messages, launch it with the query “`?nomsg=1`” appended to its URL.

## Scoreboard Geometry

By default, one scoreboard file is created per division, displaying a grid of five columns and four rows. You can override these three values using the “`config esb_geometry`” configuration option. For example, to set up Division A with one scoreboard showing 6 columns and 5 rows starting at the top of the field, and another scoreboard showing 5 columns and 4 rows starting 30 places down, use:

    config esb_geometry{'A'} = [[5,6,0],[5,4,30]]