1.1 Installing the AvatarBlocks Module

You should place all modules in the sites/all/modules folder of your Drupal installation. If you have not installed additional modules yet, this folder may not exist. If this is the case, simply create a subfolder in the sites/all folder called modules.

Download the AvatarBlocks module distribution and extract the files. The AvatarBlocks module is distributed in a pkzip or a compressed tar file. Download the appropriate distribution for your platform and extract the contents using a tool such as pkZip, 7-Zip, or Stuffit. Linux users can extract the file using the tar command.

FTP/Copy/SCP the avatar_blocks folder to the sites/all/modules folder of your Drupal installation.

Enable the module by logging into the administrator account of your Drupal installation, pointing your browser to /yoursite/admin/build/modules, and checking the 'Enabled' checkbox next to the Avatar Blocks module. Click the Save Configuration button to save the changes.

For detailed instructions on installing and configuring Drupal modules, check out the Drupal.org handbook page on module installation.

1.2 Installing Additional Modules

In order to get the most from the AvatarBlocks module, you'll probably want to install and configure some additional modules. Most importantly, you'll want to install the ImageCache module. Complete instructions for installing and configuring the ImageCache module are available here. Once you've got Imagecache installed correctly, you can use Imagecache Presets with the AvatarBlocks module.

If you want to use the My Buddylist block, you'll need to install and configure the Buddylist module. Instructions for using the Buddylist module are available here.

Additionally, AvatarBlocks will benefit from the use of the UniqueAvatar module. Read more about the problems that UniqueAvatar solves here.

You'll need to customize the configuration of each module to match the behavior you wish to provide for your site. Most importantly, you'll need to configure the access control settings at yoursite/admin/user/access. Here, you can specify who is able to view user profiles, buddylists, imagecache presets, etc.

2.1 Configuring The Who's Online Block

The following options are available for the Who's Online block:

• Block Title - You can override the default block title (which is Who's Online) by specifying an alternate title here. If you don't want a block title, specify <none> in this field.
• User Activity - This option allows you to specify how users are determined to be online.
• User List Length - This option allows you to specify how many avatars will appear in the Who's Online block.
• Imagecache Preset - If you have the ImageCache module installed, this field will allow you to select an Imagecache Preset to apply to the avatars in this block. Read more about using Imagecache on this page.
• Include text summary - If this option is enabled, a text summary of the number of online and guest users will be displayed below the avatars.
• Display Users without avatars - If you enable this option, and if you have configured a default avatar for your site, then users without avatars will be displayed in the Who's Online block using the default avatar. If this option is disabled, users without avatars will not be displayed in the Who's Online block.

2.2 Configuring the Who's New Block

The following options are available for the Who's New block:

• Block Title - You can override the default block title (which is Who's New) by specifying an alternate title here. If you don't want a block title, specify <none> in this field.
• Number of users to display - This option allows you to specify how many avatars will appear in the Who's New block.
• Imagecache Preset - If you have the ImageCache module installed, this field will allow you to select an Imagecache Preset to apply to the avatars in this block. Read more about using Imagecache on this page.
• Display Users without avatars - If you enable this option, and if you have configured a default avatar for your site, then users without avatars will be displayed in the Who's New block using the default avatar. If this option is disabled, users without avatars will not be displayed in the Who's New block.

2.3 Configuring the User Role Block

Drupal uses roles to categorize users for purposes of administration rights, content access, etc. For example, you could create a role called Moderator, configure this moderator role to have limited administration rights over forum posts, and then assign that role to trusted parties.

The User Role Block will display the avatars of users from a single selected role. With this block, you can display your sites Moderators, Editors, Contributors, Administrators, etc. We're using this block here on the demo site's forum pages to display the forum moderators.

The following options are available for the User Role block:

• Block Title - You can override the default block title (which is User Role) by specifying an alternate title here. If you don't want a block title, specify <none> in this field.
• Number of users to display - This option allows you to specify how many avatars will appear in the User Role block.
• Role - Users who are granted the selected role will be displayed in the User Role block.
• Imagecache Preset - If you have the ImageCache module installed, this field will allow you to select an Imagecache Preset to apply to the avatars in this block. Read more about using Imagecache on this page.
• Display Users without avatars - If you enable this option, and if you have configured a default avatar for your site, then users without avatars will be displayed in the User Role block using the default avatar. If this option is disabled, users without avatars will not be displayed in the User Role block.

2.4 Configuring the My Buddylist Block

The following options are available for the My Buddylist block:

• Block Title - You can override the default block title (which is My Buddylist) by specifying an alternate title here. If you don't want a block title, specify <none> in this field.
• Number of users to display - This option allows you to specify how many avatars will appear in the My Buddylist block.
• Imagecache Preset - If you have the ImageCache module installed, this field will allow you to select an Imagecache Preset to apply to the avatars in this block. Read more about using Imagecache on this page.
• Display Users without avatars - If you enable this option, and if you have configured a default avatar for your site, then users without avatars will be displayed in the My Buddylist block using the default avatar. If this option is disabled, users without avatars will not be displayed in the My Buddylist block.

2.5 Using ImageCache Presets with AvatarBlocks

By default, the AvatarBlocks module will display user pictures as they exist in your Drupal installation. The module itself does not attempt to resize or crop the image in any way. Unless you have a very consistently-sized collection of avatars, this can result in a block with user pictures of all shapes and sizes. Maybe that's the look you're going for. But more likely, you'll want the blocks to display pictures that are of the same size and shape.

Using the ImageCache module, you can transform the user pictures before they are displayed in the blocks. You could, for example, crop the pictures to a square shape and scale the pictures to a fixed size. This will result in consistently-sized pictures that line up nicely in the block display.

To use the ImageCache module with AvatarBlocks, you must create an ImageCache Preset. A preset is a sequence of actions to perform on an image. Once you have created a preset, you can choose to apply that preset to the avatars displayed by each of the blocks.

Once you've created a preset that will transform the avatars as you wish, you can select that preset on each of the block configuration pages. Each block can use a different Imagecache preset, allowing you to have different transformations of the same image in different blocks.

For the blocks on this demo site, we created an ImageCache preset with the following actions:

• Scale - width: 50, height: 50, fit: Outside dimensions
• Crop - width: 50, height: 50, xoffset: center, yoffset: top

2.6 Using the Unique Avatar Module with AvatarBlocks

Browser cacheing issues can be infuriating when working with Imagecache and user pictures. The best way around these problems is to install the Unique Avatar Module.

Here's the symptom... you're tired of your old avatar. So you go to your profile page, upload a new one, and save your profile. But the site still shows the old picture. And so do the avatar blocks.

The problem is that Drupal uses the same filename for your new avatar as it used for the old one. So your browser pulls the old image out of cache without downloading the new one. You'll have to clear your browser cache to see the new version. And so will your users.

As described on the Unique Avatar project page:

Unique Avatar circumvents unwanted browser caching of user pictures by creating a unique filename each time the image is uploaded. When a user picture is uploaded, a 32-character unique id is appended to the the filename.

Unique Avatar also flushes any ImageCache caches of the existing user picture.

3.1 Themeing Using CSS

The AvatarBlocks module wraps each individual user's avatar display with a div that has a class name of userpicture. You can use the following selectors to target CSS directives:

• .userpicture
• .userpicture a
• .userpicture a img

AvatarBlocks provides a very simple default style sheet that contains the following CSS code:

.userpicture {
  float: left;
  line-height: 0;
}

.userpicture a {
  display:block;
  border: 2px solid #fff;
}

.userpicture a:hover {
  border: 2px solid #bbb;
}

.userpicture img {
  margin: 0;
}

You can override or amend these styles in your theme style sheet to change the appearance of the default AvatarBlocks display.

The blocks on this demo site use the default AvatarBlocks styling. Each avatar is floated left, and the number of avatars in each row is dictated by the size of the images and the width of the region.

3.2 Themeing Using Theme Overrides

Geek Alert! - The theme overrides described below require some editing of your theme's PHP files. It's really not that hard. But it needs to be done right or you can break your site, so it's not for everybody. Always work on a test site, and always make a backup first.

function whitejazz_avatar_blocks_avatar($avatar_link, $name, $userlink) {
  if ($avatar_link) {
    $output =  '<div class="avatar-user-block">';
    $output .= '<div class="userpicture">';
    $output .= $avatar_link;
    $output .= '</div>';
    $output .= '<div class="username">';
    $output .= $userlink;
    $output .= '</div>';
    $output .= '<div style="clear:both"></div>';
    $output .= '</div>';
  }
  return $output;
}

.avatar-user-block {
  border: 1px solid #000;
  background: #ddd;
  margin: 2px 0;
  padding: 3px;
}

.username {
  float: left;
  margin-left: 10px;
}