diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000000000000000000000000000000000000..4e373d433ecbb38cc8d5ac2a9a7b060e87addd15 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,151 @@ +.. _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:: + + + +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:: + + + +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