Xadmin plugins

plugins overview

built-in plugins

Action

functions

Action plugin provides data selection function on the data list page. The selected data can be processed specially after Action. The batch deletion function is provided as default Action.

screenshot

_images/action.png

use

To enable the Action, the developer can set the attribute ‘actions’ of Model OptionClass which is a list type. In default, the xadmin has enabled DeleteSelectedAction which gives you an option to delete selected items from the list view. You can also implement your customized Action class, and please see the following example.

  • There needs an Action class first, which subclasses BaseActionView. BaseActionView is a subclass of ModelAdminView:

    from xadmin.plugins.actions import BaseActionView
    
    class 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 是包含了已经选择的数据的 queryset
            for obj in queryset:
                # obj 的操作
                ...
            # 返回 HttpResponse
            return HttpResponse(...)
    
  • then apply this Action:: on OptionClass in Model

    class MyModelAdmin(object):
    
        actions = [MyAction, ]
    
  • then you have completed your Action

API

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

data filters

functions

The list view provides data filtering function and you can search the data by fuzzy searching, numerical range, date range, etc.

screenshot

_images/filter.png

use

In Model OptionClass, set up the following attributes:

  • list_filter property

    This property can specify the name of column can be filtered, and then the system will generate a searcher automatically

  • search_fields property

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

  • free_query_filter property

    True by default, specifying whether free search is allowed or not. If free search is on, users can perform customized search by passing the argument url. For exampe:

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

Samples that use filters:

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

version

temporarily unaccessible

create filters

You can create your own filters to peform some specific filtering. The filters need to subclass :class: xadmin.filters.BaseFilter. Use :attr: xadmin.filters.manager to register the filters.

chart plugin

functions

The data chart can be generated from the data listed in the list view page. You can specify a number of data columns to generate more charts.

screenshot

_images/chart.png

use

Set the data_charts property of Model OptionClass a dict. The key is the name of the chart and the value is the specific setting properties. Usage examples:

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',)}
    }

The main properties of the chart are:

title: display name of the chart

The ‘x-field’ property represents the data for x axis in the chart, normally it is date or time.

The ‘y-field’ is the y-axis of the data charts, which is a list containing data fields. If the ‘y-field’ list contains more than one field, all these data will be displayed in one chart.

order: sorting information, if it is not provided, the order of the data list will be used

version

temporarily unaccessible

API

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

Bookmarks

functions

It records the results of special processing such as data filtering and ordering. The added bookmarks also can be added as small widget from the dashboard of the Index page.

screenshot

_images/bookmark.png

use

set the following properties in Model OptionClass:

  • show_bookmarks property:

    set the bookmarks function on or not, True by default

  • list_bookmarks property

    Set default bookmarks. Users can add their own bookmarks on the list page. You can also provide some bookmarks in advance. Usage examples:

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

version

temporarily unaccessible

Data exporting

functions

This plugin provides data exporting function on the data list page. Data can be exported in format Excel, CSV, XML or json.

screenshot

_images/export.png

use

Note

To export the data in Excel format, install xlwt <http://pypi.python.org/pypi/xlwt> first.

In default, the xadmin can export the data file as Excel, CSV, XML and JSON format. The supported export file format can be set by the property ‘list_export’ of OptionClass, which has values xls, cvs, xml and json. Or you can set None to the list_export to disable data export function.

class MyModelAdmin(object):

    list_export = ('xls', xml', 'json')

Refresh the list at given intervals.

functions

This plugin provides refresh function, which is very useful to check a real-time data from a list view page.

screenshot

_images/refresh.png

use

To enable the refresh function plugin, just simply set up the ‘refresh_times’ property of OptionClass. The ‘refresh_times’ is a list containing the interval. In default, this plugin is inactive. Please see the following example:

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

Display data details

functions

This plugin uses Ajax to show the details of the relevant fields in the list view page.

screenshot

_images/details.png

use

To use this plugin, you can set up the properties ‘show_detail_fields’ and ‘show_all_rel_details’ in OptionClass. The property ‘show_detail_fields’ specifies the fields shown in details, and all related fields will shown in details when ‘show_all_rel_details’ is set as True (default setting). Please check the following example:

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

instant data edit

functions

Ajax is used by this plugin to modify the value of some field instantly. There is no need for submitting or page refreshing to complete the data modification. It is quiet useful when it comes to some frequently modified field, (for example, state).

screenshot

_images/editable.png

use

This plugin can set by the ‘list_editable’ property of OptionClass. The ‘list_editable’ is a tuple used to specify the editable fields in the list view page.

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