.. default-domain:: py
-===============================================
-django-tables - An app for creating HTML tables
-===============================================
+================================================
+django-tables2 - An app for creating HTML tables
+================================================
-django-tables simplifies the task of turning sets of datainto HTML tables. It
+django-tables2 simplifies the task of turning sets of datainto HTML tables. It
has native support for pagination and sorting. It does for HTML tables what
``django.forms`` does for HTML forms.
Quick start guide
=================
-1. Download and install from https://github.com/bradleyayers/django-tables.
+1. Download and install from https://github.com/bradleyayers/django-tables2.
Grab a ``.tar.gz`` of the latest tag, and run ``pip install <tar.gz>``.
-2. Hook the app into your Django project by adding ``'django_tables'`` to your
+2. Hook the app into your Django project by adding ``'django_tables2'`` to your
``INSTALLED_APPS`` setting.
-3. Write a subclass of :class:`~django_tables.tables.Table` that describes the
+3. Write a subclass of :class:`~django_tables2.tables.Table` that describes the
structure of your table.
4. Create an instance of your table in a :term:`view`, provide it with
:term:`table data`, and pass it to a :term:`template` for display.
]
-The first step is to subclass :class:`~django_tables.tables.Table` and describe
+The first step is to subclass :class:`~django_tables2.tables.Table` and describe
the table structure. This is done by creating a column for each attribute in
the :term:`table data`.
.. code-block:: python
- import django_tables as tables
+ import django_tables2 as tables
class CountryTable(tables.Table):
name = tables.Column()
context_instance=RequestContext(request))
In your template, the easiest way to :term:`render` the table is via the
-:meth:`~django_tables.tables.Table.as_html` method:
+:meth:`~django_tables2.tables.Table.as_html` method:
.. code-block:: django
.. code-block:: django
- {% load django_tables %}
+ {% load django_tables2 %}
{% render_table table %}
.. note::
.. code-block:: python
- import django_tables as tables
+ import django_tables2 as tables
class CountryTable(tables.Table):
name = tables.Column()
.. code-block:: html
- <link rel="stylesheet" type="text/css" href="{{ STATIC_URL }}django_tables/themes/paleblue/css/screen.css" />
+ <link rel="stylesheet" type="text/css" href="{{ STATIC_URL }}django_tables2/themes/paleblue/css/screen.css" />
Save your template and reload the page in your browser.
Each item in the :term:`table data` is called a :term:`record` and is used to
populate a single row in the table. By default, the table uses column names
as :term:`accessors <accessor>` to retrieve individual cell values. This can
-be changed via the :attr:`~django_tables.columns.Column.accessor` argument.
+be changed via the :attr:`~django_tables2.columns.Column.accessor` argument.
Any iterable can be used as table data, and there's builtin support for
:class:`QuerySet` objects (to ensure they're handled effeciently).
==============
The header cell for each column comes from the column's
-:meth:`~django_tables.columns.BoundColumn.header` method. By default this
+:meth:`~django_tables2.columns.BoundColumn.header` method. By default this
method returns the column's ``verbose_name``, which is either explicitly
specified, or generated automatically based on the column name.
---
In order to use CSS to style a table, you'll probably want to add a
-``class`` or ``id`` attribute to the ``<table>`` element. ``django-tables`` has
+``class`` or ``id`` attribute to the ``<table>`` element. ``django-tables2`` has
a hook that allows abitrary attributes to be added to the ``<table>`` tag.
.. code-block:: python
- >>> import django_tables as tables
+ >>> import django_tables2 as tables
>>> class SimpleTable(tables.Table):
... id = tables.Column()
... age = tables.Column()
.. code-block:: python
- >>> import django_tables as tables
+ >>> import django_tables2 as tables
>>> class SimpleTable(tables.Table):
... row_number = tables.Column()
... id = tables.Column()
.. code-block:: python
- >>> import django_tables as tables
+ >>> import django_tables2 as tables
>>>
>>> class AngryColumn(tables.Column):
... def render(self, value):
.. code-block:: django
- {% load django_tables %}
+ {% load django_tables2 %}
<table>
<thead>
<tr>
render_table
------------
-Renders a :class:`~django_tables.tables.Table` object to HTML and includes as
+Renders a :class:`~django_tables2.tables.Table` object to HTML and includes as
many features as possible.
Sample usage:
.. code-block:: django
- {% load django_tables %}
+ {% load django_tables2 %}
{% render_table table %}
This tag temporarily modifies the :class:`.Table` object while it is being
==========================
Django 1.3 introduced `class based views`__ as a mechanism to reduce the
-repetition in view code. django-tables comes with a single class based view
+repetition in view code. django-tables2 comes with a single class based view
mixin: ``SingleTableMixin``. It makes it trivial to incorporate a table into a
view/template, however it requires a few variables to be defined on the view:
.. code-block:: python
- from django_tables.views import SingleTableMixin
+ from django_tables2.views import SingleTableMixin
from django.generic.views.list import ListView
.. code-block:: django
- {% load django_tables %}
+ {% load django_tables2 %}
{% render_table table %}
Such little code is possible due to the example above taking advantage of
['name']
To have a mixin contribute a column, it needs to be a subclass of
-:class:`~django_tables.tables.Table`. With this in mind the previous example
+:class:`~django_tables2.tables.Table`. With this in mind the previous example
*should* have been written as follows::
>>> class UsefulMixin(tables.Table):
changing ``verbose_name`` on columns, or adding an extra
:class:`~.CheckBoxColumn`.
-``django-tables`` offers the :attr:`.Table.Meta.model` option to ease the pain.
+``django-tables2`` offers the :attr:`.Table.Meta.model` option to ease the pain.
The ``model`` option causes the table automatically generate columns for the
fields in the model. This means that the above table could be re-written as
follows::
If you want to customise one of the columns, simply define it the way you would
normally::
- >>> from django_tables import A
+ >>> from django_tables2 import A
>>> class PersonTable(tables.Table):
... user = tables.LinkColumn("admin:auth_user_change", args=[A("user.pk")])
...
:class:`Accessor` Objects:
--------------------------
-.. autoclass:: django_tables.utils.Accessor
+.. autoclass:: django_tables2.utils.Accessor
:members:
:class:`Table` Objects:
-----------------------
-.. autoclass:: django_tables.tables.Table
+.. autoclass:: django_tables2.tables.Table
:class:`Table.Meta` Objects:
Allows custom HTML attributes to be specified which will be added to
the ``<table>`` tag of any table rendered via
- :meth:`~django_tables.tables.Table.as_html` or the
+ :meth:`~django_tables2.tables.Table.as_html` or the
:ref:`template-tags.render_table` template tag.
:type: ``dict``
... last_name = tables.Column()
...
>>> Person.base_columns
- {'first_name': <django_tables.columns.Column object at 0x10046df10>,
- 'last_name': <django_tables.columns.Column object at 0x10046d8d0>}
+ {'first_name': <django_tables2.columns.Column object at 0x10046df10>,
+ 'last_name': <django_tables2.columns.Column object at 0x10046d8d0>}
>>> class ForgetfulPerson(Person):
... class Meta:
... exclude = ("last_name", )
...
>>> ForgetfulPerson.base_columns
- {'first_name': <django_tables.columns.Column object at 0x10046df10>}
+ {'first_name': <django_tables2.columns.Column object at 0x10046df10>}
.. note::
:class:`TableData` Objects:
------------------------------
-.. autoclass:: django_tables.tables.TableData
+.. autoclass:: django_tables2.tables.TableData
:members: __init__, order_by, __getitem__, __len__
:class:`Column` Objects:
------------------------
-.. autoclass:: django_tables.columns.Column
+.. autoclass:: django_tables2.columns.Column
:class:`CheckBoxColumn` Objects:
--------------------------------
-.. autoclass:: django_tables.columns.CheckBoxColumn
+.. autoclass:: django_tables2.columns.CheckBoxColumn
:members:
:class:`LinkColumn` Objects:
----------------------------
-.. autoclass:: django_tables.columns.LinkColumn
+.. autoclass:: django_tables2.columns.LinkColumn
:members:
:class:`TemplateColumn` Objects:
--------------------------------
-.. autoclass:: django_tables.columns.TemplateColumn
+.. autoclass:: django_tables2.columns.TemplateColumn
:members:
:class:`BoundColumns` Objects
-----------------------------
-.. autoclass:: django_tables.columns.BoundColumns
+.. autoclass:: django_tables2.columns.BoundColumns
:members: all, items, sortable, visible, __iter__,
__contains__, __len__, __getitem__
:class:`BoundColumn` Objects
----------------------------
-.. autoclass:: django_tables.columns.BoundColumn
+.. autoclass:: django_tables2.columns.BoundColumn
:members:
:class:`BoundRows` Objects
--------------------------
-.. autoclass:: django_tables.rows.BoundRows
+.. autoclass:: django_tables2.rows.BoundRows
:members: __iter__, __len__, count
:class:`BoundRow` Objects
-------------------------
-.. autoclass:: django_tables.rows.BoundRow
+.. autoclass:: django_tables2.rows.BoundRow
:members: __getitem__, __contains__, __iter__, record, table
:class:`AttributeDict` Objects
------------------------------
-.. autoclass:: django_tables.utils.AttributeDict
+.. autoclass:: django_tables2.utils.AttributeDict
:members:
:class:`OrderBy` Objects
------------------------
-.. autoclass:: django_tables.utils.OrderBy
+.. autoclass:: django_tables2.utils.OrderBy
:members:
:class:`OrderByTuple` Objects
-----------------------------
-.. autoclass:: django_tables.utils.OrderByTuple
+.. autoclass:: django_tables2.utils.OrderByTuple
:members: __unicode__, __contains__, __getitem__, cmp
.. glossary::
accessor
- Refers to an :class:`~django_tables.utils.Accessor` object
+ Refers to an :class:`~django_tables2.utils.Accessor` object
bare orderby
- The non-prefixed form of an :class:`~django_tables.utils.OrderBy`
+ The non-prefixed form of an :class:`~django_tables2.utils.OrderBy`
object. Typically the bare form is just the ascending form.
Example: ``age`` is the bare form of ``-age``
A single Python object used as the data for a single row.
render
- The act of serialising a :class:`~django_tables.tables.Table` into
+ The act of serialising a :class:`~django_tables2.tables.Table` into
HTML.
template
table data
An interable of :term:`records <record>` that
- :class:`~django_tables.tables.Table` uses to populate its rows.
+ :class:`~django_tables2.tables.Table` uses to populate its rows.
projects / django-tables2.git / blobdiff