admin site

基本步骤：

1、添加 'django.contrib.admin' 到 INSTALL_APP 设置中。

2、再添加四个依赖项： 'django.contrib.auth', 'django.contrib.contenttype', 'django.contrib.message', 'django.contrib.sessions'。

3、添加 'django.contrib.messages.context_processors.messages' 到 TEMPLATE_CONTEXT_PROCESSORS 设置中；

4、添加 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.message.middleware.MessageMiddleware' 到 MIDDLEWARE_CLASSES 设置中，如果要使 admin site 显示本地语言，则将 'django.middleware.locale.LocaleMiddleware' 也添加加进去即可。

5、编辑你的 models，然后为每一个 model 编写相应的 admin.ModelAdmin 的子类，它用来定制你的 admin site。

6、在 admin.py 里注册你的 model 和相应的 ModelAdmin，如 admin.site.register(model_name,ModelAdmin_name)

Admin actions:

actions 主要用来对记录进行批量操作，比如内置的批量删除(使用 QuerySet.delete() )，或批量设置一批记录的某个字段的枚举值等。

actions function 包括三个参数，分别是 ModelAdmin, HttpRequest, QuerySet(多选框选中的数据集)。如：

def action_valid_false(modeladmin,request, queryset):
    rows = queryset.update(valid=0)
    if rows:
        modeladmin.message_user(request, "成功修改了 %s 条记录" %rows)
    else:
        modeladmin.message_user(request, "没有数据被修改")
action_valid_false.short_description='批量禁止登陆'
actions = ['action_valid_false']

然后把自定义的 action function 添加到 actions 列表中(如果不想显示任何action，则可设置 actions = None)。（系统默认有一个批量删除的 action function, 名为 delete_selected）上面的 demo 中，有一句 modeladmin.message_user(request, "没有数据被修改") ,是用于向用户反馈的操作结果提示。详见 django.contrib.admin.ModelAdmin.message_user()。

如果希望进行 action 操作时，可以跳转到一个中间页面，比如确认操作页面，或其它提示页面，下面的 demo 即跳转到显示操作对象 json 格式数据(同样可以转成 xml)的中间页：

from django.http import HttpResponse
from django.core import serializers

class MyModelAdmin(admin.ModelAdmin):
    def export_as_json(modeladmin, request, queryset):
        response = HttpResponse(content_type="application/json")
        serializers.serialize("json", queryset, stream=response)
        return response
    admin.site.add_action(export_as_json)
    export_as_json.short_description='导出成JSON格式'

更好的做法是，返回一个 HttpResponseRedirect 对象将用户重定向到自己写的 view 去处理：

from django.contrib.contenttypes.models import ContentType
from django.http import HttpResponseRedirect

class MyModelAdmin(admin.ModelAdmin):
    def export_selected_objects(modeladmin, request, queryset):
        selected = request.POST.getlist(admin.ACTION_CHECKBOX_NAME)
        #ContentType.objects.get_for_model(queryset.model)
        return HttpResponseRedirect("/export/?ids=%s" % (",".join(selected)))
    export_selected_objects.short_description = '跳转到处理页面'
    admin.site.add_action(export_selected_objects)

add_action 函数有两个参数，第一个参数为 action_function 名，第二个是可选参数，为 action_function 取一个别名，如果忽略第二个参数，则默认别名即为 action_function 名。该别名主要用于 actions 中存储 action 的键名，disable_action 函数的参数也会用到这个键名。

可以重载 ModelAdmin.get_actions(request) 函数，有条件的启用或禁用一些动作，如系统默认提供的 delete_selected 的 action：

def get_actions(self, request):
    actions = super(PUserAdmin, self).get_actions(request)
    del actions['delete_selected']
    logging.warning(actions)
    return actions

除此之外，action 还有几个配置项，都有默认值，如 actions_on_top = True, actions_on_bottom = False, actions_selection_counter = True, 你也可以自己来定制。

关于 action ,尚未理解的部分，是通过 add_action\disable_action 与 actions 同时设置时，到底是如何起作用的。

admindocs

1、添加 django.contrib.admindocs 到 INSTALL_APPS 中。

2、添加 url(r'^admin/doc/',include('django.contrib.admindocs.urls')) 到 urlpatterns。(注意，要放在 url(r'^admin/', include(admin.site.urls)) 之前)

3、完成上面两个步骤，即可请求 http://127.0.0.1/admin/doc ,会提示需要 docutils 模块支持，下载安装之后重启服务器，再浏览即可。

此处有两点尚未实践：

Optional: Linking to templates requires the ADMIN_FOR setting to be configured.

Optional: Using the admindocs bookmarklets requires django.contrib.admindocs.middleware.XViewMiddleware to be installed.

ModelAdmin objects

ModelAdmin 类是 model 的界面表示类，存储于 admin.py 文件中，使用方法如下：

from django.contrib import admin
from myproject.myapp.models import Author

class AuthorAdmin(admin.ModelAdmin):
    pass
admin.site.register(Author, AuthorAdmin)

admin.site.register 的第二个参数是可选的，如果你的 model 不需要任何自定制，则可不需要定制相应的 ModelAdmin 修饰类。

ModelAdmin options

选项	类型	描述	例子
actions	list	所有可用的动作列表	actions = ['action_valid_false']
actions_on_top	bool	动作条是否显示在上方，默认为 True	actions_on_top = False
actions_on_bottom	bool	动作条是否显示在下方，默认为 False	actions_on_bottom = True
actions_selection_counter	bool	动作条后是否显示选中的对象个数，默认为 True	actions_selection_counter = False
data_hierarchy	str	在对象列表上方显示的，以年月日分层的筛选器。只能设置为 DataField 和 DateTimeField 类型的字段。	data_hierarchy = 'regtime'
exclude	tuple	与 fields 作用相反，设置编辑页面中不显示的字段。 如果与 fields 设置了同一字段，则直接冲突报错。	exclude = ('password',)
fields	tuple	设置编辑页面中需要显示的字段，可包括 readonly 字段，如果需要在同一行显示多个字段，可用子 tuple 包含之。	fields = (('url','title'),'content',)
fieldsets	tuple	fields 的加强版， 可实现分组、样式和字段说明。有 fields、classes、description 三个字段。	fieldsets = ( 　　(None,{'fields':('url','title',)}), 　　('更多选项',{'classes':('collapse','wide',),'fields':('gold','jewel',)}), )
filter_horizontal	tuple	用于显示 ManyToManyField 字段，暂略
filter_vertical	tuple	同上， 垂直显示，暂略
form	class	自定义表单，赋值为 forms.ModelForm 的子类类名	form = UserForm
formfield_overrides	dict	自定义窗口部件，覆盖默认控件	formfield_overrides = {{models.TextField:{'widget':MyTextFieldWidget},}
inlines	list	内联数据，外键关联的数据，暂略
list_display	tuple	对象列表中依次显示的字段。元素可以是字段名<str格式>、带有一个model参数的函数调用、 ModelAdmin 内的一个属性名(函数)<str格式>，Model 内的一个属性名(函数)<str格式>。如果字段是外键，则显示关联对象的 __unicode__()，ManyToMany 字段不支持，如果字段是 bool 类型则会显示一个好看的图标代替文字显示，Django默认转义html输出，如果需要添加html样式，则可使用 format_html() 来返回内容，并设置字段的 allow_tags = True。 当使用函数时，对象列表中默认以此字段的可排序功能当失效，可以设定该字段的 admin_order_field = 'fieldname' 来指定可排序的规则。 也可以使用 property() 函数，如右边所示。	def color_nickname(self, obj): 　　return format_html('<font color=red>%s</font>' %nickname) color_nickname.allow_tags = True color_nickname.admin_order_field = 'nickname' list_display = ('id','color_nickname',) #new_name = property(color_nickname) #list_display = ('id','new_name',)
list_display_links	tuple	设置对象列表中，哪些字段可以链接进编辑页面（设置的字段必须位于 list_display 中），默认只有第一个字段有此链接。	list_display = ('id','nickname','age',) list_display_links = ('id','nickname',)
list_editable	tuple	设置在对象列表中即可修改的字段（设置的字段必须位于 list_display 中，且不与 list_display_links k中字段重复），如果设置此属性，则对象列表下方会出现一个保存按钮。	list_editable = ('nickname','age',)
list_filter	tuple	对象列表右侧的筛选器。元素可以是字段名、继承 django.contrib.admin.SimpleListFilter 的子类、第一个元素是字段名第二个元素是继承 django.contrib.admin.FieldListFilter 的子类。 可以在 SimpleListFilter 的子类中定义 template = ’my.html' 来重载默认的筛选器模板，默认筛选器模板为 admin/filter.html。 关于筛选器更多内容，请参照相关章节。	class validListFilter(SimpleListFilter): 　　title = ('用户状态') 　　parameter_name = 'valid' 　　def lookups(self, request, model_admin): 　　　　return ( 　　　　　　('1','允许登陆',), 　　　　　　('2','禁止登陆',), 　　　　) 　　def queryset(self, request, queryset): 　　　　if self.value() == '1': 　　　　　　return queryset.filter(valid__gte = 1) 　　　　if self.value() == '2': 　　　　　　return queryset.filter(valid__lte = 0) list_filter = ('valid',validListFilter,)
list_max_show_all	int	对象列表下方，当总量小于等于多少时出现 "显示所有" 的选项。默认为 200.	list_max_show_all = 100
list_per_page	int	对象列表分页的 pagesize，默认为 100	list_per_page = 30
list_select_related	tuple	告知 django 使用 select_related() 从数据库中查询关联表数据，暂略
ordering	tuple	指定对象列表依次以哪些字段进行排序，字段前加上 - 表示逆排序。 如果需要动态指定排序规则，如当不同用户浏览时，排序规则不同，则可以重载 get_ordering()。	ordering = ('-id','nickname',)
paginator		分页相关，暂略
prepopulated_fields	dict	设定预填充字段，不支持 DateTimeField、ForeignKey、ManyToManyField ，暂略
preserve_filters	bool	在筛选条件下，进行编辑、删除某一个对象后返回到对象列表界面，是否还是该筛选器状态。默认为 True，表示仍然是该筛选器状态，否则显示为所有筛选器都重置的所有对象。	preserve_filters = False
radio_fileds	dict	将原复选框改为单选框模式进行显示。 model 中该字段应拥有 choices 属性值。	models.py: VALID_CHOICES = ((1,'是'),(0,'否'),) valid = models.IntegerField(choices=VALID_CHOICDES,default=1) admin.py: radio_fields={"valid":admin.VERTICAL}
raw_id_fields	tuple	与 ForeignKey 和 ManyToManyField 相关，暂略。
readonly_fields	tuple	在编辑页面中显示，但不能编辑的字段。如果设置的字段不在 fields 和 fieldsets 中，则将被添加到这些可编辑的字段之后显示。 类似于 list_display ，也可以设置元素为一个方法名<str格式>	readonly_fields = ('nickname','password',)
save_as	bool	若为真，显示'保存为新的'按钮，若为假，显示'保存新增加一个新的',默认为 False	save_as = True
save_on_top	bool	保存按钮是否在上方，默认为 False	save_on_top = True
save_on_bottom	bool	保存按钮是否在下方，默认为 True	save_on_bottom = False
search_fileds	list	对象列表上方的搜索框查找的字段，^ 表示以某某开头，= 表示精确匹配 如果需要定制搜索条件，还可以重载 get_search_results() 函数	search_fields = ['^nickname',=email]
add_form_template	str	重载此字段的值，可重载模板文件，相应的view为 add_view()
change_form_template	str	同上，change_view()
change_list_template	str	同上，changelist_view()
delete_confirmation_template	str	同上，delete_view()
delete_selected_confirmation_template	str	同上，
object_history_template	str	同上，history_view()

ModelAdmin methods

save_model

Custom validation

自定义编辑表单的字段验证，首先要实现一个继承 forms.ModelForm 的子类，在此子类里重写各个字段的验证规则，然后在 ModelAdmin 中设置 form 为此子类，如：

class PUserAdminForm(forms.ModelForm):
    def clean_gold(self):
        gold = self.cleaned_data['gold']
        logging.warning('gold:%s'%gold)
        if gold < 0:
            raise forms.ValidationError("金币不能是负数!")
        return gold

form = PUserAdminForm