There are several main challenges that I’ve identified over the years as a MOD writer. This list is by no means exhaustive, and I welcome comments or additional feedback. The challenges are:
I’m going to talk about each of these in upcoming blog entries. First, I want to talk about the middle piece: Document. Why start there?
Because I think most MOD authors have at least some experience with designing and then writing code for their MODs. But one of the challenges of writing MODs — not just writing code for your own site(s) — is documenting the code so that it can be distributed. If you have a large library of MODs as we do here at the phpBB Doctor this is even more important.
So what did I do? I wrote an add-on for phpBB… the phpBB Doctor MOD Manager™.
If you’ve checked out the forum, or even if you’ve just been reading this blog, you might have noticed the MOD Manager™ menu link at the top of the page. (The link doesn’t have the ™ ) If you click that link, you’re prompted to log in. That particular feature is limited to registered members of our board at this time. Actually, even if you’re a registered member that’s not good enough… you also need to be a member of at least one of the specific groups that have access to that page. (Access managed, I might add, by one of my favorite MODs: “Page Permissions”)
So what does it do?
By its name, you might guess that it has something to do with managing our library of MODs, and you would be correct. But it actually does more than that.
First, yes, it is a repository of all of our MODs. But it’s not just a listing, it’s far more than that. I have designed a database that contains all of the MOD components. At a very high level, it contains a MOD header, a list of MOD objects, actions on those objects, revision notes, even MOD author notes are stored in this database. MOD objects are generally files, but they can be anything that has an associated MOD action.
The list of phpBB files was created and stored in our database to support this system. Some examples of actions that don’t require files are SQL and DIY.
By storing everything in the database, our MOD becomes data. And with proper coding, interface, and templating, you can do whatever you want with the data once it’s in the database.
A brief side track: there are several common formats used to distribute a MOD. You can use BBCode, the phpBB Group’s MOD Template, or even just raw text. (A new development over the past year is the XML MOD-X template, more on that in a moment.) If you consider each of these to be a template, and the MOD is data, then … do you see where this is going?
As I write a MOD, I capture and store all of the MOD instructions into my MOD database. Sometimes — especially when I don’t do a good job in advance of designing my MOD — I enter the MOD steps into the database in the wrong order. It doesn’t matter, once I get everything entered into the system I have a “resync” process that puts everything in a specific order. Makes it nice and tidy.
The point of all of this?
When I complete a MOD, my documentation is also done. If I have done my job correctly and entered all of the MOD steps as required, I don’t have to do any more work.
I can run the phpBB Doctor MOD Validatorâ„¢ on this MOD, and it will validate all of the “Find” operations on any version of phpBB that I have on file. Normally I would only be interested in validating against the most current, but I can do older versions if I need to.
Suppose that an update to phpBB makes significant changes to posting.php for some reason. I can with a few mouse clicks get a list of all of the MODs in the phpBB Doctor catalog that modify the posting code, and run the MOD Validator™ on each of them individually, or all at once. So there’s another major advantage of this system… when new versions of phpBB come out I can in a matter of minutes know exactly which MODs will break (because of missing “Find” operations, at least) due to the update.
Now here’s the best part… suppose that you have a library of 50 MODs or so. (We actually have more than that in our catalog, most of them are not currently publicly documented.) Suppose as a hypothetical example the MOD Team at phpBB.com comes up with a new XML MOD template format. Without this system I would have to go through each and every MOD and convert them to the new format.
But not now. All I have to do is build a proper template that extracts the MOD instructions and displays them in an XML output template. By doing that, I can process every MOD in the catalog and output the new format in a matter of minutes, if not seconds. Now I don’t have the XML output template built yet, but I do have templates for showing basic MOD steps (the default), BBCode (useful for posting within a topic), and of course the venerable phpBB Group MOD Team’s text (.mod) format.
What does all of this look like?
One of my easy (but fun) MODs is called Annual Stars. It allows you to have a star by your name for each year of membership on the board, and it has been validated and released at phpBB.com.
See how it looks for yourself. (Link opens in a new window)
The phpBB Doctor Page Permissions MOD allows me to set custom permissions based on url page names in combination with url parameters. By knowing the ID for that MOD and the proper calling syntax, I can grant public access to that one specific MOD and let you play around with the various output formats. So the link I provided above will give you a taste of what’s going on behind the scenes at the phpBB Doctor, without revealing all of our secrets.
I believe that our custom phpBB Doctor MOD Manager™ is going to give us a real advantage once our MOD catalog crests the 100 MOD mark. This post is just a preview of one of the many exciting things we have planned for this site. If you’re thinking ahead you might have already figured out some of the other advantages that this system will give us, but I’ll save that for another blog post. This one is long enough.