HTTPS SSH

Table of Contents generated with DocToc

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Introduction

The presented module contains django application to display two dimensional arrays data via various presentation media, typically it would be django-ORM query presented in HTML view, but implementations of both data source and final output could vary.

One might ask - why we implemented it, when most of those things could be done via customized django.contrib.admin models or via django-tables2.

We've used both approaches. We liked django.contrib.admin approach at the beginning, but its main concept is built over simple CRUD operations, and django-admin lacking row-level permission system.

Django-tables2 approach is better, but it does not provide any way to build queries (while you could use django-filter) and generally it is less extensible then pluggable system we provided.

Moreover, ua2.table3 is not related to Django itself - it can be used with any framework. Some plugins would rely on Django ORM calls, but you can easily override those with the different calls special for your situation.

So, treat this module as a alternative to django-tables2, which main advantage is pluggable architecture which allows easy extension of differnet layouts and transformations.

Quickstart

Install the module

pip install -r ua2.table3a

Define some table

This example defines the table for django.contrib.auth.User

class UsersTable(table3.Table):
    """
    Display users table with searchable username, email
    and category filter on user role.
    """
    user_name = table3.LabelColumn(_('User name'), 'username', sortable=True)
    email = table3.LabelColumn(_('Email'), 'email', sortable=True)
    last_login = table3.LabelColumn(_('Last Login'), 'last_login', sortable=True)

    class Meta:
        plugins = [
            table3.plugins.CategoryFilter(
                (('admins', 'Administrators'),
                 ('staff', 'Staff'),
                 ('all', 'all')),
                default='all'
            ),
            table3.plugins.QuickSearchORM(('username', 'email')),
            table3.plugins.SingleSortPlugin,
            table3.plugins.PaginatorPlugin,
            table3.plugins.DjangoTemplatePlugin,
        ]

    def category_filter(self, category):
        """
        Category filter ORM queries. Default data for 'all'
        """
        if category == 'admins':
            self.data = self.data.filter(is_superuser=True)
        if category == 'students':
            self.data = self.data.filter(roles__in=LmsRole.objects.filter(is_student=True))

And next is the view code itself:

@login_required
def users(request):
    table = UsersTable('users_table', request.session, User.objects.all())
    table.process_request(request)
    return render(request, 'web/users.html', {'table': table})

Documentation

Field types

LabelColumn

Simple labelled column. Arguments:

  • label - text label of column
  • refname - python getattr() notation to refer to field content
  • sortable - False by default, is field sortable or not
  • order<sub>by</sub> - which attribute to use to sort on. By default it will sort on refname
  • header<sub>style</sub> - css style for header
  • header<sub>attrs</sub> - additional attributes for header
  • cell<sub>attrs</sub> - attributes for cell rendering
  • default<sub>value</sub>

DateTimeColumn

Same as LabelColumn but renders DateTime values.

HrefColumn

Additional arguments:

  • reverse - view to reverse
  • reverse<sub>args</sub> - arguments to reverse function

TemplateColumn

Additional arguments:

  • template - template file

This column will render its content using template file. The template context obtains the following data:

  • table - table instance
  • record or row - current record

CheckboxColumn

Will render the field as checkbox. The name of checkbox will be the field name, and content - the content read from record.

MoneyColumn

Additional arguments:

  • positive<sub>format</sub> '%s'
  • negative<sub>format</sub> '-%s
  • decimal<sub>pos</sub> 2
  • force<sub>grouping</sub> True
  • empty<sub>value</sub> ''

Plugins

SingleSortPlugin

If this plugin is enabled, then sorting functionality is enabled for view: all fields which has 'sortable' defined as True will be clickable in table UI, each click should change sorting order by this field.

QuickSearchORM

QuickSearch field on top of table.

PaginatorPlugin

Pagination. The amount of rows per page could be overriden via django settings variable TABLE<sub>ROWPERPAGE</sub>.

DjangoTemplatePlugin

Plugin for data output, this one via Django template. You can take this as example and write your own output plugins