django-avatar

Django-avatar is a reusable application for handling user avatars. It has the ability to default to Gravatar if no avatar is found for a certain user. Django-avatar automatically generates thumbnails and stores them to your default file storage backend for retrieval later.

Installation

If you have pip installed, you can simply run the following command to install django-avatar:

pip install django-avatar

Included with this application is a file named setup.py. It’s possible to use this file to install this application to your system, by invoking the following command:

python setup.py install

Once that’s done, you should be able to begin using django-avatar at will.

Usage

To integrate django-avatar with your site, there are relatively few things that are required. A minimal integration can work like this:

  1. List this application in the INSTALLED_APPS portion of your settings file. Your settings file will look something like:

    INSTALLED_APPS = (
        # ...
        'avatar',
    )
    
  2. Update your database:

    python manage.py syncdb
    
  3. Add the avatar urls to the end of your root urlconf. Your urlconf will look something like:

    urlpatterns = patterns('',
        # ...
        (r'^avatar/', include('avatar.urls')),
    )
    
  4. Somewhere in your template navigation scheme, link to the change avatar page:

    <a href="{% url 'avatar_change' %}">Change your avatar</a>
    
  5. Wherever you want to display an avatar for a user, first load the avatar template tags:

    {% load avatar_tags %}
    

    Then, use the avatar tag to display an avatar of a default size:

    {% avatar user %}
    

    Or specify a size (in pixels) explicitly:

    {% avatar user 65 %}
    

Template tags and filter

To begin using these template tags, you must first load the tags into the template rendering system:

{% load avatar_tags %}
{% avatar_url user [size in pixels] %}
Renders the URL of the avatar for the given user. User can be either a django.contrib.auth.models.User object instance or a username.
{% avatar user [size in pixels] %}
Renders an HTML img tag for the given user for the specified size. User can be either a django.contrib.auth.models.User object instance or a username.
{% render_avatar avatar [size in pixels] %}
Given an actual avatar.models.Avatar object instance, renders an HTML img tag to represent that avatar at the requested size.
{{ request.user|has_avatar }}
Given a user object returns a boolean if the user has an avatar.

Global Settings

There are a number of settings available to easily customize the avatars that appear on the site. Listed below are those settings:

AVATAR_AUTO_GENERATE_SIZES
An iterable of integers representing the sizes of avatars to generate on upload. This can save rendering time later on if you pre-generate the resized versions. Defaults to (80,)
AVATAR_RESIZE_METHOD
The method to use when resizing images, based on the options available in PIL. Defaults to Image.ANTIALIAS.
AVATAR_STORAGE_DIR
The directory under MEDIA_ROOT to store the images. If using a non-filesystem storage device, this will simply be appended to the beginning of the file name.
AVATAR_GRAVATAR_BACKUP
A boolean determining whether to default to the Gravatar service if no Avatar instance is found in the system for the given user. Defaults to True.
AVATAR_GRAVATAR_DEFAULT
A string determining the style of the default Gravatar. Available options listed in the (Gravatar documentation)[https://en.gravatar.com/site/implement/images/#default-image]. Ex. ‘retro’. Defaults to None.
AVATAR_DEFAULT_URL
The default URL to default to if AVATAR_GRAVATAR_BACKUP is set to False and there is no Avatar instance found in the system for the given user.
AVATAR_MAX_SIZE
File size limit for avatar upload. Default is 1024 * 1024 (1mb).

Management Commands

This application does include one management command: rebuild_avatars. It takes no arguments and, when run, re-renders all of the thumbnails for all of the avatars for the pixel sizes specified in the AVATAR_AUTO_GENERATE_SIZES setting.