On the Inside

If you aren't sure what Drupal is, you're staring at it. If you aren't sure what Tagadelic is, then look to the left of this post at the section that says Browse by category. That is the work of the Tagadelic module for Drupal. It allows you to display a list of "tags" made up of the different categories (taxonomy terms) in a category group (vocabulary). These tags are weighted so that categories with more posts in them show up in a larger, bolder font. Tagadelic made its debut two Drupal versions ago in Drupal 4.6 and has yet to be updated for version 5.0.

How in the world did I get it on my site, then, when I converted to 5.0? That is what I have been asked to tell you, and you may read on to find out if that is your question, too.

First, I downloaded the latest Tagadelic code by going to http://drupal.org/project/tagadelic and clicking on the Download latest release link. (You can also click the View other releases link to make sure that is in fact the latest release. Sometimes the current working code, called CVS, may be more up to date than the official release.) Once I extracted the files, I opened up the code file, tagadelic.module, and had a quick look.

Next, I went back to a page at Drupal.org that's been in my bookmarks for a while now, http://drupal.org/node/64279. This is a page in the Drupal handbook that details the changes from Drupal 4.7 to 5.0 that module developers need to make in their code for compatibility. For various reasons, Dries decided long ago to not support backwards compatibility. I think it's a good move, and with pages like these, it's easy for module developers or, as in my case, third party developers to take and update a module for the latest Drupal version. This can be quite a task in larger projects like e-commerce, but it's no big deal for Tagadelic.

So, what items on the list apply to Tagadelic? After browsing the code, I could see that I would need to make changes to account for items 1, 8, 12, and 23/24. If you've got the November 2, 2006 CVS version here are the line numbers for the changes:

Line 23 and 157:

theme_add_style($stylesheet, 'all');

changed to

drupal_add_css($stylesheet, 'module', 'all');

This accounts for the new way to link in stylesheets. (Item 12 on the changes list.)

Line 52:

  }

changed to

    $items[] = array(
      'title' => t('Tagadelic settings'),
      'path' => "admin/settings/tagadelic",
      'callback' => 'drupal_get_form',
      'callback arguments' => 'tagadelic_settings',
      'access' => user_access('administer taxonomy'),
      'type' => MENU_NORMAL_ITEM);
  }

Because Drupal no longer uses hook_settings, we have to define our own settings pages for modules. (Item 8 on the changes list.) This adds a menu item to Tagadelic's hook_menu function that points to the tagadelic settings page. This also uses the new way to serve up forms. Forms are displayed by using drupal_get_form() which expects to receive a form_id as its argument. (Item 23/24 on the changes list.) So this menu item displays the form defined in the function tagadelic_settings. (The form_id in Drupal 5.0 is generally the name of the function you call that builds the $form array. Item 25 on the changes list discusses an alternate way to handle form_ids, but that doesn't apply to Tagadelic.)

Line 93:

return $form;

changed to

return system_settings_form($form);

If you look back at item 8 on the changes list, you'll see mention of the system_settings_form() helper function. This adds the submit buttons to the form that we'd need for us, and it allows Drupal to handle the saving of the variables. It's very handy here!

New file, tagadelic.info:

name = Tagadelic
description = Add tagadelic browsing of taxonomy to your site.

As per item 1 on the changes list, modules now need a .info file to be recognized by Drupal. This is a wonderful new feature to Drupal that allows for module dependencies and packages while also solving a horrible problem in earlier versions referred to as the "white screen of death" on the administer >> modules page. This file needs to be created and uploaded in the tagadelic directory when you upload that to your modules directory.

So, there you have it. That's the process I used to convert the Tagadelic module. It's quite simply a matter of reading through the update list and changing those spots in the code. It helps to be familiar with the list before diving into the code you're trying to update, because you can spot things as items that need to be changed without having to flip back to the handbook too often. The major hurdle, again, is the change to the forms API. But all the other little changes can add up, too.

Something else worth noting is Drupal 5.0 and up will now use sentence capitalization for menu items, blocks, and page names. This means the first letter is capitalized and the other words are only capitalized like they would be in a sentence. This doesn't include punctuation, though. For example, the blocks on this site right now are Browse by category, Navigation, and Recent blog posts. Menu items, too, are affected, so you see items like My account, Recent posts, and Log out. In previous versions of Drupal, these things defaulted to all lower case and there wasn't an easy way to achieve this type of capitalization. With the change, you should probably adjust the titles of the menu items in the Tagadelic function tagadelic_menu to use this capitalization.

I hope this article was somewhat helpful! Feel free to comment any questions you have. Also, I encourage you to go through the changes yourself to get a feel for the updating process, but I have also attached the version of Tagadelic running on this site for you to download. If there are any problems with it, please let me know.

(Once you have Tagadelic installed, you can adjust its settings from the administration menu. I won't go into all the details, but the module allows you to generate pages or blocks of content using tag clouds. I'm using the predefined block to display terms from my taxonomy vocabulary called "Category," but you'll noticed I changed the name to suit my fancy. You can do this by clicking on the Configure link on the block's row. Cheers!)