The newforms-admin branch has landed! It has been in development for quite some time and is now in trunk. I am extremely excited about it. However, I am a special case since I have been using the branch for quite some and even a committer on the branch. Migration for me has been easy, but I wanted to share that knowledge with everyone else. I have been seeing a lot of people getting stuck on where to begin. The admin documentation is quite pointless for those who have exisiting Django code. That is done on purpose. The newforms-admin branch wiki page has the information you are looking for.
I am going to go in-depth about how to perform this migration. I have done so in the screencast and will also provide a textual version here as well.
Download screencast (61.9 MB, 12:23, 800x600, Apple Animation)
Migrating Your Code to newforms-admin
Let us begin by starting with old-style admin code. Here are two models where we have a model that is edited inline:
class Post(models.Model):
title = models.CharField(max_length=100)
slug = models.SlugField(prepopulate_from=("title",))
pub_date = models.DateField()
class Admin:
list_display = ("title", "pub_date")
class Link(models.Model):
post = models.ForeignKey(Post, edit_inline=models.TABULAR)
title = models.CharField(max_length=100, core=True)
url = models.URLField(core=True)
newforms-admin has completely decoupled the admin syntax and options from the models. This is to provide a cleaner and more controllable expierence. It may have been more convenient before, but ultimately it isn't a ton more verbose, but gives you plenty of areas for customization.
The first thing you will need to do is create an admin.py file in your
app. This is where your new ModelAdmin subclasses will live. Here is what
the above Post model will turn into:
from django.contrib import admin
class PostAdmin(admin.ModelAdmin):
list_display = ("title", "pub_date")
prepopulated_fields = {"slug": ("title",)}
The prepopulate_from keyword argument has been translated to
prepopulated_fields. Most of the old inner Admin class options have
stayed the same, but be sure to make sure.
The last bit that needs to be moved out from the models is the edit_inline
and core keyword arguments. You can safely just remove any and all core
arguments. They are no longer used. newforms-admin now provides a nice delete
checkbox for exisiting instances in inlines. Your admin.py will now look
like after changing the edit_inline bit:
from django.contrib import admin
from myproject.myapp.models import Link
class LinkInline(admin.TabularInline):
model = Link
class PostAdmin(admin.ModelAdmin):
list_display = ("title", "pub_date")
prepopulated_fields = {"slug": ("title",)}
inlines = [
LinkInline,
]
Hooking everything up
Now that you have done a migration of the code, we now need to tie everything
together. Another change in newforms-admin is how the URL is routed. Before
it worked with an include:
from django.conf.urls.defaults import *
urlpatterns = patterns('',
(r'^admin/', include('django.contrib.admin.urls')),
)
That no longer works since django.contrib.admin.urls no longer exists. The
new way introduces the notion of individual sites. Those are defined with the
AdminSite class. Here is how you would quickly migrate this part of the
code:
from django.conf.urls.defaults import *
from django.contrib import admin
admin.autodiscover()
urlpatterns = patterns('',
(r'^admin/(.*)', admin.site.root),
)
Ok, notice the addition of admin.autodiscover(). This is a simple function
that iterates over INSTALLED_APPS and imports the admin.py module of
each. The reason for this is because you should always register your models
to their ModelAdmin classes for the default AdminSite instance. At the
bottom of your admin.py file add:
admin.site.register(Post, PostAdmin)
Based on the example code above, you will also need to import the Post
model into scope.
Custom AdminSite instances
There are cases where you may want more than one admin interface that are
registered to different models. Or perhaps you would like to override behavior
or options of any app that provides ModelAdmin classes. This is very
simple. Simply create a project-level admin.py module. Inside it create
your own AdminSite class:
from django.contrib import admin
class AdminSite(admin.AdminSite):
pass
site = AdminSite()
Now, use this instead of the default instance in your urls.py:
from django.conf.urls.defaults import *
from myproject.admin import site
urlpatterns = patterns('',
(r'^admin/(.*)', site.root),
)
Notice how I have removed admin.autodiscover(). This is no longer needed
since we don't really need to be automatically import the app's admin.py
modules. It is done in our project-level admin.py, but really doesn't
matter since we are not using the default instance. We could if we wanted, but
in this case we don't.
Now do all registration for our new AdminSite instance in the
project-level admin.py:
from django.contrib import admin
from myproject.myapp.admin import PostAdmin
from myproject.myapp.models import Post
class AdminSite(admin.AdminSite):
pass
site = AdminSite()
site.register(Post, PostAdmin)
We could even customize the contrib app's ModelAdmin subclasses and
provide our own behavior or option overrides:
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from django.contrib.auth.models import User
from myproject.myapp.admin import PostAdmin
from myproject.myapp.models import Post
class AdminSite(admin.AdminSite):
pass
site = AdminSite()
class MyUserAdmin(UserAdmin):
list_display = ("username",)
site.register(User, MyUserAdmin)
site.register(Post, PostAdmin)
That is all I have for now. I will be doing more posts in the future about
the additional hooks you can find with AdminSite and ModelAdmin
classes. Let me know what you think!
Great screencast! Just moved my site over to newforms admin. It seems faster too, but I don't know if that's just me imagining it :)
Thanks for all your hard work on this!
Posted by Eric Holscher on Jul 20, 2008 at 6:50 PM