As I’ve spoken about on Bluesky, since there is activity moving forward on the ADM8 Database, it’s time to do an updated discussion of about the design of the program, in particular the code. Part of this is so that if I have to take more breaks, I can come back to it fairly easily. But mostly, this is for people who might be considering doing a similar project, to know how this works and they might be able to evolve a better design. I want to break this down so people can have good idea of how the whole thing works, generally.
I also want to say- I am enthusiastic and I can get by, but I’m absolutely no expert when it comes to programming generally- though I’m learning a lot from my friends. The conversations invariably go “I have this issue” “Oh?” “I’ve solved it with this hackneyed and awful way” “Have you tried using [xyz functionality built into the database” “Um, no”. For example, none of my queries use joins. (Which are more effective and efficient for pulling data from different tables). Improving my code is an ongoing project that constantly falls behind “making sure things work first” and well, professional things to be honest. Just as a background- I did start in Comp Sci before I switched to history.. but I repeated first year of my undergrad (long story), and I didn’t do well in any of my second year comp sci courses. (Passed, but nothing spectacular). I never took any of the 3rd year courses, including databases. Actually the summer after I decided to switch to History, I had a summer job working for a web development company- that’s where I picked up all of my skills with PHP and my experience with coding for databases.
WordPress
The first thing that has to be understood is that I chose to modify or use WordPress because when I came up with this project this website already existed and I couldn’t forsee being able to afford hosting etc for a second website.
Using wordpress has certainly had pros and cons. In the pros column, thete’s the database, and with PHPmyadmin I can access it and create custom tables and all kinds of things. On the minus side, while there’s lots of plugins for *reading* from custom databases there are no plugins for *writing* to custom databases.
Since my PHP writing skills are.. somewhat medium, what’s ended up happening is that I’ve basically worked around WordPress instead of fully integrating with WordPress. This has created some issues when it comes to displaying things, which I’ll talk about that in that section. There is the idea of turning the database code into a plug-in, which would possibly allow me to work through WordPress instead of work-around, however this is probably beyond my skill level. Certainly including AJAX so that everything can be done in the same page instead of opening new tabs and reloading pages, but AJAX is definitely over my head. (For now, probably for ever. That’s really specialist stuff).
Code Structure
I guess the second thing is to explain how WordPress conceives of the content that is displayed. With a basic HTML website, each page is a separate file, which means you can do all kinds of different things on different pages. In WordPress, there’s a bunch of PHP and AJAX code in what is called a “theme”, and these themes interpret all the content for the webpage, which is stored in a database. Then, you have “Pages” and “Posts” Pages are kinda static, though I believe they’re interpreted by the themes just like posts- but they have a relatively static URL. On the otherhand, you have posts- which have their own URL.. and are supposed to be conceived of differently somehow. While I really understand the difference, the point of this is that WordPress allows for users to have “custom pages”, in which you can write PHP code so the page can either use parts of the theme, if you want to, or essentially you can write your own code and not have the custom page use the website at all. What I’ve ended up doing is mixing the two. I keep parts of the theme that provide the borders of the webpage. But the rest of it is the code I write myself.
the complication here is plugins. One of the best things about WordPress are the plugins- the snippets of code that add additional capabilities to the website but because they plug into the larger WordPress code, they often work just within the theme. As a result, I’ve been very limited in the number of plugins that I’ve been able to use.
So, I have two custom pages for this project.
originally I had several. One for the landing page, one for the second stage of choosing how to access the data in the database, and one for choosing reports, ships, personnel or places as well as viewing the actual reports. One of the major changes I did some time ago was to redesign things to have two: the Research Interface, and the Transcription Interface. This means that there are more if statements and code on each of these pages than there were before, but on the other hand it very much centralized where I have to make changes, where I need to make changes.
One of the things that I have done to make the code simpler is that the Research and Transcription interfaces actually have as little code in them as possible, as the if statements in those pages call functions that are kept in other files.
My code is further divided into three files
The first one is “ADM8 Project Functions”. Originally, this is where all of my functions/code were saved. However, after this grew to an absurd number of lines of code and I couldn’t find anything anymore, I split it into two further files, one dealing with Database interactions and one dealing with the User Interface.
It probably makes sense to talk about these in order of interaction with them. My general goal is that a function should only do a single thing, which means there’s a lot of functions but also hopefully less repeated code. (there’s still a lot of repeated code. I’m working on that)
User Interface Functions
This file contains functions for anything that puts print onto the screen, or involves creating forms or populating forms with things that users can interact with eg dropdown boxes, text boxes, maps, photo galleries etc. Though in the case of the maps and photo galleries, I actually use plugins for those- though I have to do this weird thing where the shortcodes (which are the the HTML- like codes that WordPress uses) have to be escaped out of text and it’s really annoying and quite fidgety, but it gets things done. (Long story short- if you can, work through WordPress, rather than around it. It’ll make your life so much simpler. In particular I use Leaflet Map for creating the maps that appear on most report-viewing pages. I also use Next Gen Gallery to create the photo galleries so that when researchers are viewing a whole report. Functions in this file are called by functions in the ADM 8 Project Functions file.
ADM8 Project Functions
I wish I could find a better way than just to use the file name, but this covers a lot of things in the middle. This is the file file that contains the functions that actually sort out what should be displayed on the page for people to see, whether they are transcribing or researching. These functions include what would have been called a “main” function for me in the old days (with a different ‘main’ function’ for each research/transcription task that a user could choose).
Functions in this file also include functions that sort and arrange data brought the database to make it presentable. For example, this includes taking the list of all reports in the database, all ships, all personnel or all locations and formats them for going into a drop-down box.
The other important thing to say about PHP is that- well it’s iterative, so code starts with the first line and goes down to the bottom. There are functions here that deal with the data entered by people doing transcriptions (usually my friend Larry), and process it, and then call functions to either send it to the screen, or interact with the database. But often, functions in this file call other functions in this filed to manipulate things before they’re sent either to screen or DB.
Database Functions
The are two classes of functions within this file- those that insert data into the database (which are written from scratch because WordPress has no plugins designed for working with custom databases) and of course functions that query the database to pull out data to display to users. Now, the important thing here is that WordPress has an object- WPDB – that has a number of functions that they want you to use for writing to the database (and for querying it, too). These functions do things like make you pass in two arrays, one containing values to be passed into query, and the second one containing short codes for the type of data that you expect to be passing in, plus all the values passing in are esecaped so they are treated just as text, or integers or whatever but absolutely not as SQL. This very much does improve the safety of working with databases as it helps to avoid the SQL injection attacks (bobbyDropTables) or whatever. It is possible to work around these, but it would be silly to do so. There’s also things that make error return values predictable and functions for getting error codes and error messages. At the level that I’m working at, there’s no reason to be directly sending SQL to WPDB except laziness. (I have been sometimes lazy and purging that and replacing it with proper WPDB calls is a high priority).
Anyways, so that’s a rough outline of how the code for the ADM8 project works, and if anybody has any questions I’d love to explain in more detail (if it’s interesting)
