<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Handbook Troggle NOTES</title>
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
</head>
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
<h2 id="tophead">CUCC Expedition Handbook</h2>
<h1>Troggle - programmers' guide</h1>
<img border="1" class="onright" width="150px" src='tricky-troggle.jpg' alt='git logo'/></a>
<h2>Programming Guide</h2>
<p>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.
<h3>you will already have tried all these..</h3>
<ul>
<li><a href="../computing/manual.html">the <em>Data</em> Maintenance</a> manual.
<li><a href="trogmanual.html">Troggle - Maintenance</a> - list of maintenance tasks<br>
<li><a href="trogarch.html">Troggle - Architecture</a> - diagrams, files, structure<br>
</ul>
<p>and you will have dismissed them as too trivial for your needs. You will have skipped over all that nasty confusing Django stuff:
<ul>
<a href="trogdjango.html">Troggle and Django</a> - The Django web framework we use<br>
<a href="trogdjangup.html">Troggle: updating Django</a> - Upgrading troggle to use a later Django version<br>
</ul>
and you will also also have merely skimmed as irrelevant or trivial:
<ul>
<li><a href="serverconfig.html">Troggle server configuration</a> - troggle running on a new server<br>
<li><a href="scriptsother.html">Other scripts</a>
<li><a href="scriptscurrent.html">Additional Scripts</a> - more detail<br>
<li><a href="../computing/repos.html">Version control</a> - why we have repos<br>
</ul>
<p>You want to dive into the real stuff and add missing fields to the core data model:
<ul>
<li><a href="datamodel.html">Troggle - Data Model</a> - syntax-coloured list of classes, instance variables and foreign keys<br>
</ul>
<p>We admire your drive and enthusiasm. We were like you once.
<p>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 <a href="/admin/">system admin control panel</a>.
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 <a href="/troggle">troggle control panel</a> which is for deeper data management: bulk uploading and export of data files.)
<p>And, you may be surprised to discover, we have given a lot of thought into how to make it easier for you
to <a href="../computing/contribute.html#programming">get involved in the programming</a> while not screwing up this multi-decade software project.
<h3>Kill it with Fire</h3>
<a href="trogkill.html">
<img border="1" class="onright" width="150px" src='../i/dumpsterfire.jpg' alt='dumpster fire'/></a>
<p>Everyone at some point feels like giving up and wonders if we should just rewrite it all from scratch using 'modern' techniques.
Several of us have given this a lot of thought, see <a href="trogsimpler.html">'A kinder, simpler troggle'</a>,
the <a href="trog2030.html">2030 plan</a>, <a href="trogspeculate.html">architecture constraints</a> and most importantly, <a href="trogdjango.html#4layer">the 4-layer stack</a> <em>any</em> future technology with some public URLs would need to emulate.
<p>We have also been learning from the global software community when you really do need to 'Kill it with Fire': what are
the characteristics of code and of organisations that mean that it is a good idea to give up, and if so how to
manage the rewrite. The answers are "almost never" and "don't": as explained in <a href="trogkill.html">this summary of the book 'Kill it with Fire'</a>.
<h3>Perhaps an external add-on?</h3>
<p>Perhaps you can program something external to troggle, in JavaScript say, using troggle data?
<ul>
<li><a href="exportjson.html">JSON export</a> - how to extract cave and expo data in JSON format.
<li><a href="exporttgz.html">Compressed data export</a> - how to extract cave and expo data in gzip/tar format.
</ul>
<h3 id="devtree">Creating your own system development machine</h3>
<p>It's a simple sequence which steadily builds your expertise:
<ol>
<li>Use the online forms and reports.
<li>Read documentation to get the <a href="trogarch.html">concepts and structures</a> into your head, so that you can see how it all fits together and works.
<li>Explore the public pages of the <a href="/repositories">4 git repositories</a> including <a href="/repositories/troggle/.git/tree/">all the source code</a>
<li>Use the online forms and reports together with 'survex' and 'therion' installed on your own laptop.
<li>Get the 'expoadmin' password and explore the live system online: watch the data change in real time
<li>Configure <a href="../computing/keyexchange.html">an ssh key</a> and <a href="../computing/fzconfig.html">Filezilla</a> or scp/sFTP.
<li>Configure a <a href="../computing/basiclaptop.html">basic expo laptop</a>
<li>Configure <a href="../computing/yourlaptop.html">more cave software on your laptop</a>
<li>Configure a <a href="troglaptop.html">troggle development machine</a> - a laptop where you have cloned the repos and installed django. Installing is the same as updating Django. See <a href="trogdjangup.html">Troggle: updating Django</a>.
</ol>
<h3>Fixing broken URL dispatch</h3>
<p>This <em>happens all the time</em>. If ever troggle is crashing on you very mysteriously, it is almost certainly due to a typo in <var>troggle/urls.py</var> . Odd but true.
<h3>Fixing a broken HTML template</h3>
[to be written]
<h3>Running databaseReset</h3>
<ul>
<li><a href="trogimport.html">Troggle - Data Import</a> - reset and import data<br>
</ul>
<h3>Running the test suite</h3>
<ul>
<li><a href="trogtests.html">Troggle - Page tests and smoke tests</a> <br>
</ul>
<h3>This manual is very incomplete - notes</h3>
<p>[Note that /survey_scans/ is a url published by troggle and is not the same thing as the real directory /expofiles/surveyscans/ at all.]
<p>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).
<hr />
<h3><a id="arch">Archived updates</a></h3>
<p>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 href="../computing/update.html">a list of updates</a> which are now only of historical interest.
<p>A history of the expo website and software was published in Cambridge Underground 1996. A copy of this article <a href="../c21bs.html">Taking Expo Bullshit into the 21st Century</a> is archived here.
<hr />
Go on to: <a href="trogarch.html">Troggle architecture</a><br />
Return to: <a href="trogintro.html">Troggle intro</a><br />
Troggle index:
<a href="trogindex.html">Index of all troggle documents</a><br />
<hr />
</body>
</html>