HOWTO: Liberating the User Picture Upload Interface

One of the things that makes Drupal such a powerful platform for building community websites is its robust and scalable user system. Its got everything you need to start popin' and lockin' built right into the core framework: unlimited user roles, granular permissions, easily extensible profiles and more.

Avatar upload screen

Still, as hookable and mashup-friendly as it is, there are a number of things that Drupal core has a stubborn hold on. One of these is the user-picture (aka avatar) upload interface. The picture system is very well implemented -- it will resize uploaded images, display them in posts and comments automagically, etc -- but the user-interface for you to actually put up your picture is locked onto the catch-all "account settings" part of the user/edit interface, which can get pretty cluttered if you've got a lot of modules throwing their settings in there.

In future (5.0+) revisions, I'm sure that the already-awesome profile system will grow and allow site admins to easily reposition all user-account elements, but yesterday I had a need to move that user-picture upload field into it's own page, and so I did. Less than 50 lines of code, too. Here's how:

Step 1: Create a new section in the user/edit interface
For my application, I wanted to put the user-picture upload off on it's own section of the user/edit interface, on it's own "category" in Drupal's user/edit lingo. This would separate it from the "account settings" clutter, and also give me a place to expand if I want to add other user-picture features down the line.

The first order of business is making a new category. For this, I used hook_user and returned some data when the $op was looking for "categories":

 

function avatar_user($op, &$edit, &$account, $category = NULL) {
  if (
$op == 'categories') {
   
$categories = array(array('name' => 'avatar', 'title' => t('picture'), 'weight' => 10));
    return
$categories;
  }
}

?>

 

The data structure you return is a little complex there. You return an array of associative arrays, with each associative array defining a new category. You set an internal name, a human readable title, a weight to help set the order when there are multiple categories. Since I only want one new category, I have an array of one arrays, as you can see.

This sets me up to now tell drupal to display a form when the user clicks on this category.

Step 2: Define your form
Within the same instance of hook_user, I added the following code:

 

if ($op == 'form' && $category == 'avatar') {
   
$form = array();
   
$form['avatar'] = array(
     
'#type' => 'fieldset',
    );
   
$form['avatar']['preview'] = array(
     
'#type' => 'markup',
     
'#value' => theme('user_picture', $account),
     
'#prefix' => '

'.t('Your current picture').'

',
    );
   
$form['avatar']['picture_upload'] = array(
     
'#type' => 'file',
     
'#title' => t('Upload a new picture'),
     
'#size' => 20,
    );
    return
$form;
  }

?>

 

When the $op is "form," Drupal listens for a Form API-style array to render on that category page of the user/edit interface. You can also use this to extend the form on other category pages, including the default "account settings" page.

What I've defined here tells the "avatar" category to display the current user-picture via a "markup" form element, and then defines a file field for uploading a new one. I've borrowed heavily from the core user.module and kept it simple, but this could someday expand to include other picture-related options, such as multiple images, a caption, etc.

With this in place, can now move on to handling the submitted form values.

Step 3: Handling form values
Again, we're utilizing hook_user, this time to deal with a submitted form by means of the "validate" $op value:

 

if ($op == 'validate' && $category == 'avatar') {
    if (
$file = file_check_upload('picture_upload')) {
     
user_validate_picture($file, $edit, $account);
    }
  }

?>

 

This seems too easy to be true, but it isn't. Since I've stuck with the established style for Drupal's default user-picture upload, and I don't want to change how the stored pictures are handled (just where the upload interface lives), I can reuse the function in the core user.module to handle the form values.

If I wanted to handle multiple images or additional data, this would have to be re-written and expanded, but for now we can take advantage of the functionality Drupal already offers to finish up our user/edit category.

Step 4: Hiding the old form elements
One last detail is to get rid of the old user-picture upload interface. It will still work fine, but it would be confusing to users to have this interface in two places. Luckily, there's no need to hack at Drupal core's user.module thanks again to Form API and the form_alter hook:

 

function avatar_form_alter($form_id, &$form) {
  if(
$form_id == 'user_edit' && arg(3) == NULL) {
   
// only fire this if it's user//edit, not any other category
   
unset($form['picture']);
  }
}

?>

 

This clears out the old user-picture upload interface, preventing user confusion.

Guess what? You're done! You can download the complete module code below. Share and enjoy!