CUCC Expedition Handbook

Troggle - programmers' guide

Programming Guide

If you want to roll up your sleves and fix some horrifying annoyance that is bugging the hell out of you then you have come to the right place.

you will already have tried all these..

• the Data Maintenance manual.
• Troggle - Maintenance - list of maintenance tasks
  
• Troggle - Architecture - diagrams, files, structure
  

and you will have dismissed them as too trivial for your needs. You will have skipped over all that nasty confusing Django stuff:

Troggle and Django - The Django web framework we use
Troggle: updating Django - Upgrading troggle to use a later Django version

• Troggle server configuration - troggle running on a new server
  
• Other scripts
• Additional Scripts - more detail
  
• Version control - why we have repos
  

You want to dive into the real stuff and add missing fields to the core data model:

• Troggle - Data Model - syntax-coloured list of classes, instance variables and foreign keys
  

We admire your drive and enthusiasm. We were like you once.

First, you need to get the "expoadmin" password from a nerd. Then you will be able to dive into the online admin system where you can explore and poke the live system and database using the system admin control panel. This has a data structure browser for the classes and fields of the system as live and in-use: all the foreign keys and relationship cardinalities. (This is not the same thing as the troggle control panel which is for deeper data management: bulk uploading and export of data files.)

And, you may be surprised to discover, we have given a lot of thought into how to make it easier for you to get involved in the programming while not screwing up this multi-decade software project.

Perhaps an external add-on?

Perhaps you can program something external to troggle, in JavaScript say, using troggle data?

• JSON export - how to extract cave and expo data in JSON format.
• Compressed data export - how to extract cave and expo data in gzip/tar format.

Creating your own system development machine

It's a simple sequence which steadily builds your expertise:

1. Use the online forms and reports.
2. Read documentation to get the concepts and structures into your head, so that you can see how it all fits together and works.
3. Explore the public pages of the 4 git repositories including all the source code
4. Use the online forms and reports together with 'survex' and 'therion' installed on your own laptop.
5. Get the 'expoadmin' password and explore the live system online: watch the data change in real time
6. Configure an ssh key and Filezilla or scp/sFTP.
7. Configure a basic expo laptop
8. Configure more cave software on your laptop
9. Configure a troggle development machine - a laptop where you have cloned the repos and installed django. Installing is the same as updating Django. See Troggle: updating Django.

Fixing broken URL dispatch

This happens all the time. If ever troggle is crashing on you very mysteriously, it is almost certainly due to a typo in troggle/urls.py . Odd but true.

Fixing a broken HTML template

Running databaseReset

• Troggle - Data Import - reset and import data
  

Running the test suite

• Troggle - Page tests and smoke tests
  

This manual is very incomplete - notes

[Note that /survey_scans/ is a url published by troggle and is not the same thing as the real directory /expofiles/surveyscans/ at all.]

Only a small part of troggle's original plan was fully implemented and deployed. Many of the things it was intended to replace are still operating as a motley collection written by many different people in several languages (but mostly perl and python; we won't talk about the person who likes to use OCamL).

Archived updates

Since 2008 we have been keeping detailed records of all data management system updates in the version control system. Before then we manually maintained a list of updates which are now only of historical interest.

A history of the expo website and software was published in Cambridge Underground 1996. A copy of this article Taking Expo Bullshit into the 21st Century is archived here.