.. _usage:

Usage
=====

Django Pydenticon is targeted at developers who wish to integrate an identicon
service in their Django projects. This chapter covers details on how an
identicon image is served, and how to integrate Django Pydenticon with other
applications.

Requesting identicons
---------------------

Identicon images are served through specially formatted URL. Whenever such URL
is submitted to Django Pydenticon application, an identicon image is created on
the fly.

The format of URL is ``/image/USER_DATA`` (relative to prefix URL assigned for
the application), where **USER_DATA** can be either in hashed or raw format. For
example, if Django Pydenticon application is reachable under ``/identicon/``,
identicon images can be requested using the following URLs:

* ``/identicon/image/somedataforhashing`` (raw data)
* ``/identicon/image/55d207ea47247b375dc1f495517f1332`` (pre-hashed data using
  *md5*)

.. warning::
   Keep in mind that if user data is submitted in pre-hashed form, the digest
   used should match with the digest configured for Django Pydenticon
   application. If digest does not match, the user data will be treated as any
   other user data, and it will be hashed once again.

URL instance namespaces
-----------------------

When resolving Django Pydenticon URLs, you should always use the URL names in
conjunction with application instance namespace.

Default application instance namespace is ``django_pydenticon``. Alternative
instance namespace can be specified by passing an (optional) argument to
``django_pydenticons.urls.get_patterns`` function.

For example, if default namespace is in use, the ``image`` URL would be
referenced as ``django_pydenticon:image`` in template tag ``url`` or function
call ``reverse``.

Generating identicon URLs in templates
--------------------------------------

If the data (whether raw or hashed) is available in template's context, an
identicon URL can be easily generated from within the template itself. This can
be achieved via ``url`` tag.

The URL for serving the identicons is named ``image``. It should always be
referenced in conjunction with an application instance namespace. The
application namespace defaults to ``django_pydenticon``, unless custom instance
namespace is passed when including the application URLs via
``django_pydenticon.urls.get_patterns``. In case of default namespace, that
means the URL would be referenced to as ``django_pydenticon:image``.

For example, let's say that it's necessary to show an identicon based on
username next to every comment. Related template snippet could look something
similar to the following::

  <ul>
  {% for comment in comments %}
    <li><img src="{% url 'django_pydenticon:image' comment.user.username %}"/>{{ comment.text }}</li>
  {% endfor %}
  </ul>

Generating identicon URLs programatically
-----------------------------------------

The URLs can be generated programtically, using Python code. Afterwards those
URLs can be either passed into template's rendering context, or used inside of
code for whatever other purposes. This is achieved by using the ``reverse`` URL
resolver (from ``django.core.urlresolvers``).

The URL for serving the identicons is named ``image``. It should always be
referenced in conjunction with an application instance namespace. The
application namespace defaults to ``django_pydenticon``, unless custom instance
namespace is passed when including the application URLs via
``django_pydenticon.urls.get_patterns``. In case of default namespace, that
means the URL would be referenced to as ``django_pydenticon:image``.

For example, let's say that it's necessary to show an identicon based on
username next to every comment. A special context variable could be passed into
template that would contain a list of comments, where each comment consists out
of identicon URL and comment itself. The Python code could look something
similar to::

  comments_context = []

  for comment in comments:
      identicon_url = reverse("django_pydenticon:image",
                              kwargs={"data": comment.user.username})
      comments_context.append({"text": comment.text,
                               "identicon_url": identicon_url})

  return render_to_response('myapp/comments.html',
                            {"comments": comments_context})

With the above context set-up, the ``myapp/comments.html`` template could
contain a snippet similar to::

  <ul>
  {% for comment in comments %}
    <li><img src="{{ comment.identicon_url }}"/>{{ comment.text }}</li>
  {% endfor %}
  </ul>

Overriding identicon parameters
-------------------------------

By default, the identicon generator will use parameters from project settings
for each request, falling back to application defaults if none were defined. In
addition to this static configuration, some parameters can be overridden per
request.

Per-request identicon generator parameters are passed via *GET* parameters. The
following *GET* parameters are available:

w
  Specifies the width of generated identicon image in pixels. Overrides the
  ``PYDENTICON_WIDTH`` configuration option.

h
  Specifies the height of generated identicon image in pixels. Overrides the
  ``PYDENTICON_HEIGHT`` configuration option.

f
  Specifies the format of generated identicon. Overrides the
  ``PYDENTICON_FORMAT`` configuration option.

p
  Specifies the padding that will be added to the generated identicon image. The
  value should be provided as 4 comma-separated positive integers.

i
  Specifies whether the background and foreground colour in generated identicon
  should be inverted (swapped) or not. The value passed for this parameter
  should be ``true`` or ``false``.

Passing an invalid parameter value via *GET* parameter will result in a
``SuspiciousOperation`` exception being raised.

For example, the following request would generate an identicon with width of
``320``, height of ``240``, format ``PNG``, padding (top, bottom, left, right)
of ``10, 10, 20, 20``, and with inverted foreground and background colours::

  /identicon/image/somedata?w=320&h=240&f=png&p=10,10,20,20&i=true