Quite a bit of my work over the past year has been integrating ListServ (the grand-daddy of email discussion lists) with a modern web forum. I built the initial prototype from the ground up, but performance issues and lack of bells and whistles most users expect these days led me to evaluate several open source platform. After some research, a couple of false starts, and one near-disaster, I settled on Vanilla Forums.
Vanilla Forums is a mature open source forum platform with an active community in which the developers actively participate and listen to the ideas, wishes and rants of its community members. The Vanilla team has been working hard to develop formal Documentation for the platform, and while I would consider the forum administrator and user documentation complete, the developer documentation is only half way there.
I think part of the challenge in documenting Vanilla Forums stems from the developers us of Model-View-Controller (MVC) design pattern. MVC helps developers produce high-performance, reusable code, but it’s easy for an a developer unfamiliar with working with Object Oriented MVC code to get lost in layers of abstraction.
I found myself in this situation as I neared completion of my ListServ integration project. Much of my work over the past decade has been refactoring spaghetti code into some semblance of structure, and I’ve had a good bit of experience working with object oriented PHP, but I’ve never seen anyone drink the MVC Kool-Aid like the developers at Vanilla. Their code is tight, clean and performs extremely well, but it isn’t always clear what classes, methods and functions to use.
In future posts, I’ll try to dig down deeper in how to make Vanilla Forums behave, but for now, I’ll share my quick and dirty tips on where developers can get started building their own Vanilla Forums Themes.
- Take advantage of Open Source themes.
- If you’re building your own theme, don’t. Steal, borrow, or exercise some Open Source license on a theme you like that’s structurally close to what you want to do. Use Find/Replace (at least in Dreamweaver) to change all instances of the theme name. And don’t forget to rename any files that contain the them name. Oh, don’t forget to give yourself credit for your new awesome theme in the “about.php”.
- Don’t be a Smarty-pants.
- Smarty is a templating engine built to run on top of a PHP application. Unfortunately, Vanilla has only implemented a few “Smarty tags”, so using the Smarty theme templates (you can recognize them by their .tpl extension) is a bit painful for PHP developers familiar with using PHP at the presentation layer. To prove you’re smarter than Smarty, and to make building your own custom theme significantly less frustrating, delete “deafault.master.tpl” from your theme’s “views” directory and replace it with a copy of default.master.php (found in the “/[your-vanilla-root]/applications/dashboard/views” directory)
- Do it with Style(s).
- Vanilla’s stylesheet “strategy” can get messy fast. Create a “custom.css” in the “[your-theme]/design/” directory. As you modify classes, copy the whole class you want to use from “/[your-vanilla-root]/applications/dashboard/design/style.css”. You can often achieve everything you want out of a custom template just by modifying the stylesheet.
- Get plugged in.
- Plugins are relatively easy to use in Vanilla. If you want some special functionality out of your theme, look for a plugin that does something similar, and then make it your own. If you can, try to take advantage of Vanilla’s built-in modules and classes, but if you’re trying to build a simple plugin on a tight deadline, sometimes it’s easier just use ten lines of PHP to query the database and echo the results where your want them, rather than using a few hundred lines across several files to build to MVC design patterns.
- Do whatever it takes.
- If you can’t figure out where Vanilla is adding a particular element (usually it’s embedded deep within a module, inside of an enigma, wrapped in a mystery), don’t be afraid to commit CSS assassination (visibility: hidden !important). Just remember to come back to it once you’ve done your product demo.
Hardcore Vanilla developers will probably flame me over these five tips, but sometimes it’s better to be a pragmatist rather than a perfectionist.
After all, if the client is happy with the job, then it’s a job well done.