disobey.com

The Drupal Achievements module offers the ability to create achievements and badges similar to systems seen on Xbox 360, Playstation 3, Foursquare, Gowalla, GetGlue, and more. For a Drupal site, this could mean commenting a certain number of times, starting a forum topic, visiting the site every day of the week, or anything else that can be tracked and coded. The recently released 7.x-1.4 update focuses on changes that make theming easier.

In my first post about #theme_wrappers, we fixed up bad HTML in #prefix and #suffix to give themers an easier time. This post, about render arrays, is no different. In fact, most of the tweaks in Achievements 7.x-1.4 are not very obvious, or even useful, to module developers. It's only when you sit down with a themer who wants to change the entire look and feel that you realize your carefully-coded "looks good in Garland!" output is not as useful as you think.

Why render arrays are better

You've probably read about render arrays in the Drupal Developer's Handbook already, but the documentation doesn't really give a developer a decent reason why they should use them. It also doesn't talk about $content or splitting your variables into "data" and "presentation". I'll cover both below.

First, let's look at the wrong approach:

    $build['image'] = theme('image', array('path' => array('misc/druplicon.png')));

If this was passed to a theme file, the themer would simply print $image; and be done with it. The themer could even link the image if they wanted, but they wouldn't be able to add any classes or attributes to the image, since calling theme() directly always returns rendered HTML. Here's what the above looks like as a render array:

    $build['image'] = array(
      '#theme' => 'image',
      '#path' => 'misc/druplicon.png',
    );

To get this to display in the theme, we'd use print render($image); instead. In this case, the theme is telling Drupal to render the HTML, not your module. Why is this important? Ignoring the nebulous "I CAN'T ADD CSS CLASSES, SNIFF!" themer lament, consider the following small tweak to our original bad example:

    $image = theme('image', array('path' => array('misc/druplicon.png')));
    $build['image'] = l($image, 'node', array('html' => TRUE));

Here, we've simply added a link to our dummy image and the themer gets the fully rendered HTML to print out. Everything is toasty... unless the client or theme doesn't want or need the image to be linked. The themer now has no choice: they either have to use a regular expression to strip out the unwanted link or they have to recreate the $image variable in his own, well, image. Not only is that fragile (it's essentially copying module code to the theme and that code might change in a future version), but it also mixes too much logic with too little presentation. If the image's path isn't available to the theme as its own variable (it isn't, in the above example), the themer will still have to parse your rendered HTML to find the image's path first. Yuck.

Let's convert the above to a render array:

    $build['image'] = array(
      '#theme' => 'image_formatter',
      '#item' => array(
        'uri' => 'misc/druplicon.png',
      ),
      '#path' => array(
        'path' => 'node',
        'options' => array('html' => TRUE),
      ),
    );

Now, if the themer wants to remove the link, they can listen in a theme override, a preprocess, or even the dreaded hook_page_alter() and simply unset($variables['image']['#path'])'. No more link, without duplicating any upstream code or recreating things themselves. This is a real-life example, by the way - I just finished an optional submodule of Achievements which removes all links to the default leaderboards. I couldn't have easily done that if I used either of the link approaches below:

    $build['achievement_title'] = l($title, 'path/to/achievement');
    $build['achievement_title']['#markup'] = l($title, 'path/to/achievement');

But with the following render array:

    $build['achievement_title'] = array(
      '#type' => 'link',
      '#title' => $title,
      '#href' => 'path/to/achievemnt',
    );

I can make those links linkless:

  unset($variables['achievement_title']['#type']);
  $variables['achievement_title']['#markup'] = $variables['achievement_title']['#title'];

Data, presentation, and $content['a'] not $a

This doesn't mean that every single variable you pass to the theme should be a render array: there's clearly a difference between variables that represent data (an image path, the $node or $user object, a Unix timestamp, etc.) and variables that are meant for presentation (the linked image, the node's filtered teaser, a human-readable date, etc.).

There's a move afoot to more clearly indicate these two types by using a $content variable as a container for all the supplied render arrays. Drupal core does this in some places (node.tpl.php, for one), but not all, and it's slowly becoming a preferred practice in the theming world. Another benefit is the ability to use print render($content);, which says "render everything I haven't already rendered", allowing themes to display things that they, or the parent module, might not know about (new data added by a third party module in a preprocess, etc.). I've yet to implement this in Achievements, but I'll likely get there for the next release.

The Achievements module offers the ability to create achievements and badges similar to systems seen on Xbox 360, Playstation 3, Foursquare, Gowalla, GetGlue, and more. For a Drupal site, this could mean commenting a certain number of times, starting a forum topic, visiting the site every day of the week, or anything else that can be tracked and coded.

Here's what's new in version 7.x-1.3, released today.

Relative leaderboards and latest achievements

The biggest changes in 7.x-1.3 happened to the leaderboards. You can now provide an (optional) "relative leaderboard" which will show a logged-in user their current rank as well as (optionally) a number of ranks before and after their position. For folks who like achievements or mapping their rise to greatness, this will give them a little something more to strive for, a continual heartbeat of their movement through the site-wide rankings. It can also encourage rivalries as users flip-flop back and forth in their point gains and positions. Some users won't give a crap at all, certainly, but for those that do, relative leaderboards can increase a site's stickiness.

Another addition to the leaderboard is "latest achievement" which is exactly as it sounds: it'll show the latest unlock a user has earned. This is important because it increases discoverability of your site's achievements. In previous versions of the module, the only mention of individual achievements was located on a tab in the user's profile -- not exactly the easiest place to find. By including recent achievements on the leaderboard, we're increasing awareness of what you're offering, as well as providing subtle and potential todos for your users and curious visitors.

Hooks for developers

Besides the required hook_achievements_info(), I didn't add any other achievement hooks in the earlier releases because I didn't trust I had a firm grasp of how Achievements module would "end up" based upon my initial roadmap. With said roadmap nearly complete, the latest release of Achievements now includes some additional hooks for more integration. As is best practice, I'm starting off "small and obvious", but will add more as needs arise. hook_achievements_info_alter(), hook_achievements_unlocked(), and hook_achievements_locked() all do what they sound like and are further documented in achievements.api.php.

Small footprint

At its heart, Achievements is a monitoring and statistical module: it listens for events, logs statistics, and does analysis on incoming data. When you have hundreds of achievements, all this intervention could slow your site down. Thankfully, the module has been designed under the oppressive gaze of better performance experts than I and has Examiner.com, one of the largest Drupal 7 sites, as an in-progress client. The new release of Achievements has yet another performance improvement that ensures heavy traffic sustainability, and the new features above cost just one additional database query (per page, but only if you're using the block with relative leaderboards enabled). Future releases of Achievements will continue this dedication to a svelte codebase.

Take a look, bub

You can read about the full feature-set at the Achievements module project page which also includes screenshots of the default interface. Don't hesitate to contact me or create an issue with your pie-in-the-sky feature requests and questions.

Achievements 7.x-1.1 has been released (with screenshots for installer trepidation):

• Achievements can now be categorized into groups.
  • Grouped achievements will be displayed within jQuery UI tabs.
  • If groups exist, ungrouped achievements "upgrade" automatically.
  • See achievements.api.php for more on how to define achievement groups.
• Achievements can now have images.
  • Three possible display states: locked, unlocked, and hidden.
  • Admins may set the default images at admin/config/people/achievements.
  • An 'images' array has been added to hook_achievements_info() definitions.
  • Per-achievement images can override the default on a per-state basis.
  • CSS tweaks were made for a more flexible achievement display.
  • Default images have been provided for each of the three states.
• Administrators can now manually give and take achievements from users.
  • It's problematic on progression-based achievements and internal statistics.
  • hook_achievements_info() gets 'storage' to define where statistics are kept.
  • If 'storage' is not specified, assume it exists under the achievement ID.
  • See admin/config/people/achievements for the disclaimer text on usage.
  • See achievements.api.php for more on 'storage' and a revised HOWTO.
• A new permission, "Earn achievements", has been added.
  • It is REQUIRED and NECESSARY for all roles that can unlock achievements.
  • Core functions check for it so you shouldn't need it in your own code.
  • If you think you need to check, use achievements_user_is_achiever().
  • Removing this permission from a role does NOT delete data or ranks.
  • It does stop, however, the collection of new data, points, or unlocks.
• achievements/leaderboard/NONEXISTENT now returns a 404.
• Locked achievements are now displayed on a user's achievements tab.
• No more warnings when viewing a user with no achievement unlocks.
• 'id' is no longer duplicated in hook_achievements_info() definitions.
• achievements.tpl.php has had its PHP moved to template_preprocess_hook().
  • New variables have been added to streamline the display code.

Notable links enjoyed today:

• Gargantua and Pantagruel
  Delicious tags: wikipedia fiction books literature
  "The Life of Gargantua and of Pantagruel (in French, La vie de Gargantua et de Pantagruel) is a connected series of five novels written in the 16th century by François Rabelais. It is the story of two giants, a father (Gargantua) and his son (Pantagruel) and their adventures, written in an amusing, extravagant, satirical vein. The text features much crudity, scatological humor, and violence. Lists of explicit or vulgar insults fill several chapters. The censors of the Sorbonne stigmatized it as obscene, and in a social climate of increasing religious oppression, it was dealt with suspicion, and contemporaries avoided mentioning it. According to Rabelais, the philosophy of his giant Pantagruel, "Pantagruelism", is rooted in "a certain gaiety of mind pickled in the scorn of fortuitous things" (French: "une certaine gaîté d'esprit confite dans le mépris des choses fortuites")."
• Ant Death Spiral
  Delicious tags: biology science nature death ants
  "This is one of my favorite things about ants -- the ant death spiral. Actually, it's a circular mill, first described in army ants by Schneirla (1944). A circle of army ants, each one following the ant in front, becomes locked into a circular mill. They will continue to circle each other until they all die. How crazy is that? Sometimes they escape, though. Beebe (1921) described a circular mill he witnessed in Guyana. It measured 1200 feet in circumference and had a 2.5 hour circuit time per ant. The mill persisted for two days, "with ever increasing numbers of dead bodies littering the route as exhaustion took its toll, but eventually a few workers straggled from the trail thus breaking the cycle, and the raid marched off into the forest."
• List of games with concealed rules
  Delicious tags: wikipedia games
  "These are games where the rules are intentionally concealed from new players, either because their discovery is part of the game itself, or because the game is a hoax and the rules do not exist. In fiction, the counterpart of the first category are games that supposedly do have a rule set, but that rule set is not disclosed." Includes discovery games, hoax or joke games, and games in works of fiction.
• 7 Scientific Reasons a Zombie Outbreak Would Fail (Quickly)
  Delicious tags: zombies culture science
  "Let's pretend for a moment that zombies are real (as if half of you weren't already daydreaming about that very thing). Have you noticed how most zombie movies take place only after the apocalypse is in full-swing? By the time we join our survivors, the military and government are already wiped out, and none of the streets are safe. There's a reason the movie starts there, and not earlier. It's because the early part, where we go from one zombie to millions, doesn't make any sense. If you let the creeping buzzkill of logic into the zombie party, you realize the zombies would all be re-dead long before you even got a chance to fire up that chainsaw motorcycle you've been working on. Why?"
• Mautam
  Delicious tags: nature wikipedia india rats
  Mautam (Mizo, ’bamboo death’; also spelt mautaam) is a cyclic ecological phenomenon that occurs every 48 years in the northeastern Indian states of Mizoram and Manipur, which are thirty percent covered by wild bamboo forests, as well as Chin State in Burma, particularly Hakha, Thantlang, Falam, Paletwa and Matupi Townships, creating a widespread famine in those areas … This event is followed invariably by a plague of Black Rats in what is called a rat flood. This occurs as the rats multiply in response to the temporary windfall of seeds and leave the forests to forage on stored grain when the bamboo seeds are exhausted, which in turn causes devastating famine."

My Drupal IRC bot.module received a new release today, bringing it to 7.x-1.3:

• #273116: bot_auth.module added (thanks snufkin, RobLoach).
• scripts/bot_start.php: the new location of bot_start.php.
• scripts/bot_check.sh added: restarts the bot if it's not running.
• #524218: Drush integration added (thanks jonhattan, q0rban, sirkitree).
• bot_log.channel is now a text column (required for large installations).
• All incoming messages are forced to UTF-8 (thanks bellHead, nick_vh).
• #918966: New Net_SmartIRC wrapper; hook_irc_access added (thanks Bevan).
• All forgotten strlens()s have been changed to drupal_strlen().
• All forgotten substr()s have been changed to drupal_substr().
• First release for Drupal 7.x; based on 6.x-1.2 release.