mirror of
https://github.com/jazzband/django-avatar.git
synced 2026-03-16 22:20:30 +00:00
191 lines
6.8 KiB
Text
191 lines
6.8 KiB
Text
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.
|
|
|
|
.. _Gravatar: http://gravatar.com
|
|
|
|
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. Migrate your database::
|
|
|
|
python manage.py migrate
|
|
|
|
3. Add the avatar urls to the end of your root urlconf. Your urlconf
|
|
will look something like::
|
|
|
|
urlpatterns = [
|
|
# ...
|
|
(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 %}
|
|
|
|
Example for customize the attribute of the HTML ``img`` tag::
|
|
|
|
{% avatar user 65 class="img-circle img-responsive" id="user_avatar" %}
|
|
|
|
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] **kwargs %}``
|
|
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. The (key, value) pairs in kwargs will be added to ``img`` tag
|
|
as its attributes.
|
|
|
|
``{% 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_CACHE_ENABLED
|
|
Set to ``False`` if you completely disable avatar caching. Defaults to ``True``.
|
|
|
|
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_EXPOSE_USERNAMES
|
|
Puts the User's username field in the URL path when ``True``. Set to ``False`` to
|
|
use the User's primary key instead, preventing their email from being searchable on the web.
|
|
Defaults to ``True``.
|
|
|
|
AVATAR_FACEBOOK_BACKUP
|
|
A bool determining whether to default to Facebook Graph service if no ``Avatar`` instance
|
|
is found in the system for the given user. ``AVATAR_GRAVATAR_BACKUP`` takes precedence, so
|
|
if you set this to ``True`` then you must set ``AVATAR_GRAVATAR_BACKUP`` to False. You
|
|
must also set the ``AVATAR_FACEBOOK_GET_ID`` setting.
|
|
Defaults to ``False``.
|
|
|
|
AVATAR_FACEBOOK_GET_ID
|
|
A callable or string path to a callable that will return the user's Facebook ID. The
|
|
callable should take a ``User`` object and return a string. If you want to use this
|
|
then make sure ``AVATAR_FACEBOOK_BACKUP`` is ``True`` and ``AVATAR_GRAVATAR_BACKUP`` is
|
|
``False``. Defaults to ``None``.
|
|
|
|
AVATAR_GRAVATAR_BACKUP
|
|
A bool 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 default Gravatar. Can be a URL to a custom image or a
|
|
style of Gravatar. Ex. `retro`. All Available options listed in the
|
|
`Gravatar documentation <https://en.gravatar.com/site/implement/images/#default-image>`_.
|
|
Defaults to ``None``.
|
|
|
|
AVATAR_GRAVATAR_FORCEDEFAULT
|
|
A bool indicating whether or not to always use the default Gravitar. More details can be found
|
|
in the `Gravatar documentation <https://en.gravatar.com/site/implement/images/#force-default>`_.
|
|
Defaults to ``False``.
|
|
|
|
AVATAR_GRAVATAR_FIELD
|
|
The name of the user's field containing the gravatar email. For example, if you set
|
|
this to ``gravatar`` then django-avatar will get the user's gravatar in ``user.gravatar``.
|
|
Defaults to ``email``.
|
|
|
|
AVATAR_MAX_SIZE
|
|
File size limit for avatar upload. Default is ``1024 * 1024`` (1 MB).
|
|
|
|
AVATAR_PATH_HANDLER
|
|
Path to a method for avatar file path handling. Default is
|
|
``avatar.models.avatar_path_handler``.
|
|
|
|
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. Defaults to ``avatars``.
|
|
|
|
AVATAR_ADD_TEMPLATE
|
|
Path to the Django template to use for adding a new avatar. Defaults to ``avatar/add.html``.
|
|
|
|
AVATAR_CHANGE_TEMPLATE
|
|
Path to the Django template to use for changing a user's avatar. Defaults to ``avatar/change.html``.
|
|
|
|
AVATAR_DELETE_TEMPLATE
|
|
Path to the Django template to use for confirming a delete of a user's avatar. Defaults to ``avatar/avatar/confirm_delete.html``.
|
|
|
|
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.
|
|
|
|
|
|
.. _pip: http://www.pip-installer.org/
|