Author Background

For more information about Steven Wilcox, visit http://devpicayune.com.

Purpose

This paper (and corresponding talk) is designed to shed light on some of the very robust features that are quickly gained by utilizing the supplied Admin Interface in the Django Web Framework. Because the Admin portion of the framework is so powerful and thorough, there are actually quite a few applications that could be built solely on the Admin screens. Also, due to the speed a project can be setup with the Admin Interface and the additional database introspection tool provided with Django, it's possible to quickly create web-based administration screens for an existing web or non-web project that's been originally created in any language so long as the database is supported by Django.

When properly utilized, the Admin Interface then becomes both an incredibly useful tool for standalone applications, administration screens for existing or legacy projects, and also an invaluable weapon for Python advocacy within an organization.

Assumptions

• You know a little something about databases and you know at least a beginners level knowledge of Python
• You know how to use the internet to search for anything not covered
• Some of the information presented here could be incredibly wrong

Big Notice

ATTENTION: All code samples in this paper are presented using the Django NewForms-Admin which is currently just an active branch of the Django project with plans to merge into the trunk prior to version 1.0. While I hesitated to show information that was based on a version of Django that might not be suitable for production use at this moment, it's likely that within a matter of weeks, this will become the standard syntax and model for Admin use.

Check the NewForms-Admin branch for more information.

Also note that I've decided to just keep all my code in the models.py file. That's probably not good form, but for demonstration and teaching purposes, I believe it's more concise to keep it all in one file.

What's Not Covered

• Setting up or installing Django
• Django as a whole
• A complete review of everything that can be with Django's ORM
• A complete analysis of the entire Admin Interface supplied by Django
• The Answer to Life, the Universe and Everything... oh wait, that's 42.

Security

The security model in Django is built around the concept of users and groups. This is obviously, a pretty common and easily understood paradigm. Of note is the fact that a user can belong to multiple groups rather than just one.

The security model in Django (with respect to the Admin interface) also makes a couple of assumptions. As stated in The Django Book[1] regarding the Admin interface:

This is a Web-based interface, limited to trusted site administrators, that enables the adding, editing and deletion of site content.

So the biggest security assumption made is that the users are "trusted". But one of the reasons this paper/talk exists is that for a certain but fairly large set of applications, all the users of a particular application may be "trusted" to one extent or another. It's for this reason, that we can consider building an entire application using just the Admin interface (or at least relying on it for 90-99% of it).

With regard to security and the Admin site, one important point to remember is that users must have the "Staff Status" checked for them to be able to utilize the Admin interface. The other shortcut around the group membership is administrator status which basically enables all rights for a user.

In what may also be considered part of the Django Admin interface, there is a log kept as a basic form of audit trail that logs users actions on the data that includes the user, object, and which fields may have been changed. This log contains action messages like "changed description" (for a field change) or "added date 'dad birthday'" (for the addition of a related child record).

Data Manipulation

The bulk of what people think of as the Admin interface is the actual ability to deal with application data as part of web-interface. The Django Admin interface provides the ability to add/edit/delete records in tables that are defined in a Django application (using Django ORM).

There are a ton of configurable features and options that can be defined for these screens that affect how the browse lists function and look as well as the restrictions, validations, etc... made on records being added or changed.

It's this full-featured data manipulation interface for non-technical users that we so desperately need for so many applications. And Django's Admin is obviously very complete and out-of-the-box beautiful versus so many other frameworks. It's just a logical choice when you need to have a good looking and full featured Admin interface built in an extremely short amount of time.

From Scratch

If the database tables you are going to be using for your application don't exist yet, you can follow the standard instructions for building a new Django application. Part of those instructions have you writing out definitions for the data in the models.py for the application you are building.

For our example application, I setup something like this as a starting point in the models.py:

from django.db import models


class Address(models.Model):
    short_name = models.CharField(max_length=20)
    long_name = models.CharField(max_length=80)
    addr_line_1 = models.CharField(max_length=80,blank=True)
    addr_line_2 = models.CharField(max_length=80,blank=True)
    city = models.CharField(max_length=50)
    state = models.USStateField()
    zip = models.CharField(max_length=10,blank=True)


class PhoneType(models.Model):
    description = models.CharField(max_length=20)


class Phone(models.Model):
    description = models.CharField(max_length=80)
    number = models.PhoneNumberField()
    number_type = models.ForeignKey(PhoneType)
    address = models.ForeignKey(Address)


class Date(models.Model):
    description = models.CharField(max_length=80)
    start_date = models.DateField()
    annual_event = models.BooleanField()
    address = models.ForeignKey(Address)


class Group(models.Model):
    description = models.CharField(max_length=80)
    addresses = models.ManyToManyField(Address)


class Note(models.Model):
    note_text = models.TextField()
    address = models.ForeignKey(Address)

The only semi-custom thing I've done is indicated that some of the fields are not required by including the blank=True property in the definition of some of the fields. At this point, Admin is not enabled, we're just defining our ORM models for our database.

If you run syncdb command at this point, django will setup the basic framework support tables in the database, but you'll notice it doesn't even include our new models:

$ ./manage.py syncdb
Creating table auth_message
Creating table auth_group
Creating table auth_user
Creating table auth_permission
Creating table django_content_type
Creating table django_session
Creating table django_site

You just installed Django's auth system, which means you don't have any superusers defined.
Would you like to create one now? (yes/no): yes
Username (Leave blank to use 'steven'):
E-mail address: demo@site.demo
Password:
Password (again):
Superuser created successfully.
Installing index for auth.Message model
Installing index for auth.Permission model
Loading 'initial_data' fixtures...
No fixtures found.

Pay particular attention to the superuser setting because you'll need that later to login to the Admin interface. Set that carefully.

Edit the settings.py and add the addtracker application as an installed application so it should now look like this:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'addtracker',
)

Then rerun the syncdb application:

$ ./manage.py syncdb
Creating table addtracker_group
Creating table addtracker_note
Creating table addtracker_phone
Creating table addtracker_phonetype
Creating table addtracker_address
Creating table addtracker_date
Installing index for addtracker.Note model
Installing index for addtracker.Phone model
Installing index for addtracker.Date model
Loading 'initial_data' fixtures...
No fixtures found.

Now we actually have tables in our database that map with our models.

Importing (or Rather "Inspecting")

The other possible way of dealing with getting the database layout correctly setup in Django's ORM is the "inspectdb" command available as part of the manage.py application that is part of each django project.

For this example, I've created a new project called mydemo2 and an application called legacyapp to demonstrate setting up django based on existing database tables. The settings.py will be configured to point to a database schema called demo2 (again MySQL). The tables have a layout like this:

After setting up the settings.py similar to before (although this time my data is in the demo2 schema), we can run the inspectdb utility to give us a leg up on our models.py:

$ ./manage.py inspectdb
# This is an auto-generated Django model module.
# You'll have to do the following manually to clean this up:
#     * Rearrange models' order
#     * Make sure each model has one field with primary_key=True
# Feel free to rename the models, but don't rename db_table values or field names.
#
# Also note: You'll have to insert the output of 'django-admin.py sqlcustom [appname]'
# into your database.

from django.db import models

class Authors(models.Model):
    name = models.CharField(max_length=60, primary_key=True)
    nickname = models.CharField(max_length=60)
    description = models.TextField()
    class Meta:
        db_table = u'authors'

class Entries(models.Model):
    id = models.IntegerField(primary_key=True)
    title = models.CharField(max_length=600)
    postdate = models.DateTimeField()
    modifydate = models.DateTimeField()
    contents = models.TextField()
    author = models.CharField(max_length=60)
    class Meta:
        db_table = u'entries'

This is pretty close to right. For some reason, in my particular version, you can see it was multiplying the max_length by 3, so that's got to be tweaked (issue 5725). The other thing here is that while it correctly identifies the primary fields, inspectdb is unable to detect that the id field is auto numbered. Also, because I'm using a MyISAM storage engine for MySQL, there is no true database support for foreign keys, so inspectdb can't detect those either.

So making a couple of changes to the above version of models.py we now have:

from django.db import models

class Authors(models.Model):
    name = models.CharField(max_length=20, primary_key=True)
    nickname = models.CharField(max_length=20)
    description = models.TextField()
    class Meta:
        db_table = u'authors'

class Entries(models.Model):
    id = models.AutoField(primary_key=True)
    title = models.CharField(max_length=200)
    postdate = models.DateTimeField()
    modifydate = models.DateTimeField()
    contents = models.TextField()
    author = models.ForeignKey(Authors,db_column='author')
    class Meta:
        db_table = u'entries'

First, I fixed the id field in Entries to be an AutoField since it is auto-numbered by the database. We wouldn't want the admin interface demand that we enter a number there.

Second, I changed the author field to be a ForeignKey to Authors. If the author field in Entries actually linked to a non-primary key, Django even offers an option called to_field so that a specific field can be specified to link to. I also had to specify the the option db_column to specify that the name of the field in the database really was just 'author' because under the covers, Django is used naming those types of fields with an '_id' appended to the name of the field.

Depending on how the postdate and modifydate fields are used, you may have to decide to deal with those. If the legacy application normally fills those, and now your application is being requested to fill those, you'll have to accomodate that. So let's say that the postdate field is filled when the record is originally created by the user, and the modifydate field is always updated anytime the record is added or edited. And we're obviously stating that the database isn't taking care of that for us in this case, that the application is expected to do that.

Without wandering out of the models.py and without changing the table, we can handle that also:

from django.db import models
import datetime

class Authors(models.Model):
    name = models.CharField(max_length=20, primary_key=True)
    nickname = models.CharField(max_length=20)
    description = models.TextField()
    class Meta:
        db_table = u'authors'

    def __str__(self):
        return self.name

class Entries(models.Model):
    id = models.AutoField(primary_key=True)
    title = models.CharField(max_length=200)
    postdate = models.DateTimeField(editable=False)
    modifydate = models.DateTimeField(editable=False)
    contents = models.TextField()
    author = models.ForeignKey(Authors,db_column='author')
    class Meta:
        db_table = u'entries'

    def save(self):
        if not self.id:
            self.postdate = datetime.date.today()
        self.modifydate = datetime.datetime.today()
        super(Entries, self).save()

In this version, we're sub-classing the save method of the model. Prior to doing the normal saving, we set the postdate to today's date and the modifydate to the current date and time (more of a true timestamp). But also note that in the field definitions, I added the editable=False option so that those fields wouldn't be manually entered on the Admin form. [3]

Inline Child Records

The NewForms-Admin makes inline child records very logical and easy to implement. We'll look at Phone child. We want to be able to add and edit related phone records when we're on the address record form. For this particular purpose, the admin.TabularInline class is perfect. We just define a class that inherits from admin.TabularInline and then specify the options we want:

class PhoneInline(admin.TabularInline):
    model = Phone
    extra = 3

class AddressOptions(admin.ModelAdmin):
    search_fields = ['short_name','long_name','city']
    list_display = ('short_name','city','state')
    ordering = ('short_name',)
    list_filter = ('state',)
    fieldsets = (('Name',
               {'fields':('short_name',
                          'long_name')}),
              ('Address',
               {'fields':('addr_line_1',
                          'addr_line_2',
                          'city',
                          'state',
                          'zip')}),
        )
    inlines = [PhoneInline]

Then, our AddressOptions class we specify a new option called inlines which is really just a list of all inline child record classes. So far, we're just working on Phone records so we add the new PhoneInline object in our list of inlines.

Now we've got the ability to add/edit/delete phone records as needed from within the parent record. By the way, the TabularInline versus the StackedInline is really about the field representation. The TabularInline has a grid sort of field (as you can see in the screen shot) where fields are spread across the screen as if they were in a table of a data (hence the term 'tabular' I guess). 'Stacked' is like having the admin screen for that child record right there embedded as the field and value pairs go down rather than across.

So in our example application, I'll just add the notes and dates children on there. The final bit of customization needed to have a useable application is a tweak to the Group form. The default group form has a small box where you Ctrl-Click on the members you want or don't want in the group. It works but likely won't pass the spouse-friendly user interface test. So, we'll tweak that by specifying in its Admin options class that we want a horizontal selection inteferface so that it looks like this:

After some final tweaks, this is the final version of the models.py:

from django.db import models
from django.contrib import admin


class Address(models.Model):
    short_name = models.CharField(max_length=20,
                                  verbose_name="last name",
                                  help_text="name used for sorting purposes")
    long_name = models.CharField(max_length=80,
                                 help_text="the text that would appear on an envelope")
    addr_line_1 = models.CharField(max_length=80,blank=True,verbose_name="address line 1")
    addr_line_2 = models.CharField(max_length=80,blank=True,verbose_name="address line 2")
    city = models.CharField(max_length=50)
    state = models.USStateField()
    zip = models.CharField(max_length=10,blank=True)

    def __str__(self):
        return self.short_name + ' (' + self.city + ', ' + self.state + ')'

    class Meta:
        verbose_name_plural = 'addresses'


class PhoneType(models.Model):
    description = models.CharField(max_length=20)

    def __str__(self):
        return self.description


class Phone(models.Model):
    description = models.CharField(max_length=80)
    number = models.PhoneNumberField()
    number_type = models.ForeignKey(PhoneType)
    address = models.ForeignKey(Address)

    def __str__(self):
        return str(self.number)


class Date(models.Model):
    description = models.CharField(max_length=80)
    start_date = models.DateField()
    annual_event = models.BooleanField()
    address = models.ForeignKey(Address)


class Group(models.Model):
    description = models.CharField(max_length=80)
    addresses = models.ManyToManyField(Address)

    def __str__(self):
        return self.description


class Note(models.Model):
    note_text = models.TextField()
    address = models.ForeignKey(Address)


class DateInline(admin.TabularInline):
    model = Date
    fields = ('start_date','description','annual_event')
    extra = 2

class NoteInline(admin.StackedInline):
    model = Note
    extra = 1

class PhoneInline(admin.TabularInline):
    model = Phone
    extra = 3

class AddressOptions(admin.ModelAdmin):
    search_fields = ['short_name','long_name','city']
    list_display = ('short_name','city','state')
    ordering = ('short_name',)
    list_filter = ('state',)
    fieldsets = (('Name',
               {'fields':('short_name',
                          'long_name')}),
              ('Address',
               {'fields':('addr_line_1',
                          'addr_line_2',
                          'city',
                          'state',
                          'zip')}),
        )
    inlines = [PhoneInline,DateInline,NoteInline]

class GroupOptions(admin.ModelAdmin):
    filter_horizontal = ('addresses',)


admin.site.register(Address,AddressOptions)
admin.site.register(PhoneType)
admin.site.register(Group,GroupOptions)

It isn't perfect but in what ended up being an hour or less of coding and playing with settings, we have a useable and decent looking application.

If you want to customize the "Django administration" text throughout the system to match you can find that information on-line, of course.

There are also some guides to changing and customizing the CSS used to style the Admin interface so that you can really make it feel like your own application.

And finally, you can take the existing Admin templates and use them as a starting point for additional views and forms as reports or special input screens.