The Borg: A Learning Theme for Drupal

In 1993, web development was a straightforward affair. Type HTML in a text editor and view it in a browser. Since the information was coded together with it's presentation, early web design was essentially page layout. This simple recipe kept me fed for many years, but came up short when I needed to create a knowledge management system for an evolving architecture firm. Obviously, HTML alone wasn't going to do the trick!

Fortunately, a friend in the IT department pointed me towards drupal.org and set up a 4.7 installation on the internal server. I began by learning Drupal at the application level, one menu item at a time. This gave me a basic understanding of functionality and a sense of how contributed modules would get me close to my goals. But I still felt like I was working with Drupal at a distance, like my hands were reaching through holes in a glass wall with rubber gloves attached.

Being an early web designer, I knew I wouldn't feel comfortable working with Drupal until I could put the information I needed exactly where I wanted it. Over time, I've developed a WYSIWYG approach to development in which efficient visual design reveals essential functionality. But with no prior PHP or MySQL experience, how should I begin learning Drupal design and development?

Lullabot

Fortunately again, the evolving company sponsored my attendance at a Lullabot Theming Workshop, which was excellent! (I'm in the photo wearing a green hat.) I honestly hadn't felt that excited about code since freshman year of high-school, when my buddies and I would write rinky-dink video games in BASIC on a TRS-80. And as it turned out, PHP was just as basic.

The presenters had us download a simple HTML page template and rename it page.tpl.php. Then, where the title of the page appears, we were instructed to insert a strange new tag:

We loaded the page in our browsers and... Hello World! There was the name of the site I had entered on the admin/settings/site-information page. What had always been a fixed and rigid index.html file now sprang to life with the inclusion of dynamic data. My eyes began to open to the possibilities.

On the train home that evening, I made a blank page.tpl.php file and started printing all of the variables I could recall from the afternoon workshop. I found myself wondering, "How can I find out all of the variables that are available to print?". The next morning, this question was answered with a handy bit of code that presents a formatted array of variables and their values:

For the next few weeks I methodically made my way through the items in the array. I examined phptemplate.engine to determine how each was created, often following a trail of nested functions using api.drupal.org. I dutifully read each line of code, even though I didn't know PHP yet. The chapters on Drupal 4/5 theming by Douglass, VanDyk/Westgate and Schnapp were invaluable guides.

The Borg

During my variable investigation I created a two-column HTML table in my page.tpl.php file. The left column contained the name of the variable and the right its printed value. Halfway through this process it occurred to me that I could probably write some code to generate the table from the get_defined_variables() array. That's when my PHP skills started flapping their wings.

In my first PHP script, a foreach() loop steps through each item in the get_defined_vars() array, skips the redundant variables[] array, converts variables that contain code into HTML characters, uses <pre> and print_r() to present any arrays or objects, and wraps each table row in HTML comments identifying the variable and template file - just in case it helps to view source. I put this bit of code in each of the tpl.php files that make up a theme and used CSS to give a distinctive color to each: page, node, block, box and comment.

At the end of this learning experiment I had a new theme, but what to call it? For some reason I recalled the Star Trek TNG episodes with the Borg. There's something funny about humans cruising the vacuum of space in an aerodynamic disc while their enemies pursue them in a cube. Since there's no air resistance in space, the cube is entirely suitable, probably easier to make, definitely more efficient in terms of capacity... and wasn't it always outrunning the Enterprise? In an inverse manner, I thought it delightfully absurd to navigate a database with alphabetical lists of variables inside a grid of nested tables, hence, The Borg.

Being Borg

While working on my first "real" Drupal theme, I assigned The Borg theme to a test user and then logged in as that user in a different browser. This gave me a quick reference of available variables as well as the following features:

• The color coded tables demonstrate at-a-glance how pages are put together from template files, which is good for a conceptual understanding of the theming system.
• Viewing the HTML source code reveals the beginning and end of each variable's output clearly marked with HTML comments.
• The template name in the table header (i.e. page.tpl.php) links to a drupal.org page with descriptions of the variables available to that template.

However, the greatest value of The Borg came from the learning process used to create it. I recommend this approach for anyone coming to Drupal with minimal HTML and PHP knowledge:

1. Read about the theming system at drupal.org, or in a good book.
2. Make a new theme from scratch starting with a blank page.tpl.php file.
3. Print all available variables to page.tpl.php using the second code snippet listed above.
4. Print each variable in the array and investigate how it is created in phptemplate.engine.
5. Investigate any functions that are referenced using api.drupal.org.
6. Repeat from Step 3 for the other standard template files in a theme: node.tpl.php, block.tpl.php, box.tpl.php and comment.tpl.php.

The knowledge gained from this exercise, along with some basic HTML and CSS skills, should provide a solid foundation for any aspiring Theming Ninja. One cautionary note - make sure to assign your theme-in-progress to a test user, do not make it the default theme, and log in as the test user using a different browser. This will ensure that you can always log in as the administrator using a fully functional theme.

Epilogue

At the recent DrupalCon Boston 2008 I was excited to see this concept taken to goal by Moshe Wietzman's Theme Developer Module for Drupal 6, which offers a handy Firebug-like tool for inspecting variables and associated functions.

Try The Borg at demo1.voidengineering.org or download it below.