README.rst

   1 ================================================
   2 django-tables2 - An app for creating HTML tables
   3 ================================================
   4
   5 .. note::
   6
   7     Prior to v0.6.0 this package was a fork of miracle2k's and both were known
   8     as *django-tables*. This caused some problems (e.g. ambiguity and inability
   9     to put this library on PyPI) so as of v0.6.0 this package is known as
  10     *django-tables2*.
  11
  12 django-tables2 simplifies the task of turning sets of data into HTML tables. It
  13 has native support for pagination and sorting. It does for HTML tables what
  14 ``django.forms`` does for HTML forms.
  15
  16 Its features include:
  17
  18 - Any iterable can be a data-source, but special support for Django querysets
  19   is included.
  20 - The builtin UI does not rely on JavaScript.
  21 - Support for automatic table generation based on a Django model.
  22 - Supports custom column functionality via subclassing.
  23 - Pagination.
  24 - Column based table sorting.
  25 - Template tag to enable trivial rendering to HTML.
  26 - Generic view mixin for use in Django 1.3.
  27
  28 Creating a table is as simple as::
  29
  30     import django_tables2 as tables
  31
  32     class SimpleTable(tables.Table):
  33         class Meta:
  34             model = Simple
  35
  36 This would then be used in a view::
  37
  38     def simple_list(request):
  39         queryset = Simple.objects.all()
  40         table = SimpleTable(queryset)
  41         return render_to_response("simple_list.html", {"table": table},
  42                                   context_instance=RequestContext(request))
  43
  44 And finally in the template::
  45
  46     {% load django_tables2 %}
  47     {% render_table table %}
  48
  49
  50 This example shows one of the simplest cases, but django-tables2 can do a lot
  51 more! Check out the `documentation`__ for more details.
  52
  53 .. __: http://django-tables2.readthedocs.org/en/latest/
  54
  55
  56 Building the documentation
  57 ==========================
  58
  59 If you want to build the docs from within a virtualenv, use::
  60
  61     make html SPHINXBUILD="python $(which sphinx-build)"