Templates like that...

Hey there, hope you’ve been well. For this exciting installment of my technical rants, I’m focusing on templates. No, not that kind. The web programming kind.

In order to make a long and boring story short, what I mean by template is a file that is fed data to produce an automated output. These are commonly used to facilitate controlling what is output to the client (ie you on your browser) and it uses a templating engine with its own syntax to interpret both template and the data its fed. This layer of abstraction helps keep other code tidy and avoids duplication of effort.  

Yeah, okay, good to know. In THP’s case the templating engine has a pivotal role in just about everything. All those threads we so enjoy are generated thanks to a combination of templates, PHP code and data from the database. Whenever a post is made (or deleted), the site does its thing and creates new files which you see. The front page is likewise dependent on templates as are some of the other functions like RSS, archiving and some moderation options. Changing how the site looks and what data is presented often involves tangling with the templates.

Kusaba X opted to use a templating engine named Dwoo. It was a fork of the venerable Smarty which focused on more modern (at the time) code and optimizations. The trouble is, it’s had several periods of neglect over the years. It had been modernized after a period of being a moribund project it has once again been more or less abandoned. Add to that less-than-stellar documentation and so replacing it has been a middle-to-long term item on my to-do list for a while.   

As of a few days ago, Dwoo has been completely removed and replaced with Twig. I took a look at various templating engines but ultimately went with Twig because it was a) not that niche, b) maintained and actively developed, c) its syntax isn’t a huge departure from Smarty/Dwoo, d) has decent documentation, and e) does not seem to be over-engineered. The last point is particularly important I find when bringing in code that one hasn’t written themselves as having too many things to worry about can put a dent in productivity.  

Replacing the template engine was a somewhat tedious affair. Not only did I have to do all the background research into a replacement but I also had to learn how to use my pick. Oh, and yeah, the various template files had to be at least partially or entirely rewritten to account for the new syntax. This meant editing 22 files, each ranging from a dozen to a few hundred lines of html and template syntax. I took advantage of new features wherever I could and replaced most things and cut a few minor (mostly unused and obsolete) things in there as well.  

It wasn’t really viable to just do a search and replace for most things. Actual words and other syntax varied too greatly for me to able to automate the process. I had to go line by line across every template file to make sure all Dwoo style functions were gone and that the new code was also bug-free. A missing curly brace, a stray single quote or doing the wrong thing with an in-built function makes the whole thing outright not work. A good editing program can only do so much to minimize the amount of effort that’s required.  

Every step of the way I also made sure to test in my local server environment, to see if there were any subtle bugs or quirks that I had to account for in how pages were output. In absolute numbers, there weren’t that many but I did have to adjust a lot of how the front page works and several things in the threads to make it seamless to the end user. 200 or so test posts and several days later and I was fairly certain I had dealt with template-related bugs.  

But It wasn’t just the templates that needed modifying either—the PHP files that invoke the templating engine had to be looked at and made to work as well. The worst part of Kusaba X’s code is the PHP class governing how threads and posts are built. It’s about a thousand lines of code that has the optimistic comment from at least 10 years at top, stating: “TODO: replace repetitive code blocks with functions.”

As you might guess, a lot of that code invokes the templating engine before combining bits and pieces of information to actually write an html file. Understanding bits of the code or making tweaks is easy enough but there’s a major problem in comprehending the flow of information around the various interrelated parts of the file. Let me give you a quick example: passing a variable to the template engine may not work properly if it’s not in the right place. Too late or two early and you get an error/crash or, worse, a silent failure which you only really notice when you look closely at bits of your board page’s source code and realize that it has no title and users can’t pick css themes (this was a thing I had to sort out).  

Thankfully, the other PHP parts like the RSS feeds and the management class (which is several thousand lines of code but more self-contained) were more straightforward to wrangle into submission. That fact likely kept me from from fashioning a noose and embarking upon a journey to Gensokyo. There are still some parts that could use some tidying up since it’s not always clear when some parts of the code are just outright redundant but it’s fine for now. 58 files and several thousand lines of code modified seem like a good stopping point.  

I could ramble on about all the technical stuff but there’s a good reason why changing the template engine is more than just modernization for the sake of it. A lot of the new content and features that I want for the site will require new templates and integration. Having a good foundation for that future work was important. There’s no point in overhauling, say, the story list if it’s just another huge mess of unreadable code. Nor in adding [REDACTED] when it comes to tools readers and authors can use in threads. All that shiny new stuff is easier to do when there’s less legacy code to mind.  

Finally, as an almost afterthought, there are a few minor things that also made the cut this time around. I overhauled the statistics page in the management section of the site, got rid of some useless libraries in the process, and also fixed up some minor CSS and Javascript miscellanea. Yeah, not very notable for the end user but a lot of the work that needs to be doing is like that.  I still have a few things on the drawing board and other features partially implemented. I’m not sure what will be finished next but I’d like to refocus on the mobile user experience again if possible.  

Until next time, take it easy!