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.
To integrate django-avatar
with your site, there are relatively few things that are required. A minimal integration can work like this:
List this application in the
INSTALLED_APPS
portion of your settings file. Your settings file will look something like:INSTALLED_APPS = ( # ... 'avatar', )
Add the pagination urls to the end of your root urlconf. Your urlconf will look something like:
urlpatterns = patterns('', # ... (r'^avatar/', include('avatar.urls')), )
Somewhere in your template navigation scheme, link to the change avatar page:
<a href="{% url 'avatar_change' %}">Change your avatar</a>
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 %}
- Optionally customize
avatar/change.html
andavatar/confirm_delete.html
to conform to your site's look and feel.
There are only two views for this application: one for changing a user's avatar, and another for deleting a user's avatar.
The actual view function is located at avatar.views.change
, and this can be referenced by the url name avatar_change
. It takes two keyword arguments: extra_context
and next_override
. If extra_context
is provided, that context will be placed into the template's context.
If next_override
is provided, the user will be redirected to the specified URL after form submission. Otherwise the user will be redirected to the URL specified in the next
parameter in request.POST
. If request.POST
has no next
parameter, request.GET
will be searched. If request.GET
has no next
parameter, the HTTP_REFERER
header will be inspected. If that header does not exist, the user will be redirected back to the current URL.
The actual view function is located at avatar.views.delete
, and this can be referenced by the url name avatar_delete
. It takes the same two keyword arguments as avatar.views.change
and follows the same redirection rules as well.
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.get_user_model()
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 adjango.contrib.auth.get_user_model()
object instance or a username.{% render_avatar avatar [size in pixels] %}
Given an actual
avatar.models.Avatar
object instance, renders an HTMLimg
tag to represent that avatar at the requested size.
There are a number of settings available to easily customize the avatars that appear on the site. Listed below are those settings:
- AVATAR_GRAVATAR_BASE_URL
The base URL where to get avatars at gravatar.com. Defaults to
http://www.gravatar.com/avatar/
.- AUTO_GENERATE_AVATAR_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_DEFAULT_URL
The default URL to default to if
AVATAR_GRAVATAR_BACKUP
is set to False and there is noAvatar
instance found in the system for the given user.
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 AUTO_GENERATE_AVATAR_SIZES
setting.