The following isn't magic but it was unclear to me and required reading both documentation and source code and some additional Googling to get right. Maybe that's because I'm a Django newbie, but hey, I'm probably not the only one. By the way, the following applies to Django SVN revision 8068. That's roughly Django 1.0 alpha.
Anyway, I have in my model a field that's basically a time-stamped boolean: a field called deleted of type DateTimeField. If it's NULL, the thing, let's call it Foo, is not deleted; if it has a value, it tells us the Foo in question was marked as deleted back then. It's not the only way I could have implemented it but it meets my requirements and I didn't want to change it.
How to display that in admin? I could have left it as just a split datetime field, but that doesn't really communicate the intent. A checkbox with additional text telling the date is a much better representation.
I found some help in in Stuart Langridge's Overriding a single field in the Django admin, using newforms-admin, but it seems it's slightly outdated and didn't contain all the details.
Turns out for this to work well, I needed three bits: a widget class, a field class and a formfield_for_dbfield method in my ModelAdmin class.
Here's my widget class:
def __init__(self, attrs=None, check_test=lambda v: v is not None):
super(BooleanDateWidget, self).__init__(attrs, check_test)
def render(self, name, value, attrs=None):
final_attrs = self.build_attrs(attrs, type='checkbox', name=name)
result = self.check_test(value)
except: # Silently catch exceptions
result = False
final_attrs['checked'] = 'checked'
dt = ' <label for="%s" class="vCheckboxLabel">(%s)</label>' % (final_attrs["id"], value)
dt = ""
if value not in ('', True, False, None):
# Only add the 'value' attribute if a value is non-empty.
final_attrs['value'] = force_unicode(value)
return mark_safe(u'<input%s />%s' % (flatatt(final_attrs), dt))
The render method has mostly been copied and pasted from django.forms.CheckboxInput.render, with a few modifications to create an additional label. When database value is rendered to the admin form, that method gets called. If deleted is NULL, it creates an empty checkbox; if there's a date there, it creates a checked checkbox with an additional label that contains the timestamp (not very prettily formatted, though.)
Next, the field class:
widget = BooleanDateWidget
def clean(self, value):
v = super(BooleanDateField, self).clean(value)
That's pretty simple. I just specify the widget to use and make the clean method which is called when the value sent by the browser is validated for storage in the model return either None if the checkbox was checked or None otherwise.
And finally the last piece is formfield_for_dbfield method in the ModelAdmin class.
def formfield_for_dbfield(self, db_field, **kwargs):
if db_field.name == 'deleted':
field = db_field.formfield(form_class=booleandate.BooleanDateField)
field = super(FooAdmin,self).formfield_for_dbfield(db_field,**kwargs)
That method is invoked when the newforms-admin interface needs the field object for displaying and handling the deleted value. It checks the field name to specialize the interface. For the deleted class, we call the db_field object's formfield method, otherwise we delegate to ModelAdmin. ModelAdmin's formfield_for_dbfield is pretty simple itself, it mostly just sets the widget type for a few field types and calls the formfield method of the db_field object. That's what we could have done here, too; instead of specifying the widget type in the Field class, we could have done it here.
That's all it takes! With those modifications, the split datetime field disappears and instead you get a datetime-labeled checkbox.