Runner Form — User Guide

Audience

Racing analysts and internal staff looking up horse/jockey/trainer form. Requires a login — ask a maintainer for credentials (see [[bugs]] for why they're currently hard-coded rather than per-user).

Setup (first time)

1. Clone the repo and cd into runner_form_fixed.
2. Create and activate a virtualenv:

   python -m venv venv
   venv\Scripts\activate
   

3. Install dependencies: pip install Django mysqlclient (or pip install -r requirements.txt if one is present).
4. Confirm config/settings.py can reach the qdb database at 138.226.220.168:3306 — network access to that host/port is required.
5. python manage.py migrate — this only creates Django's own internal tables; the app itself reads the existing remote database and needs no migration of its own.
6. python manage.py runserver, then open http://127.0.0.1:8000/.

Verifying the install

After logging in you should land on WINX's (AUS) brief form automatically. Confirm:

• Horse name, sire, dam, owner appear at the top.
• The Sales Information table shows data.
• Race cards render on the detailed tab.
• Date / Meeting / Race dropdowns populate.

If any of those are empty, see Troubleshooting below or [[bugs]].

Using the app

Finding a horse

• Type 3+ characters into the search box for autocomplete (calls /api/search/).
• Or use the toolbar: pick a date → meeting → race → runner, each dropdown populated by the corresponding /api/* endpoint.
• Or browse Form Guide (/form/guide/) — today's meetings and races by venue, with a country filter; click a race to see its runners inline.

Runner (horse) page

• Brief tab (default): last 5 runs, career stats, sales info, and By Country / Jockey / Trainer summary cards (5 rows per page, "Show More" pagination).
• Detailed tab: full race-by-race history. Controls: show latest 10 / 20 / all runs, filter by track, toggle Barrier Trials to swap in trial cards, Collapse/Expand All for in-running comments, pagination (10 cards/page), and Export Form (browser print, print-optimised layout).
• Click a past-run row to expand its notes/stewards-comments row.

Jockey / Trainer pages

Same brief/detailed pattern — ride or entry history with aggregated stats by track, class, and distance.

Troubleshooting

Symptom	Likely cause	Fix
Login loops back to the login page	Session cookie not set correctly	Confirm SESSION_ENGINE = signed_cookies; clear cookies and retry
Static files 404	collectstatic not run	python manage.py collectstatic --noinput
Meeting/date dropdown empty	No races on that date, or DB unreachable	Try a known date from /api/dates/; check DB connectivity
Sectional positions (12m/8m/6m/4m/2m) show —	Race predates ~2021 sectional data load	Expected — see [[database-schema]] known data gap
Sales section says "No sales data available"	Horse wasn't sold at a tracked AUS/NZ public auction	Expected, not a bug
Barrier Trials toggle does nothing	window.toggleTrialFilter not globally accessible	Must be defined outside any DOMContentLoaded closure
Cache shows stale data after a query fix	Old versioned cache key still valid	Bump the version suffix (e.g. v7 → v8) in queries.py

See [[api-reference]] for endpoint details and [[architecture]] for how requests flow through the app.