How I converted my HTML template into a Drupal 6 theme
In my recent Boston Drupaltherapy workshop I got stuck on an in-class example of how to convert a well-formed HTML template into a Drupal 6 theme. I was showing this off as an example for how new Drupal users could attack themeing in a lightweigh way by using an HTML template as a starting point. I picked a simple HTML template that I found with a free license on a free HTML template site.
The excercise uses Drupal's core default theme called Garland and mercilessly steals portions of theme code from it to paste into the correct places in the new HTML template. I've got screenshots below that show the windows for Garland open right beside my HTML template window so I can make direct comparisons between the files and their contents.
Here is my original default theme and some sample content:
Here is the unviolated HTML theme, Blackfairy, consisting of one HTML file and one CSS file:
Here are the directories of each theme beside each other, Garland on left, Blackfairy on right:
First things first, in order for Drupal 6 to acknowledge and detect that my new theme Blackfairy exists, I have to move the HTML template into my sites/all/themes directory. New in Drupal 6, I also need to create a .info file that will tell Drupal information about this new theme - like theme name, blurb, version number and what theme engine it depends on. I simply created a new text file in my Blackfairy directory called blackfairy.info, and inserted this stuff:
name = Blackfairy
description = A sexy little theme with a huge orange block and a large orchid, originally hacked from a free HTML template.
core = 6.x
engine = phptemplate
Now my new theme will register on the admin/build/themes page and I could enable and configure this theme. When I enable Blackfairy I get the HTML of the theme displayed on my Drupal pages, stripped of its CSS formatting, like this:
It looks like garbage because Drupal is looking inside the theme directory for files of certain names, and Blackfairy doesn't have those yet. We have to change Blackfairy's original index.html file into a file called page.tpl.php. Similarly, I changed Blackfairy's default.css file to style.css so it matches the naming convention Drupal likes for CCS files. We're starting to look more like a Drupal theme directory at this point:
From this point forward, it's a copy/paste marathon to replace the HTML elements of Blackfairy with the Drupal theme elements found in Garland. I simply compare the two page.tpl.php files side by side. There are about five simple copy/paste exercises that I'll do that will make my new theme come to life.
First, we can tell from the current state of our Drupal site that this Blackfairy theme can't find its CSS file. That makes sense because we changed the name of the CSS file in an earlier step. Lets solve this by stealing the contents of the head tags from Garland and inserting it into the matching tags in Blackfairy. This carries over the $head, $styles, $scripts into my new theme, reestablishing the calls for the CSS files (among other things).
Again, Garland is on the right, Blackfairy on the left. I have highlighted the swap I am about to do:
Second, I want to replace Blackfairy's title and slogan with corresponding values from our Drupal site. In this case, I am stealing the code inside Garland's header tags and inserting it into the matching tags in Blackfairy, and after doing this we can see that resulting page is showing us or first "Drupal-ish" theme elements - the title of our site rather than Blackfairy's hard coded title. Here are the changes:
Here is the result:
Third, look inside the Blackfairy template and find the div called content and its enclosed divs called colOne and colTwo. Blackfairy is treating these two columns the way Drupal might present a main content area and a sidebar. Let's replace the contents of Blackfairy's colTwo with Garland's code for rendering the main content area called center. Look at the example replacement here:
Here is the result:
The result on our front page is a display of the content from our Drupal site in place of the dummy text provided in Blackfairy. Note how all the links and dates and tags and everything else are being rendered properly.
Forth, let's swap the contents of Blackfairy's colOne with Garland's code that generates one of Drupal's sidebars. Look at the example replacement here:
And the result:
The last theme template change I'll make is to carry over all the xx.tpl.php template files from Garland so that Blackfairy's theme can take more granular control over nodes, comments, blocks, etc. I'll also create a new, blank template.php file so that any future themers using Blackfairy can write in their custom theme functions there. I can just copy all these files from Garland directly:
The last steps I don't need to show you explicitly since the rest is CSS work to tweak your styles to match more closely those of the original Blackfairy. These were pretty lightweight changes just to show you how close I can get the styling in just a few minutes. I can also get into themeing the nodes, blocks or comments to help get closer to this design.
When it is all tweaked out, the result is a Drupal 6 theme built from a plain HTML/CSS design that could have been made by anyone without specific Drupal skills. The original HTML design has been very fairly replicated in this conversion, and it didn't take a CSS genius to do it. Here is the display of a fully converted Drupal 6 theme:
This Blackfairy theme was originally copyrighted under a Creative Commons license that isn't totally open source and prevents me from contributing this new Drupal 6 theme to Drupal.org, but it makes for an excellent teaching tool. Explore these examples of the original and the converted Blackfairy files to see the details of the changes that I made in this little exercise:
And by the way, for any of my students reading this, the reason why it wasn't coming together in the class was because of a cached blackfairy.info file that wasn't being cleared with the cache since I had been working on this same example the night before the class. There is a helpful description of .info files right here and what to do if you have been editing them and your theme doesn't render as expected.
Hope this helps someone out there. Good luck!