=======
Example
=======

.. _create-example-django-project:

---------------------------------
1 Create Django project polls app
---------------------------------

This example show quickly how to apply ``django_roles_access``. As is necessary
a simple Django project and application the example will use the *polls*
application that you can find in Django documentation: Polls_App_example_.

.. _Polls_App_example: https://docs.djangoproject.com/en/dev/intro/tutorial01/


.. note::

   The present example assume you have all the code of *polls app*.

--------------------
2 App and views name
--------------------

.. _`writing more views`: https://docs.djangoproject.com/en/dev/intro/tutorial03/#namespacing-url-names

Make sure you name views in *polls/urls.py* as in example you can found in
`writing more views`_. Also note how has been configurated
``app_name ='polls'`` .


-------------------------------------
3 Start using ``django_roles_access``
-------------------------------------

Imagine you want to keep polls application public, in this way all users
(anonymous or not) can vote a polls; but result should be restricted to a
special users with specific role.

Achieve this is very simple with ``django_roles_access``:

* Install ``django_roles_access`` middleware; or add ``django_roles_access``
  decorators to *results* views

  .. code-block:: python
      :caption: polls/views.py

      ...
      from django_roles_access.decorator import access_by_role
      ...

      @access_by_role
      def results(request, question_id):
          response = "You're looking at the results of questions %s."
          return HttpResponse(response % question_id)

* Go to *admin site*.

* Create a new :class:`django_roles_access.models.ViewAccess` and configure it:

  * **view** attribute: Type ``polls:results``.

  * **type** attribute: Select ``By role``.

  * **role** attribute: Add a :class:`django.contrib.auth.models.Group`
    representing the specific role.

If new users need access to the view, you only need to add then user to
any of the groups added to **roles** attribute. This can be done in run time
from *admin site*.

.. note::

   Is not nice at all to receive 403 Forbidden after voting!!!. A simple code
   modification could help:

   .. code-block:: python
       :caption: polls/views.py

       ...

       def vote(...

           ...

           return HttpResponseRedirect(reverse('polls:index'))