Commits

Mark Lavin committed 0efece0

Added basic admin docs. fixes #3.

Comments (0)

Files changed (3)

+Admin Integration
+====================
+
+Overview
+--------------------------------------
+
+Django-Selectables will work in the admin. To get started on integrated the
+fields and widgets in the admin make sure you are familiar with the Django
+documentation on the `ModelAdmin.form <http://docs.djangoproject.com/en/1.3/ref/contrib/admin/#django.contrib.admin.ModelAdmin.form>`_ 
+and `ModelForms <http://docs.djangoproject.com/en/1.3/topics/forms/modelforms/>`_ particularly
+on `overriding the default widgets <http://docs.djangoproject.com/en/1.3/topics/forms/modelforms/#overriding-the-default-field-types-or-widgets>`_. As you will see integrating Django-Selectables in the admin
+is the same as working with regular forms.
+
+
+Basic Example
+--------------------------------------
+
+In our sample project we have a `Farm` model with a foreign key to `auth.User` and 
+a many to many relation to our `Fruit` model.
+
+    .. literalinclude:: ../example/core/models.py
+        :lines: 11-17
+
+In `admin.py` we will define the form and associate it with the `FarmAdmin`.
+
+    .. literalinclude:: ../example/core/admin.py
+        :lines: 12-36
+
+You'll note this form also for new users to be created and associated with the
+farm if no user is found matching the given name. To make use of this feature we
+need to add `owner` to the exclude so that it will pass model validation. Unfortunately
+that means we must set the owner manual in the save and in the initial data because
+the `ModelForm` will no longer do this for you. Since `fruit` does not allow new
+items you'll see these steps are not necessary.
+
+
+Inline Example
+--------------------------------------
+
+With our `Farm` model we can also associate the `UserAdmin` with a `Farm`
+by making use of the `InlineModelAdmin 
+<http://docs.djangoproject.com/en/1.3/ref/contrib/admin/#inlinemodeladmin-objects>`_.
+We can even make use of the same `FarmAdminForm`.
+
+    .. literalinclude:: ../example/core/admin.py
+        :lines: 39-48
+
+The auto-complete functions will be bound as new forms are added dynamically.
+
     lookups
     fields
     widgets
+    admin
     releases
 
 

example/core/admin.py

 from django import forms
 
 import selectable.forms as selectable
-from selectable.forms.widgets import MEDIA_PREFIX
 
 from example.core.models import Fruit, Farm
 from example.core.lookups import FruitLookup, OwnerLookup
         widgets = {
             'fruit': selectable.AutoCompleteSelectMultipleWidget(lookup_class=FruitLookup),
         }
+        exclude = ('owner', )
 
-    def clean(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs):
+        super(FarmAdminForm, self).__init__(*args, **kwargs)
+        if self.instance and self.instance.pk and self.instance.owner:
+            self.initial['owner'] = self.instance.owner
+
+    def save(self, *args, **kwargs):
         owner = self.cleaned_data['owner']
         if owner and not owner.pk:
             owner = User.objects.create_user(username=owner.username, email='')
-            self.cleaned_data['owner'] = owner
-        return self.cleaned_data
+        self.instance.owner = owner
+        return super(FarmAdminForm, self).save(*args, **kwargs)
 
 
 class FarmAdmin(admin.ModelAdmin):