Usage¶
Using Candy admin is similar to using Django’s default admin.
Example models¶
Let’s establish some models which will be used throughout this document for examples:
# models.py
from django.db import models
class Author(models.Model):
name = models.CharField(max_length=50)
gender = models.CharField(max_length=10)
email = models.EmailField()
class Post(models.Model):
author = models.ForeignKey(Author, on_delete=models.CASCASE)
title = models.CharField(max_length=150)
content = models.TextField()
Registering models¶
Registering models is similar to Django, except you use
django_candy.admin
:
# admin.py
from django_candy import admin
from myapp.models import Author, Post
admin.site.register(Author)
# Or for more control, use ModelAdmin class
class PostAdmin(admin.ModelAdmin):
list_display = ['title', 'author']
admin.site.register(Post, PostAdmin)
Customising list table columns¶
You can use ModelAdmin.list_display
to specify which fields appear in
list table:
from django_candy import admin
class AuthorAdmin(admin.ModelAdmin):
list_display = ['name', 'email']
admin.site.register(Author, AuthorAdmin)
List search¶
Currently, Candy doesn’t provide automatic search like Django’s default admin
does. Therefore, search_fields
and get_search_results
don’t work.
To implement search for your models, Candy provides a
get_filtered_queryset()
method. It receives
a request
, queryset
and query_params
arguments. The query_params
argument is a dict containing query parameters sent with the request. The name
for the search query parameter is q
which you can use for filtering the queryset.
This method returns a queryset.
class AuthorAdmin(admin.ModelAdmin):
def get_filtered_queryset(self, request, queryset, query_params):
search_term = query_params.get('q')
if search_term:
queryset = queryset.filter(name__istartswith=search_term)
return queryset
List filters¶
Django’s list_filter
option doesn’t work. Instead, use list_filters
(note the extra “s” at the end).
Candy doesn’t provide automatic filtering either.
list_filters
option should be a list which contains dicts of all the
filters and options.
Then, you can use the get_filtered_queryset()
method to filter the results.
class AuthorAdmin(models.Model):
list_filters = [
{
'label': 'Gender', 'name': 'gender', 'type': 'checkbox',
'options': [
{'label': 'Any', 'value': '', 'default': True},
{'label': 'Male', 'value': 'male'},
{'label': 'Female', 'value': 'female'},
]
},
{
'label': 'Sort by', 'name': 'sort_by', 'type': 'radio',
'options': [
{'label': 'Name (A-Z)', 'value': 'name'},
{'label': 'Name (Z-A)', 'value': '-name'},
]
}
]
def get_filtered_queryset(self, request, queryset, query_params):
gender = query_params.get('gender')
sort_by = query_params.get('sort_by')
if gender:
queryset = queryset.filter(gender__in=gender)
if sort_by:
queryset = queryset.order_by(sort_by)
return queryset