A Game of Tag

Hey all, hope that the last few weeks have seen you well. I’ve been stealing away time here and there to finish up pending features for the site and have plenty exciting stuff to share this time around.

I’ll start, however, with something that makes my life much easier but is unlikely to elicit much response from you. The flashier stuff can wait.

I’ve completely removed all instances of a global constant that was used for database queries as a prefix for tables. Which …, well, it might not sound very important. But it is! Basically, every single database query made (like when getting information about a post, inserting data, opening up the front page etc etc) tends to be a statement that is formatted in a certain way. You need to specify what kind of action to which table and what kind of data you expect back. These lines of code can get long and somewhat difficult to parse especially when there’s a lot of variables or it’s a complex operation. That can’t be helped by the most part.

The bit that I removed was a 11-character constant—that also had to be escaped every time, taking at least 6 more characters in the prepared statement—that was just before the table part. Seeing as this (or a stand-in variable) was there for hundreds if not thousands of lines in the code base, it makes a large practical difference to simplify things. Less work to write new statements and it’s easier to parse existing ones. Actually replacing instances wasn’t too hard thanks to various tools and usage of strict regular expressions. But, still, I had to make sure that nothing would break when doing this; checking for any callbacks or references that used the constant meant rewriting bits here and there and testing for breakage under various scenarios. The tricky bit of modifying any legacy code and practices is making sure that nothing catches on fire afterwards!

You may be wondering—astutely enough—why bother to have this prefix in the first place? Well, there’s legitimate reasons to have prefixes in table names, such as avoiding collisions when dealing with multiple databases with a shared code base (common enough for large business setups!) That seems unlikely as the main reason given the … limited scope of Kusaba X. Knowing some of the attitudes of the developers and some of its history, I think that it was more along the lines of wanting to provide optional security through obscurity. It’s more difficult to exploit a database through a bug if you don’t know how to query what you want. Whatever the reason, however, given that THP has been its own thing for a time and diverges significantly from that code base, there was no compelling reason to keep it in.

Keeping to the theme of making life a little easier, there were some organizational changes made  to the management side of things. The navigation menu had always been somewhat unwieldy with a few dozen options ever-present. I simplified some of the sections and entries, merging some and also adding collapsible sections for the less-used functionality. While it’s not all there yet, I think that it goes a far way in reducing clutter and making things easier to process at a glance.

For the admins and mods, the menu has been shrunk significantly though the rest of the staff has always had less to contend with.

While most of the site is styled with external stylesheets and output is formatted according to templates the management side of things still uses a lot of in-line theming and section-specific code. It’s somewhat of an inherent problem with the design of the management class main file (by far the largest single file in the code base with around 4000 lines of code despite my attempts to slim things down over the years).  Some of the changes this time around tried to consolidate further with partial success. While getting a consistent look with a single external style sheet would require a massive effort, we’re at least a step closer now.

Similarly, there’s historically been an amount of in-line script in specific parts of the management pages. I can happily report that I did manage to centralize that, however, standardizing what is run and when and placing a fairly slim file that’s loaded just the once. Even the new features—which I’ll get to presently—use this new convention and save effort in duplicated code. So I’m confident that I’ll eventually be able to wrangle the rest of the old code into a more rational and maintainable state.

Just as a final point on the subject of looks—there’s a very inconsistent way in how tables and data are presented. Fixing that requires a rewrite of the code generation process for many pages and so I accept the small every day annoyances of different looks and interfaces for the time being.

But well, it’s time to get to the new features that matter for other people other than me. First and foremost, the improved tools for tagging are now live after being delayed from earlier updates. There’s multiple systems that are impacted by this and I’ll explain them piecemeal.

On the more conceptual side of things, I wanted to have tags be more useful and clear in their application. Part of the solution to that was to add brief descriptions to each one, making them easily understood when applied to a story. I added to the database to accommodate for this new data and then had to adjust how the information is retrieved by existing processes. Because I set up things like the story list sensibly, the basics weren’t a big deal to implement.

What was a fair deal more work was setting up relevant sections in the management-side of things. I set up a new interface where staff can look up all the tags, look them up by category, or specifically. Presented with results, they can have their information edited (or deleted by an admin) without too much fiddling about. The aforementioned script consolidation helps here as things like character counters for the input fields work seamlessly and is reminiscent of the existing interface for story entry editing.

There’s lots I can say about the behind-the-scenes stuff, like sanity checks and integration with other systems but I will spare you the dull details. I’ll just emphasize that the most time-consuming parts are polishing up implementations, testing, and the small details that make things work as smoothly as possible.

Building upon the idea of tag management, I also extended a previously moderator-level-and-higher section that dealt previously dealt with tags awaiting approval. Writers had been able to suggest tags that needed to be approved for quite some time and so I built a little interface where I could review and accept or deny them. While I can still do that (and now edit pending entries!), it’s also become a place where the rest of the volunteer staff can directly submit their own tags without going through the writer-side of things.

Incidentally, the writer-side of tags has also seen a large change. It’s been updated to be more along the lines of the management side of things. I got rid of the large list of tags and simplified the interface significantly; it makes for leaner code and quicker access times; the essentials are intact with submission and a look at tags pending approval being easy. Additionally, things look good no matter the screen size. That holds true for everything else I’ve mentioned, incidentally. Going the extra mile to make sure that things are legible on phones, tablets or anything else as well as a proper computer takes more effort but improves the experience for everyone.

That brings us to the tag list itself. It has existed for a long time but hasn’t really been advertised, mainly linked to in the user management pages and the like. As the name implies, it’s a list of all the tags that exist in the database. Since we now have tag descriptions, it wouldn’t do to simply have a large, chaotic list. Clicking on a tag now pulls up its description underneath and it scales in size according to the available screen real estate. I thought about having individual pages for each tag, as they do on other sites, but concluded that it’s too much complexity for little added benefit. So long as the entries are easy to parse at a glance—thanks to good spacing and styling—it doesn’t matter if they’re all displayed at once.

Unmentioned in detail is that all of these pages are also brought up the standards of the rest of the site in terms of having proper footers, color schemes, and otherwise being better integrated. There’s a lot of small details that are appreciable if you play around in each space.

Like, for example, in the tags list and submission interfaces, the categories of tags are colored. These correspond to the colors that exist on the story list and account for both light and dark themes. It’s meant to be an easy way to tell what is what and to reinforce (if only subconsciously) that there’s different types of tags and they each have their descriptive use. It also looks good and is unobtrusive!

… And that’s a good segue to the story list. I’ve steadily improved its layout and features over the years and it’s currently in a good state in my reckoning. Some changes behind the scenes to accommodate some of the changes I’ve already mentioned. Only a couple that would be noticeable to an end user.

A mysterious “?” now hovers above the tag input field on the page. Hovering on it reveals an explanatory title. Clicking on it—you’ve guessed it—takes you to the tag list. It’s a small, unobtrusive way to include the list into a compact interface in my opinion. I didn’t really didn’t want to break up the flow of the input fields or the story results so I think it’s a good solution. More satisfyingly, however, is the fact that it gets repositioned to be roughly in the same relative spot even when the window is resized, using vanilla JS to generate the effect. In other words, will look good on any device barring silly edge cases.

The other thing that ought to be noticeable is a little nagging message telling people to help out with tagging and leading them to our Discord and Matrix communities. It’s a dismiss able message that you can click away and won’t appear again. Should a new message appear in the future, however, it’ll have to be dismissed again. It is hoped that this will get people more aware of the fact that a site that’s all about the community ought to have the community doing things. It’s a theme I’ve tried to push at times with mixed results.

It’s a message that will be echoed on the front page as well and I’ll mention in the other communities for good measure. With well over a thousand stories, it’s a gargantuan task to tag and write synopses for them all. The only way it’s going to get done properly is with crowd-sourcing. I don’t expect that these messages will have much of an impact but it’s about time to try to get more people involved again.

Well then, I think I’ve rambled on for too long already. There’s more that I could say but I think I covered the major points already. There’s more that I’ll continue to do to fix bugs, refine systems, and work slowly on bigger changes. I can’t really tell you yet what it is that I’ll work on in earnest next because I’m not sure myself. Still, I think that there’s interesting things on the horizon, some of them facilitated by a better tagging system.

Until next time, take it easy!