Xadmin文档

快速开始 Xadmin

For using Xadmin, Django 1.4 needs to be installed and an Admin Site has to be activated.

安装

使用 pip:

pip install django-xadmin

源码安装

到 https://github.com/sshwsfc/django-xadmin 下载最新的源码包或是 clone git 库, 然后在项目目录下执行:

pip install -r requirements.txt

注解

在执行前您可以先编辑文件 requirements.txt , 其中 xlwt 不是必选的, 如果您不需要导出 excel 的功能, 可以删除这项

运行 Demo

如果您下载的是 Xadmin 的源码包, 您会在项目目录下找到 demo_app 目录, 执行一下命令可以迅速开启一个 Xadmin 的演示实例:

cd demo_app
python manage.py runserver

打开浏览器, 输入 http://127.0.0.1:8000 看一下效果吧.

使用在自己的项目中

Xadmin 作为 Django 的模块, 可以很方便的使用在 Django 的网站中.

首先编辑 settings.py 添加 Xadmin 的模块到 INSTALLED_APPS 中 (注意, 安装 Django admin 所需要的 APP 也要安装, 但是 django.admin 可以不安装):

INSTALLED_APPS = (...'xadmin','crispy_forms','reversion',...
)

然后添加 URL-patterns 以及 autodiscover 操作:

import xadminxadmin.autodiscover()# version模块自动注册需要版本控制的 Modelfrom xadmin.plugins import xversionxversion.registe_models()urlpatterns = patterns('',url(r'xadmin/', include(xadmin.site.urls)),)

收集 media 文件:

[python] view plain copy

1. python manage.py collectstatic

Xadmin 的插件

插件概述

内置插件

Action

功能

Action 插件在数据列表页面提供了数据选择功能, 选择后的数据可以经过 Action 做特殊的处理. 默认提供的 Action 为批量删除功能.

截图

使用

开发者可以设置 Model OptionClass 的 actions 属性, 该属性是一个列表, 包含您想启用的 Action 的类. 系统已经默认内置了删除数据的 Action,当然您可以自己制作 Action 来实现特定的功能, 制作 Action 的实例如下.

• 首先要创建一个 Action 类, 该类需要继承 BaseActionView. BaseActionView 是 ModelAdminView 的子类:

  from xadmin.plugins.actions import BaseActionViewclass MyAction(BaseActionView):# 这里需要填写三个属性action_name = "my_action"    #: 相当于这个 Action 的唯一标示, 尽量用比较针对性的名字description = _(u'Test selected %(verbose_name_plural)s') #: 描述, 出现在 Action 菜单中, 可以使用 ``%(verbose_name_plural)s`` 代替 Model 的名字.model_perm = 'change'    #: 该 Action 所需权限# 而后实现 do_action 方法def do_action(self, queryset):# queryset 是包含了已经选择的数据的 querysetfor obj in queryset:# obj 的操作...# 返回 HttpResponsereturn HttpResponse(...)

• 然后在 Model 的 OptionClass 中使用这个 Action:

  class MyModelAdmin(object):actions = [MyAction, ]

• 这样就完成了自己的 Action

API

• class xadmin.plugins.actions.ActionPlugin(admin_view)[source]

数据过滤器

功能

在数据列表页面提供数据过滤功能, 包括: 模糊搜索, 数字范围搜索, 日期搜索等等

截图

使用

在 Model OptionClass 中设置以下属性:

• list_filter 属性:

  该属性指定可以过滤的列的名字, 系统会自动生成搜索器

• search_fields 属性:

  属性指定可以通过搜索框搜索的数据列的名字, 搜索框搜索使用的是模糊查找的方式, 一般用来搜素名字等字符串字段

• free_query_filter 属性:

  默认为 True , 指定是否可以自由搜索. 如果开启自有搜索, 用户可以通过 url 参数来进行特定的搜索, 例如:

  http://xxx.com/xadmin/auth/user/?name__contains=tony

使用过滤器的例子:

class UserAdmin(object):list_filter = ('is_staff', 'is_superuser', 'is_active')search_fields = ('username', 'first_name', 'last_name', 'email')

版本

暂无

制作过滤器

您也可以制作自己的过滤器, 用来进行一些特定的过滤. 过滤器需要继承 xadmin.filters.BaseFilter 类, 并使用xadmin.filters.manager 注册过滤器.

图表插件

功能

在数据列表页面, 跟列表数据生成图表. 可以指定多个数据列, 生成多个图表.

截图

使用

在 Model OptionClass 中设定 data_charts 属性, 该属性为 dict 类型, key 是图表的标示名称, value 是图表的具体设置属性. 使用示例:

class RecordAdmin(object):data_charts = {"user_count": {'title': u"User Report", "x-field": "date", "y-field": ("user_count", "view_count"), "order": ('date',)},"avg_count": {'title': u"Avg Report", "x-field": "date", "y-field": ('avg_count',), "order": ('date',)}}

图表的主要属性为:

title : 图表的显示名称

x-field : 图表的 X 轴数据列, 一般是日期, 时间等

y-field : 图表的 Y 轴数据列, 该项是一个 list, 可以同时设定多个列, 这样多个列的数据会在同一个图表中显示

order : 排序信息, 如果不写则使用数据列表的排序

版本

暂无

API

• class xadmin.plugins.chart.ChartsPlugin(admin_view)[source]

• class xadmin.plugins.chart.ChartsView(request, *args, **kwargs)[source]

书签

功能

记录数据列表页面特定的数据过滤, 排序等结果. 添加的书签还可以在首页仪表盘中作为小组件添加

截图

使用

在 Model OptionClass 中设定如下属性:

• show_bookmarks 属性:

  设置是否开启书签功能, 默认为 True

• list_bookmarks 属性:

  设置默认的书签. 用户可以在列表页面添加自己的书签, 你也可以实现设定好一些书签, 使用实例如下:

  class UserAdmin(object):list_bookmarks = [{'title': "Female",         # 书签的名称, 显示在书签菜单中'query': {'gender': True}, # 过滤参数, 是标准的 queryset 过滤'order': ('-age'),         # 排序参数'cols': ('first_name', 'age', 'phones'),  # 显示的列'search': 'Tom'    # 搜索参数, 指定搜索的内容}, {...}]

版本

暂无

数据导出

功能

该插件在数据列表页面提供了数据导出功能, 可以导出 Excel, CSV, XML, json 格式.

截图

使用

注解

如果想要导出 Excel 数据, 需要安装 xlwt.

默认情况下, xadmin 会提供 Excel, CSV, XML, json 四种格式的数据导出. 您可以通过设置 OptionClass 的 list_export属性来指定使用哪些导出格式 (四种各使用分别用 xls, csv, xml, json 表示), 或是将 list_export 设置为 None 来禁用数据导出功能. 示例如下:

class MyModelAdmin(object):list_export = ('xls', xml', 'json')

列表定时刷新

功能

该插件在数据列表页面提供了定时刷新功能, 对于需要实时刷新列表页面查看即时数据的情况非常有用.

截图

使用

使用数据刷新插件非常简单, 设置 OptionClass 的 refresh_times 属性即可. refresh_times 属性是存有刷新时间的数组. xadmin 默认不开启该插件.示例如下:

class MyModelAdmin(object):# 这会显示一个下拉列表, 用户可以选择3秒或5秒刷新一次页面.refresh_times = (3, 5)

显示数据详情

功能

该插件可以在列表页中显示相关字段的详细信息, 使用 Ajax 在列表页中显示.

截图

使用

使用该插件主要设置 OptionClass 的 show_detail_fields, show_all_rel_details 两个属性. show_detail_fields属性设置哪些字段要显示详细信息, show_all_rel_details 属性设置时候自动显示所有关联字段的详细信息, 该属性默认为 True. 示例如下:

class MyModelAdmin(object):show_detail_fields = ['group', 'father', ...]

数据即时编辑

功能

该插件可以在列表页中即时编辑某字段的值, 使用 Ajax 技术, 无需提交或刷新页面即可完成数据的修改, 对于需要频繁修改的字段(如: 状态)相当有用.

截图

使用

使用该插件主要设置 OptionClass 的 list_editable 属性. list_editable 属性设置哪些字段需要即时修改功能. 示例如下:

class MyModelAdmin(object):list_editable = ['price', 'status', ...]

Xadmin 插件制作

插件原理

Xadmin 的插件系统架构设计一定程度上借鉴了 wordpress 的设计。 想要了解 Xadmin 的插件系统架构首先需要了解 Xadmin AdminView 的概念。简单来说，就是 Xadmin 系统中每一个页面都是一个 AdminView 对象返回的HttpResponse 结果。|xadmin| 的插件系统做的事情其实就是在 AdminView运行过程中改变其执行的逻辑， 或是改变其返回的结果，起到修改或增强原有功能的效果。下面让我们看看整个插件从制作完成到实际运行的整个过程。

首先需要创建自己的插件类， 插件类继承 BaseAdminPlugin

class HelloWorldPlugin(BaseAdminPlugin):...

开发好的插件首先要注册到 Xadmin 中， 示例代码如下:

# ListAdminView 是 Model 列表页面xadmin.site.register_plugin(HelloWorldPlugin, ListAdminView)

其中插件的注册和使用可以参看 xadmin.sites.AdminSite.register_plugin()

当将插件注册到 Xadmin 后， Xadmin 在创建 AdminView 实例的时候会将该插件放入实例的 plugins 属性。当AdminView 在处理请求时，会首先逐个调用 plugins 中插件的 init_request() 方法，插件在该方法中一般进行初始化的操作并且返回一个 Boolean 值告诉 AdminView是否需要加载该插件。当 init_request() 方法返回值为 False时， AdminView 不会加载该插件。实例如下:

class HelloWorldPlugin(BaseAdminPlugin):say_hello = False# 初始化方法根据 ``say_hello`` 属性值返回def init_request(self, *args, **kwargs):return bool(self.say_hello)

在以上实例中，插件根据自身的 say_hello 属性来决定是否让自己被加载。您可能会迷惑， say_hello 属性看起来一直会是 False 呀，那样这个插件不是永远不会被加载？其实 Xadmin 在创建插件实例的时候会将 OptionClass 的同名属性替换插件的属性。这样，在不同的 OptionClass 下会有不同的插件结果，实例如下:

class SomeModelAdmin(object):say_hello = True...site.register(SomeModel, SomeModelAdmin)

理解以上内容后，让我们再看看插件具体是如何起作用的。在 AdminView 的执行过程中，可以被插件截获或修改的方法使用 filter_hook() 装饰，实例如下:

class ListAdminView(ModelAdminView):# 可以被插件截获或修改的方法使用该装饰器装饰@filter_hookdef get_context(self):...

使用 filter_hook() 装饰的方法执行过程中会根据一定原则执行插件中的同名方法，具体信息查考该装饰器的文档内容。

• xadmin.views.base.filter_hook(func)[source]

• 表明 AdminView 的方法可以被插件插入的装饰器。执行使用了该装饰器的方法时，会按照以下过程执行:

  • 如果插件方法没有参数，AdminView 方法的返回结果不为空则抛出异常

  • 如果插件方法的第一个参数为 __ ，则 AdminView 方法将作为第一个参数传入，注意，这时还未执行该方法，在插件中可以通过 __() 执行，这样就可以实现插件在 AdminView 方法执行前实现一些自己的逻辑，例如:

    def get_context(self, __):c = {'key': 'value'}c.update(__())return c

  • 如果插件方法的第一个参数不为 __ ，则执行 AdminView 方法，将结果作为第一个参数传入

  1. 首先将实例的 plugins 属性取出，取出含有同样方法名的插件

  2. 按照插件方法的 priority 属性排序

  3. 顺序执行插件方法，执行插件方法的规则:

  4. 最终将插件顺序执行的结果返回

根据该装饰器的执行原则，如果我们想修改上面示例中 ListAdminView 的 get_context 的返回值，可以在插件中实现如下代码:

class HelloWorldPlugin(BaseAdminPlugin):# 在插件中加入同名方法，修改 ``ListAdminView`` 的 ``get_context`` 返回的值def get_context(self, context):context.update({'hello_target': 'World!!'})return context

如果我们希望插件在 AdminView 的方法前执行，或是完全使用自己的方法替代 AdminView 的方法可以这样:

class HelloWorldPlugin(BaseAdminPlugin):# 第一个参数为 ``__`` 。这样 ``__`` 即为 ``ListAdminView`` 的 ``get_context`` 方法本身，注意，这时还没有执行这个方法。def get_context(self, __):context = {'hello_target': 'World!!'}#我们可以在任何时候执行 ``AdminView`` 的方法，或是根本不执行context.update(__())return context

至此，加入的插件就实现了对 AdminView 方法的完全控制。

模板插件

我们知道，Django 中一个完整的 View 是包含模板的，模板用来生成 View 最终返回的 HTML 内容。当然，插件也可以在模板中插入自己的内容。我们来看看具体如何实现。

首先让我们来看看 Xadmin 中的模板代码示例片段 (change_list.html):

{% load xadmin %}
...
<form id="changelist-form" action="" method="post"{% view_block 'result_list_form' %}>{% csrf_token %}{% view_block 'results_top' %}<div class="results">{% if results %}...

其中的 view_block Tag 即为插件的 插入点 。插件可以在自己的插件类中使用 block_ + 插入点名称 方法将 HTML 片段插入到页面的这个位置，示例如下:

class HelloWorldPlugin(BaseAdminPlugin):# context 即为 TemplateContext， nodes 参数包含了其他插件的返回内容。# 您可以直接返回 HTML 片段，或是将内容加入到 nodes 参数中def block_results_top(self, context, nodes):return s"<div class='info'>Hello %s</div>" % context['hello_target']

插件实例

下面让我们来看一个 Xadmin 中完整的插件实例:

from django.template import loaderfrom xadmin.sites import sitefrom xadmin.views import BaseAdminPlugin, ListAdminViewREFRESH_VAR = '_refresh'# 该插件实现了一个列表页面刷新器的效果class RefreshPlugin(BaseAdminPlugin):# 用户可以定制刷新的频率，可以传入多个值。该属性会被 ``OptionClass`` 的同名属性替换refresh_times = []def init_request(self, *args, **kwargs):# 根据用户是否制定了刷新器来决定是否启动该插件return bool(self.refresh_times)# 插件拦截了返回 Media 的方法，加入自己需要的 js 文件。def get_media(self, media):if self.request.GET.get(REFRESH_VAR):# 放页面处于自动刷新状态时，加入自己的 js 制定刷新逻辑media.add_js([self.static('xadmin/js/refresh.js')])return media# Block Views# 在页面中插入 HTML 片段，显示刷新选项。def block_top_toolbar(self, context, nodes):current_refresh = self.request.GET.get(REFRESH_VAR)context.update({'has_refresh': bool(current_refresh),'clean_refresh_url': self.admin_view.get_query_string(remove=(REFRESH_VAR,)),'current_refresh': current_refresh,'refresh_times': [{'time': r,'url': self.admin_view.get_query_string({REFRESH_VAR: r}),'selected': str(r) == current_refresh,} for r in self.refresh_times],})# 可以将 HTML 片段加入 nodes 参数中nodes.append(loader.render_to_string('xadmin/blocks/refresh.html', context_instance=context))# 注册插件site.register_plugin(RefreshPlugin, ListAdminView)

最后不要忘记在适当的地方加载该代码， 让其执行。一般情况下，你可以将其写到 adminx.py 文件中，这样，只要您的 APP 加入到 Django Settings 的 INSTALL_APPS 中，Xadmin 就会自动执行 app 下的 adminx.py 文件。

插件开发

了解了插件的运行原理后我们就可以开发自己的插件了。首先我们需要了解插件类中的实用方法。因为插件是继承BaseAdminPlugin 类，而该类继承自:class:`~xadmin.views.BaseAdminObject`，所以这两个类的方法都可以在插件中使用。

Xadmin 在创建插件时会自动注入以下属性到插件实例中:

• request : Http Request

• user : 当前 User 对象

• args : View 方法的 args 参数

• kwargs : View 方法的 kwargs 参数

• admin_view : AdminView 实例

• admin_site : Xadmin 的 admin_site 对象实例

如果 AdminView 是 ModelAdminView 的子类，还会自动注入以下属性:

• model : Model 对象

• opts : Model 的 _meta 属性

接下来您应该考虑打算制作什么功能的插件了。不同功能的插件额能需要注册到不同的 AdminView 上，|xadmin| 系统中主要的 AdminView 有:

• BaseAdminView : 所有 AdminView 的基础类，注册在该 View 上的插件可以影响所有的 AdminView

• CommAdminView : 用户已经登陆后显示的 View，也是所有登陆后 View 的基础类。该 View主要作用是创建了 Xadmin 的通用元素，例如：系统菜单，用户信息等。插件可以通过注册该 View 来修改这些信息。

• ModelAdminView : 基于 Model 的 AdminView 的基础类，注册的插件可以影响所有基于 Model 的 View。

• ListAdminView : Model 列表页面 View。

• ModelFormAdminView : Model 编辑页面 View。

• CreateAdminView : Model 创建页面 View。

• UpdateAdminView : Model 修改页面 View。

• DeleteAdminView : Model 删除页面 View。

• DetailAdminView : Model 详情页面 View。

选择好目标 AdminView 后就要在自己的插件中编写方法来修改或增强这些 AdminView 。其中每个 AdminView 可以拦截的方法及其介绍请参看各 AdminView 的文档。

插件规范

文档模板:

"""Name======作者----该插件的作者信息功能----描述插件的主要功能截图----.. image:: /images/plugins/action.png使用----描述插件的使用方法,  以及使用示例.版本----描述插件的版本信息API---.. autoclass:: XXX"""

AdminSite

• class xadmin.sites.AdminSite(name='admin', app_name='admin')[source]

• xadmin最核心的类，管理整个xadmin站点的所有注册内容。

  一般一个管理站点只有一个 AdminSite 实例，该实例主要完成以下工作:

  其中，xadmin 需要的信息包括以下信息：

  • urls[source]

  • 返回 xadmin site 的urls，用于设置django的urls。该方法用于属性使用。在您的Django的 urls.py 中，使用示例如下:

    from django.conf.urls import patterns, include, urlimport xadminxadmin.autodiscover()urlpatterns = patterns('',url(r'', include(xadmin.site.urls)),)

  • unregister(model_or_iterable)[source]

  • 取消 Model 或 OptionClass 的注册

    如果 Model 或 OptionClass 并未注册过，会抛出 xadmin.sites.NotRegistered 异常

  • restore_registry(data)[source]

  • 恢复当前 AdminSite 实例的信息

  • path – view对应的url路径

  • admin_view_class – 注册的 Admin View 类

  • name – view对应的url name

  • register_view(path, admin_view_class, name)[source]

  • 将 Admin View 类注册到 AdminSite，一般用于创建独立的 admin 页面，例如登陆，介绍页面，帮助页面等。

    参数:

    关于 Admin View 具体内容可以参看 :class:`~xadmin.views.base.BaseAdminView`。 举例:

    from xadmin.views import BaseAdminViewclass TestAdminView(BaseAdminView):def get(self, request):passsite.register_view(r'test_view/$', TestModelAdminView, name='for_test')

    注册后，用户可以通过访问 /test_view/ 访问到该view

  • plugin_class – view对应的url路径

  • admin_view_class – 该 plugin 绑定的 Admin View 类

  • register_plugin(plugin_class, admin_view_class)[source]

  • 将 Plugin 类注册到 AdminSite，当任何 Admin View 运行时当前 view 绑定的 plugin 会生效。

    参数:

    关于 Admin Plugin 具体内容可以参看 :class:`~xadmin.views.base.BaseAdminPlugin`。 举例:

    from xadmin.views import BaseAdminPluginclass TestAdminPlugin(BaseAdminPlugin):def get_context(self, context):context['test'] = Truereturn contextsite.register_plugin(TestAdminPlugin, SomeAdminView)

    注册后，只要运行 SomeAdminView 实例的 get_context 方法，就会调用该 plugin。

  • path – view对应的url路径

  • admin_view_class – 注册的 Model Base Admin View 类

  • name – view对应的url name, 要包含两个%%s, 分别会替换为 app_label和module_name

  • register_modelview(path, admin_view_class, name)[source]

  • 将 Model Base Admin View 类注册到 AdminSite，

    参数:

    注册 Model Base Admin View 可以为每一个在xadmin注册的 Model 生成一个 Admin View，并且包含相关的 Model 信息。具体内容可以参看 :class:`~xadmin.views.base.ModelAdminView`。 举例:

    from xadmin.views import ModelAdminViewclass TestModelAdminView(ModelAdminView):def get(self, request, obj_id):passsite.register_modelview(r'^(.+)/test/$', TestModelAdminView, name='%s_%s_test')

    注册后，用户可以通过访问 /%(app_label)s/%(module_name)s/123/test 访问到该view

  • model_or_iterable – 传入 model 或是指定的 ModelOptionClass

  • admin_class – 当 model_or_iterable 为 Model 时，该参数为 ModelAdmin；model_or_iterable 为 AdminView 时 ，该参数为 OptionClass

  • register(model_or_iterable, admin_class=<type 'object'>, **options)[source]

  • 注册需要管理的 Model， 或是注册某 AdminView 的 OptionClass

    参数:

    关于 Admin Plugin 具体内容可以参看 :class:`~xadmin.views.base.BaseAdminPlugin`。 举例:

    from models import SomeModelclass SomeModelAdmin(object):passsite.register(SomeModel, SomeModelAdmin)

  • has_permission(request)[source]

  • 如果返回为 True 则说明 request.user 至少能够访问当前xadmin网站。否则无法访问xadmin的任何页面。

  • get_view_class(view_class, option_class=None, **opts)[source]

  • xadmin中 最核心 的方法，用于创建 xadmin 特有的 AdminViewClass。

    创建 AdminView 和核心思想为动态生成 mix 的类，主要步骤有两步:

  • get_plugins(admin_view_class, *option_classes)[source]

  • xadmin中 核心 方法，用于获取 AdminViewClass 的 plugins。

    获取 plugins 首先根据该 AdminViewClass 及其所有的集成类在已经注册的插件中找到相应的插件类。然后再使用第二个参数的 OptionClass 拼成插件类。

  • admin_view_class – AdminView 类，该类应该为 ModelAdminView 的子类

  • model – Model 类，目前该参数暂无作用

  • option_class – Model 的 OptionClass，保存对该 Model 的相关定制

  • create_model_admin_view(admin_view_class, model, option_class)[source]

  • 使用 get_view_class() 创建 ModelAdminView 类，并且返回 view 方法，可以用于 get_urls 方法中

    参数:

  • create_admin_view(admin_view_class)[source]

  • 使用 get_view_class() 创建 AdminView 类，并且返回 view 方法，可以用于 get_urls 方法中

    参数:	admin_view_class – AdminView 类

  • copy_registry()[source]

  • 复制当前 AdminSite 实例的信息

  • check_dependencies()[source]

  • 检查运行xadmin需要的包是否已经正确安装

    默认情况下会检查 ContentType 模块是否已经正确安装

  • admin_view(view, cacheable=False)[source]

  • 为当前 AdminSite 的所有 View 提供的 Decorator。主要是功能是使用 AdminSite.has_permission() 方法来判断当前用户是否有权限访问该 ``AdminSite``， 如果没有，转到登陆页面

    通常情况下会在 AdminSite.get_urls() 方法中使用该方法

    参数:	cacheable – 默认情况下，所有的 AdminView 会通过 never_cache 标记成不做缓存，如果确实需要缓存，可以设置 cacheable=True

  • 需要 xadmin 管理的 models，以及各 model 的 admin 信息

  • 注册的 admin view class

  • 注册的 model admin view class

  • 注册的各种插件

  • 注册管理所有 xadmin 需要的信息

  • 创建 admin view class

  • 注册 django urls

  1. 使用已经注册的 OptionClass (见 register()) 以及参数传入的 option_class 与 view_class 动态生成类

  2. 根据 view_class 及其继承类找到相应的 plugins， 作为生成的 AdminViewClass 的 plugins 属性

• exception xadmin.sites.AlreadyRegistered[source]

• 如果一个 model 已经在 AdminSite 注册过，当尝试再次注册时会抛出这个异常。

• class xadmin.sites.MergeAdminMetaclass[source]

• 用来生成 admin view class 的原类。

  目前该原类没有做什么特殊的工作。接下来的版本该原类可能会给 admin view class 注入一些公共的属性。

• exception xadmin.sites.NotRegistered[source]

• 当一个model并未在 AdminSite 注册，当调用 AdminSite.unregister() 想要取消该model的注册就会抛出该异常。