I am having a difficult time finding documentation on how to write a custom widget.
My questions are:
You're right in that Django doesn't supply documentation on this specific topic. I advise you to look at the builtin widgets in
django.forms.widgets (I'll reference classes from that module below).
If I build a custom widget, can it be used equivalently for the admin interface or for normal forms?
Admin overrides some widgets (see
django.contrib.admin.options.FORMFIELD_FOR_DBFIELD_DEFAULTS). You can probably subclass
ModelAdmin and change the
formfield_overrides attribute, but I have never done anything with
ModelAdmin so I can't help here...
If I want to allow the user to edit a list of items, what widget should I subclass? What methods of the widget do I need to override/implement?
Your widget probably doesn't have anything in common with the default widgets (with
Select if any?!). Subclass from
Widget and if you find any common pattern with builtins, you can still change it later.
Implement the following methods:
render(self, name, value, attrs=None, renderer=None)
Input.render for a simple example. It also supports user-defined attributes that are included in the HTML. You may also want to add "id" attributes, see
MultipleHiddenInput.render on how to do that. Don't forget to use
mark_safe when outputting HTML directly. If you have a rather complex widget you can use template rendering (example).
_has_changed(self, initial, data)
Optional. Used in admin to log messages about what was changed.
What widget method is responsible for going from the user's input back to the data model?
That has nothing to do with the widget - Django can't know what widget was used in an earlier request. It can only use the form (POST) data sent from the form. Therefore, the field method
Field.to_python is used to convert input to the Python data type (may raise
ValidationError if the input is invalid).