django-admin-flexselect 0.4.1

## About Django Admin FlexSelect ##

FlexSelect is a small app for the Django Admin that makes it trivial to have
foreign keys depend on each other. By depend I mean that choices and additional
content of one field updates dynamically when another is changed.

## Usage example ##

See the video at http://www.youtube.com/watch?v=ooii3iCTZ6o.

In the following we will define a Case model with two foreign key fields, a
base field `client` and a trigger field `company_contact_person`. When we
change the client on the Case change view the company_contact_person updates
accordingly. Furthermore we will display the customer_contact_persons company
and email as additional details.

In "models.py":

```python
from django.db import models as m
from django.core.exceptions import ValidationError

"""
No changes to the models are needed to use flexselect.
"""

class Company(m.Model):
name = m.CharField(max_length=80)

def __unicode__(self):
return self.name

class CompanyContactPerson(m.Model):
company = m.ForeignKey(Company)
name = m.CharField(max_length=80)
email = m.EmailField()

def __unicode__(self):
return self.name

class Client(m.Model):
company = m.ForeignKey(Company)
name = m.CharField(max_length=80)

def __unicode__(self):
return self.name

class Case(m.Model):
client = m.ForeignKey(Client)
company_contact_person = m.ForeignKey(CompanyContactPerson)

def clean(self):
"""
Makes sure the company for client is the same as the company for the
customer contact person. Note that you need to check for `None` too
if the fields are not required.
"""
if not self.client.company == self.company_contact_person.company:
raise ValidationError('The clients and the contacts company does'
' not match.')

def __unicode__(self):
return u'Case: %d' % self.id
```

In "admin.py":

```python
from django.contrib import admin
from flexselect import FlexSelectWidget
from test_flexselect.tests.models import (Company, Case, Client,
CompanyContactPerson,)

class CompanyContactPersonWidget(FlexSelectWidget):
"""
The widget must extend FlexSelectWidget and implement trigger_fields,
details(), queryset() and empty_choices_text().
"""

trigger_fields = ['client']
"""Fields which on change will update the base field."""

def details(self, base_field_instance, instance):
"""
HTML appended to the base_field.

- base_field_instance: An instance of the base_field.
- instance: A partial instance of the parent model loaded from the
request.

Returns a unicoded string.
"""
return u"""\
<div>
<dl>
<dt>%s</dt><dd>%s</dd>
<dt>%s</dt><dd>%s</dd>
</dl>
</div>
""" % ('Company', base_field_instance.company,
'Email', base_field_instance.email,
)

def queryset(self, instance):
"""
Returns the QuerySet populating the base field. If either of the
trigger_fields is None, this function will not be called.

- instance: A partial instance of the parent model loaded from the
request.
"""
company = instance.client.company
return CompanyContactPerson.objects.filter(company=company)

def empty_choices_text(self, instance):
"""
If either of the trigger_fields is None this function will be called
to get the text for the empty choice in the select box of the base
field.

- instance: A partial instance of the parent model loaded from the
request.
"""
return "Please update the client field"

class CaseAdmin(admin.ModelAdmin):
def formfield_for_foreignkey(self, db_field, request, **kwargs):
"""
Alters the widget displayed for the base field.
"""
if db_field.name == "company_contact_person":
kwargs['widget'] = CompanyContactPersonWidget(
base_field=db_field,
modeladmin=self,
request=request,
)
kwargs['label'] = 'Contact'
return super(CaseAdmin, self).formfield_for_foreignkey(db_field,
request, **kwargs)

class ClientAdmin(admin.ModelAdmin):
pass

class CompanyContactPersonAdmin(admin.ModelAdmin):
pass

class CompanyAdmin(admin.ModelAdmin):
pass

admin.site.register(Case, CaseAdmin)
admin.site.register(Client, ClientAdmin)
admin.site.register(CompanyContactPerson, CompanyContactPersonAdmin)
admin.site.register(Company, CompanyAdmin)
```

## Installation ##

sudo pip install django-admin-flexselect

## Configuration ##

1. Add `"flexselect",` to `INSTALLED_APPS` in "settings.py".

2. Add `(r'^flexselect/', include('flexselect.urls')),` to "urls.py".

### Options ###
As of yet, flexselect only have one configuration option, namely
"include_jquery" that if set to true will include jQuery and jQueryUI from
the google ajax CDN. It defaults to false and the entire FLEXSELECT dict can
be omitted.

```python
# Flexselect settings.
FLEXSELECT = {
'include_jquery': True,
}
```

### Static files ###
FlexSelect requires "django.contrib.staticfiles" installed to work
out of the box. If it is not then include "jQuery", "jQueryUI" and
"flexselect/static/flexselect/js/flexselect.js" manually. Read more about
"django.contrib.staticfiles" at
https://docs.djangoproject.com/en/1.3/ref/contrib/staticfiles/.