Activating the administration interface
The administration interface comes as a Django application. To activate it, we will follow a simple procedure that is similar to enabling the user authentication system. The administration application is located in the django.contrib.admin package. So the first step is adding the path of this package to the INSTALLED_APPS variable. Open the settings.py file, locate INSTALLED_APPS, and edit it as follows:
INSTALLED_APPS = (
Next, run the following command to create the necessary tables for the administration application:
$ python manage.py syncdb
Now we need to make the administration interface accessible from within our site by adding URL entries for it. The admin application defines many views (as we will see later), so manually adding a separate entry for each view can become a tedious task. Therefore, the admin interface provides a shortcut for this. There is a single object that encapsulates all the admin views. To use it, open the urls.py file and edit it as follows:
from django.contrib import admin
urlpatterns = ('',
# Admin interface
Here, we are importing the admin module, calling a method in it, and mapping all the URLs under the path ^admin/ to a view called admin.site.root. This will make the views of the administration interface accessible from within our project.
One last thing remains before we see the administration page in action. We need to tell Django what models can be managed in the administration interface. This is done by creating a new file called the admin.py file in the bookmarks directory. Create the bookmarks/admin.py file and add the following code to it:
from django.contrib import admin
from bookmarks.models import *
We created a class derived from the admin.ModelAdmin class and mapped it to the Link model using the admin.site.register method. This effectively tells Django to enable the Link model in the administration interface. The keyword pass means that the class is empty. Later, we will use this class to customize the administration page; so it won't remain empty.
Do the same to the Bookmark, Tag, and SharedBookmark models and add it to the bookmarks/admin.py file. Now, create an empty admin class for each of them and register it. The User model is provided by Django and, therefore, we don't have control over it. But fortunately, it already has an Admin class so it's available in the administration interface by default.
Next, launch the development server and direct your browser to http://127.0.0.1:8000/admin/. You will be greeted by a login page. The superuser account after writing the database model is the account that you have to use in order to log in:
Next, you will see a list of the models that are available to the administration interface. As discussed earlier, only models that have admin classes in the bookmarks/admin.py file will appear on this page.
If you click on a model name, you will get a list of the objects that are stored in the database under this model. You can use this page to view or edit a particular object, or to add a new one. The following figure shows the listing page for the Link model:
The edit form is generated according to the fields that exist in the model. The Link form, for example, contains a single text field called Url. You can use this form to view and change the URL of a Link object. In addition, the form performs proper validation of fields before saving the object. So if you try to save a Link object with an invalid URL, you will receive an error message asking you to correct the field. The following figure shows a validation error when trying to save an invalid link:
Fields are mapped to form widgets according to their type. For example, date fields are edited using a calendar widget, whereas foreign key fields are edited using a list widget, and so on. The following figure shows a calendar widget from the user edit page. Django uses it for date and time fields.
As you may have noticed, the administration interface represents models by using the string returned by the __unicode__ method. It was indeed a good idea to replace the generic strings returned by the default __unicode__ method with more helpful ones. This greatly helps when working with the administration page, as well as with debugging.
Experiment with the administration pages. Try to create, edit, and delete objects. Notice how changes made in the administration interface are immediately reflected on the live site. Also, the administration interface keeps a track of the actions that you make and lets you review the history of changes for each object.
This section has covered most of what you need to know in order to use the administration interface provided by Django. This feature is actually one of the main advantages of using Django. You get a fully featured administration interface from writing only a few lines of code!
Next, we will see how to tweak and customize the administration pages. As a bonus, we will learn more about the permissions system offered by Django.
Users, groups, and permissions
So far, we have been logged into the administration interface using the superuser account that we created with manage.py syncdb. In reality, however, you may have other trusted users who need access to the administration page. In this section, we will see how to allow other users to use the administration interface. We will also learn more about the Django permissions system in the process.
Before we continue, I want to emphasize that only trusted users should be given access to the administration pages. The administration interface is a very powerful tool, so only those whom you know well should be granted access to it.
If you don't have users in the database other than the superuser, create a new user account using a registration form. Alternatively, you could use the administration interface by clicking on Users | Add User. Next, return to the Users list and click on the name of the newly created user. You will get a form which can be used to edit various aspects of the user account such as name and email information. Under the Permissions section of the edit form, you will find a checkbox labeled Staff status. Enabling this checkbox will let the new user enter the administration interface. However, they won't be able to do much after they log in because this checkbox only grants access to the administration area, and it does not give the ability to see or change the data models.
To give permission to the new user to change the data models, you can enable the superuser status checkbox, which will grant the new user full permission to perform any function that he or she wants. This option makes the account as powerful as the superuser account created by manage.py syncdb.
However, on the whole, it's not desirable to grant a user full access to everything. Therefore, Django gives you the ability to have fine control over what users can do through the permissions system. Below the Superuser status checkbox, you will find a list of permissions that you can grant to the user. If you examine this list, you will find that each data model has three types of permissions:
- Adding an object to the data model
- Changing an object in the data model
- Deleting an object from the data model
These permissions are automatically generated by Django for data models that contain an Admin class. Use the arrow button to grant some permission to the account that we are editing. For example, give the account the ability to add, edit, and delete—links, tags, and bookmarks. Next, log out and then log into the administration interface again using the new account. You will notice that you will only be able to manage the Link, Tag, and Bookmark data models.
The permissions section of the user edit page also contains a checkbox called Active. This checkbox can be used as a global switch to enable and disable the account. When unchecked, the user won't be able to log into the main site or the administration area.
If you have a considerable number of users who share the same permissions, it would be a tedious and error-prone task to edit each user's account and assign the same permissions to them. Therefore, Django provides another user management facility—groups. To put it simply, groups are a way of categorizing users who share the same permissions. You can create a group and assign permissions to it. And when you add a user to the group, this user is granted all of the group's permissions.
Creating a group is not any different from other data models. Click Groups on the main page of the administration interface, and then click on Add Group. Next, enter a group name and assign some permissions to the group. Finally, click Save.
To add a user to a group, edit the user account, scroll to the Groups section in the edit form, and select whichever group you want to add the user to.
Using permissions in views
Though we have only used permissions in the administration interface so far, Django also lets us utilize the permission system while writing views. When programming a view, it is possible to use permission s to grant a group of users access to a particular feature or a page, such as private content. We will learn about methods that can be used to do so in this section. We won't actually make changes to the code of our application, but feel free to do so if you want to experiment with the methods explained.
If you wanted to check whether a user has a particular permission, you could use the has_perm method on the User object. This method takes a string that represents the permission in the following format:
app is the name of the application where the model is located; operation is either add, change, or delete; and model is the name of the model. For example, to check whether the user can add tags, use:
And to check if the user can change bookmarks:
Furthermore, Django provides a decorator that can be used to restrict a view to the users who have a particular permission. The decorator is called permission_required and is located in the django.contrib.auth.decorators package.
Using this decorator is similar to how we used the login_required decorator to restrict pages to the logged-in users. Let's say we want to restrict the bookmark_save_page view (in the bookmarks/views.py file) to users who have the bookmarks.add_bookmark permission. To do so, we can use the following code:
from django.contrib.auth.decorators import permission_required
This decorator takes two parameters: the permission to check for, and where to redirect users if they don't have the required permission.
The question of whether to use the has_perm method or the permission_required decorator depends on the level of control that you want. If you need to control access to a view as a whole, use the permission_required decorator. However, if you need finer control over permissions inside a view, use the has_perm method. These two approaches should be sufficient for any permission-related needs.
Though this article is relatively short, we learned how to implement a lot of things. This emphasizes the fact that Django lets you do a lot with only a few lines of code. You learned how to utilize Django's powerful administration interface, customize it, and take advantage of the comprehensive permission system.
Here is a quick summary of the features covered in this article.
- Activating the administration interface consists of the following steps:
- Add the django.contrib.admin application to INSTALLED_APPS in the settings.py file
- Run the manage.py syncdb command to create the administration application tables
- Add URL entries for the administration pages to the urls.py file
- For each model that you want to manage through the administration interface, add a corresponding admin class and register it in the admin.py file
- You can customize listing pages in the administration interface by adding one or more of the following fields to the admin class: list_display, list_filter, ordering, and search_fields
- You can check whether a user has a particular permission by using the has_perm method on the User object
- You can restrict a view to users who have a particular permission by using the permission_required decorator from the django.contrib.auth.decorators package