Welcome to django-listable's documentation!
###########################################
.. image:: https://travis-ci.org/randlet/django-listable.svg?branch=master
:target: https://travis-ci.org/randlet/django-listable
=====
About
=====
Listable is a Django package to make the integration of your Django
models with `Datatables.js <https://datatables.net/>`_ easy.
Django-listable was motivated by my repeated need to generate sortable
and filterable tables from my Django models for CRUD apps.
The idea is that you should easily be able to go from a model like this::
class Staff(models.Model):
first_name = models.CharField(max_length=255, help_text=_("Enter the name of the staff being rounded"))
last_name = models.CharField(max_length=255, help_text=_("Enter the name of the staff being rounded"))
active = models.CharField(max_length=10, choices = ACTIVE_CHOICES)
position = models.ForeignKey(Position)
department = models.ForeignKey(Department)
limit = models.Q(app_label='staff', model='genericmodela') | models.Q(app_label='staff', model='genericmodelb')
content_type = models.ForeignKey(ContentType, limit_choices_to=limit)
object_id = models.PositiveIntegerField()
generic_object = generic.GenericForeignKey("content_type", "object_id")
to a filterable/orderable table in a template like this with as little code as possible:
.. image:: docs/_static/staff_table.png
There are a couple of other similar projects worth checking out to see if they fit your
needs better:
- `django-datatables-view <https://pypi.python.org/pypi/django-datatables-view>`_
- `django-datatables <https://pypi.python.org/pypi/django-datatables>`_
- `django-eztables <https://github.com/noirbizarre/django-eztables>`_
============
Installation
============
$ pip install django-listable
========
Settings
========
Listable currently has 4 settings you can configure to be used
as default values for your table (they can be overriden in the listable template tag).
*LISTABLE_DOM*
Default datatables sDOM parameter to use. By default listable uses the Bootstrap 3 dom below.::
# bootstrap 2
# LISTABLE_DOM = '<"row-fluid"<"span6"ir><"span6"p>>rt<"row-fluid"<"span12"lp>>'
#boostrap 3
LISTABLE_DOM = '<"row"<"col-sm-6"i><"col-sm-6"rp>>rt<"row"<"col-sm-12"lp>>'
*LISTABLE_PAGINATION_TYPE* ::
# pagination types -> bootstrap2, bootstrap3, two_button, full_numbers
LISTABLE_PAGINATION_TYPE = "full_numbers"
*LISTABLE_STATE_SAVE*
Enable sticky filters by default.::
LISTABLE_STATE_SAVE = True
*LISTABLE_PAGINATE_BY*
Default page size.::
LISTABLE_PAGINATE_BY = 10
=====
Usage
=====
There's four steps to using django-listable
1. Including `listable` in your settings.INSTALLED_APPS
2. Create a view by subclassing listable.views.BaseListableView
3. Connect the view to a url pattern in your apps urls.py
4. Include the `listable` template tag in a template
These steps will demonstrated below assuming we have
a Django application called staff and we want to create a page on our
site with a list of staff and the department and business they belong to.
with the following models defined::
class Business(models.Model):
name = models.CharField(max_length=255)
class Department(models.Model):
name = models.CharField(max_length=255)
business = models.ForeignKey(Business)
class Staff(models.Model):
first_name = models.CharField(max_length=255, help_text=_("Enter the name of the staff being rounded"))
last_name = models.CharField(max_length=255, help_text=_("Enter the name of the staff being rounded"))
active = models.CharField(max_length=10, choices = ACTIVE_CHOICES)
department = models.ForeignKey(Department)
def name(self):
return "%s, %s" % (self.last_name, self.first_name)
def status(self):
return self.get_active_display()
A full functional example can be found in the demo app included with
django-listable.
Adding `listable` to settings.INSTALLED_APPS
--------------------------------------------
To start using django-listable add `listable` to your INSTALLED_APPS::
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.messages',
'django.contrib.staticfiles',
'django.contrib.admin',
'staff',
'listable',
...
)
Defining a Listable view
------------------------
To define a `listable` view, sublcass `listable.views.BaseListableView`
and set the model that is to be used as the source of data::
from listable.views import BaseListableView
from models import Staff
class StaffList(BaseListableView):
model = models.Staff
...
Defining Columns for your table
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Every `listable` view must define one or more fields to be displayed as columns in the table.
`listable` fields are defined in a manner similar to ModelForms::
class StaffList(BaseListableView):
model = models.Staff
fields = (...)
widgets = {...} # optional
search_fields = {...} # optional
order_fields = {...} # optional
headers = {...} # optional
select_related = (...) # optional
prefetch_related = (...) # optional
*fields*
Fields defines an iterable of the columns that you want to display in the table,
these fields can either be fields on your model, foreign key lookups, the name
of a callable on your view, the name of a callable on your model or the result of an *extra*
query.
*widgets*
Widgets is a dictionary mapping a field to a search widget type. Currently you can use
either text (default) or select inputs. For example::
from listable.views import BaseListableView, SELECT
from . import models
class StaffList(BaseListableView):
model = models.Staff
fields = ("id", "name", "active", "department__name",)
widgets = {
"department__name": SELECT,
"active": SELECT,
}
The choices available in a select widget are currently automatically
populated although this will change to allow manual configuration of choices
in the future. The choices are populated based on either the `choices` option
for a model field or in the case of a foreign key all the values of the foreign
key lookup. (*I hope to make this more flexible in the future*)
*search_fields (optional)*
Search fields are a mapping of field names to the django filter syntax that should
be used for searching the table. This can either be a string, an iterable of
strings or a falsy value to disable searching on that field. For example::
search_fields = {
"name": ("first_name__icontains", "last_name__icontains",),
"last_name": "last_name__exact",
"genericname": "genericname__icontains",
"department__name": False,
}
if a field is not declared in search_field's it a filter using `icontains` is assumed.
*loose_text_search*
If set to True, will split search terms. E.g. "Sm ti" will return an object with field value of "Small Ticket".
This is very similar to how Django's admin backend does its searches. Be default, the value is False for backward
compatibility.
*order_fields (optional)*
Order fields allows you to define how a column should be ordered (similar to
Django's ordering or order_by). For example::
order_fields = {
"name": ("last_name", "first_name",),
}
*headers (optional)*
Headers is a mapping of field names to the column name to be displayed. For example by default
a field name of `department__business__name` would be converted to "Department Business Name" but that
could be overriden like so::
headers = {
"department__business__name": _("Business"),
}
*select_related*
Allows you to use Django's queryset select_related option for reducing database queries. e.g::
select_related = ("department", "position", "department__business",)
*prefetch_related*
Allows you to use Django's queryset prefetch_related option for reducing database queries. e.g::
prefetch_related = ("some_fk__some_field",)
*get_extra*
*Due to a bug with pagination, using an extra query will result in your entire table being loaded into memory before
being paginated :(*
You may define a callable `get_extra` method on your view that should return a dictionary suitable
for use in the Django queryset's `extra` method. For example::
def get_extra(self):
return {select: {'is_recent': "pub_date > '2006-01-01'"}}
A more complex example is given in the "Complete Example" sample below.
Formatting fields
^^^^^^^^^^^^^^^^^
The order in which `listable` tries to find a method for formatting a field for display is as follows:
1. A method on the actual view::
class StaffList(BaseListableView):
model = models.Staff
fields = (..., "name",...)
def name(self, staff):
return staff.name()
2. A `get_{field}_display` callable on the model.
3. A callable on the model::
class Staff(Model):
...
def staff_name(self):
return "{0} {1}".format(self.first_name, self.last_name)
class StaffList(BaseListableView):
model = models.Staff
fields = (..., "staff_name",...)
4. A field on the model.
A `listable` column is defined using the `listable.views.Column` data structure.
A `Column` is essentially a namedtuple with the following fields (detailed descriptions below):
Including the `listable` template tag in a template
---------------------------------------------------
To include `listable` in your templates you need to load the `listable` template
tags and include the `listable_css`, a placeholder for the listable table
and the listable tag which tells the template the name of the view to wire the table to.::
{% extends 'base.html' %}
{% load listable %}
{% block extra_css %}
{% listable_css %}
{% endblock extra_css %}
{% block content %}
{{listable_table}}
{% endblock %}
{% block extra_js %}
{% listable 'staff-list'%}
{% endblock extra_js %}
with the example above requiring a url something like::
urlpatterns = patterns('',
url('staff-list/$', views.StaffList.as_view(), name="staff-list"),
)
Arguments to the listable tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The listable tag currently has 1 required argument and five optional keyword args.
A full example of the listable template tag looks like::
{% listable 'staff-list' dom="", save_state=False, pagination_type="", css_table_class="", css_input_class="" %}
*dom*
Overrides the default Datatables sDOM parameter to use. ::
{% listable 'staff-list' dom='<"row-fluid"<"span6"ir><"span6"p>>rt<"row-fluid"<"span12"lp>>' %}
*pagination_type*
Overrides the default Datatables sDOM parameter to use. ::
{% listable 'staff-list' pagination_type='bootstrap3' %}
*save_state*
Save state enables/disables sticky filters in `DataTables <Datahttp://www.datatables.net/examples/basic_init/state_save.html>`_.::
{% listable 'staff-list' save_state=False %}
*css_table_class*
Add a css class to your datatables table e.g.::
{% listable 'staff-list' css_table_class="striped compact" %}
*css_input_class*
Add a css class to the datatables column filter inputs e.g.::
{% listable 'staff-list' css_table_class="input-sm" %}
==================
A Complete Example
==================
This is a complete example of a `django-listable` table. It is included
as a demo app under the django-listable/listable-demo/
models.py
---------
::
ACTIVE = 'active'
INACTIVE = 'inactive'
TERMINATED = 'terminated'
ACTIVE_CHOICES = (
(ACTIVE, "Active"),
(INACTIVE, "Inactive"),
(TERMINATED, "Terminated"),
)
ACTIVE_CHOICES_DISPLAY = dict(ACTIVE_CHOICES)
class Business(models.Model):
name = models.CharField(max_length=255)
business_type = models.IntegerField(choices=zip(range(5), range(5)), default=1)
class Meta:
verbose_name_plural = "Businesses"
def __unicode__(self):
return self.name
class Department(models.Model):
name = models.CharField(max_length=255)
business = models.ForeignKey(Business)
def __unicode__(self):
return self.name
class Position(models.Model):
name = models.CharField(max_length=255)
def __unicode__(self):
return self.name
class AbstractGeneric(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
staff = generic.GenericRelation(
"Staff",
content_type_field="content_type",
object_id_field="object_id",
)
class Meta:
abstract = True
class GenericModelA(AbstractGeneric):
class Meta:
verbose_name_plural = "Generic Model A's"
def __unicode__(self):
return self.name
class GenericModelB(AbstractGeneric):
class Meta:
verbose_name_plural = "Generic Model B's"
def __unicode__(self):
return self.name
class Staff(models.Model):
first_name = models.CharField(max_length=255, help_text=_("Enter the name of the staff being rounded"))
last_name = models.CharField(max_length=255, help_text=_("Enter the name of the staff being rounded"))
active = models.CharField(max_length=10, choices=ACTIVE_CHOICES)
position = models.ForeignKey(Position)
department = models.ForeignKey(Department)
limit = models.Q(app_label='staff', model='genericmodela') | models.Q(app_label='staff', model='genericmodelb')
content_type = models.ForeignKey(ContentType, limit_choices_to=limit)
object_id = models.PositiveIntegerField()
generic_object = generic.GenericForeignKey("content_type", "object_id")
class Meta:
verbose_name_plural = "staff"
ordering = ("last_name", "first_name",)
def name(self):
return "%s, %s" % (self.last_name, self.first_name)
def status(self):
return ACTIVE_CHOICES_DISPLAY[self.active]
def __unicode__(self):
return self.name()
views.py
--------
::
class StaffList(BaseListableView):
model = models.Staff
fields = (
"id",
"name",
"active",
"department__name",
"position__name",
"department__business__name",
"department__business__business_type",
"genericname",
)
widgets = {
"department__business__name": SELECT,
"department__business__business_type": SELECT,
"position__name": SELECT,
"choices": SELECT,
"active": SELECT,
}
search_fields = {
"name": ("first_name__icontains", "last_name__icontains",),
"last_name": "last_name__exact",
"genericname": "genericname__icontains",
"department__name": "department__name__icontains",
}
order_fields = {
"name": ("last_name", "first_name",),
}
headers = {
"position__name": _("Position"),
"department__business__name": _("Business"),
"department__business__business_type": _("Business Type"),
}
select_related = ("department", "position", "department__business",)
def generic(self, obj):
return obj.generic_object.name
def name(self, staff):
return staff.name()
def get_extra(self):
cta = ContentType.objects.get_for_model(models.GenericModelA)
ctb = ContentType.objects.get_for_model(models.GenericModelB)
extraq = """
CASE
WHEN content_type_id = {0}
THEN (SELECT name from staff_genericmodela WHERE object_id = staff_genericmodela.id)
WHEN content_type_id = {1}
THEN (SELECT name from staff_genericmodelb WHERE object_id = staff_genericmodelb.id)
END
""".format(cta.pk, ctb.pk)
return {"select": {'genericname': extraq}}
staff_list.html
---------------
::
{% extends 'base.html' %}
{% load listable %}
{% block extra_css %}
{% listable_css %}
{% endblock extra_css %}
{% block content %}
{{listable_table}}
{% endblock %}
{% block extra_js %}
{% listable 'staff-list' save_state=True %}
{% endblock extra_js %}
=======
History
=======
0.8.2 (2023-12-22)
------------------
* Django 4.x compatibility
0.8.1 (2023-05-25)
------------------
* In order to allow ``|`` characters in searches, the search term separator for
multi selects has been updated to use ```|``` which is a 3 character sequence
unlikely to apply in normal searches.
0.8.0 (2023-04-18)
------------------
* Added a loose_text_search setting to views. Set ``loose_text_search = True``
on your view to enable partial matching in your text searches. For example
"Fo Ba" will match "Foo Bar".
0.7.0 (2023-02-24)
------------------
* Listable for Django 3.2
0.6.0 (2021-10-07)
------------------
* Add field names to column headers as data attributes
* Add columnSearch to Listable context object
0.5.2 (2021-08-20)
------------------
* Fix issue with encoding of search filters
0.5.1 (2021-06-15)
------------------
* wrap datatables css/scripts in function so static is not called at import
0.5.0 (2021-02-03)
------------------
* Fixed a same site cookie issue
* Fixed a bug where select dropdowns were being truncated by bottom of page
* Added a get_fields method to set fields dynamically
* Fix an issue with incorrect timezones
* Add support for Django 2-
0.4.3 (2017-05-11)
------------------
Fix values_to_dt to allow unicode
0.4.1 (2016-10-14)
------------------
Add fix for when using FORCE_SCRIPT_NAME setting
0.4.0 (2016-10-02)
------------------
Update to support Django 1.8-1.10 and Python 2.7-3.5
0.3.10 (2016-11-08)
-------------------
Cast search term to lower case if case insensitive search requested to allow
easier filtering with extra queries.
0.3.9 (2016-09-27)
------------------
Fix formatting bug introduced by 0.3.8
0.3.8 (2016-09-27)
------------------
Fix unicode encoding error
0.3.7 (2016-08-25)
------------------
Add date range picker
0.3.6 (2016-06-29)
------------------
Add multi select and date select widgets (thanks to @ryanbottema)
0.3.5 (2016-06-22)
------------------
Fix filtering and count queries for django-mssql
0.3.3 (2015-04-12)
------------------
* Fix filtering of None values for SELECT fields
0.3.1 (2015-02-25)
------------------
* Fix issue with boolean field filtering
0.2.10 (2014-12-16)
-------------------
* Fix issue with pagination type
0.2.9 (2014-12-15)
------------------
* Fix issue with namespaced urls
0.2.6 (2014-10-30)
------------------
* add view args & kwargs to context to allow full reverse
0.2.5 (2014-10-30)
------------------
* fix order_by
0.2.0 (2014-10-29)
------------------
* Complete overhaul of api
0.1.2 (2014-07-09)
------------------
* Fix saveState bug
0.1.0 (2013-08-15)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/randlet/django-listable",
"name": "django-listable",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django-listable",
"author": "Randle Taylor",
"author_email": "randle.taylor@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/26/d3/e84020970158bd3dea793e69f7d815fd041f1830d7dad1018d2cf37e108b/django-listable-0.8.2.tar.gz",
"platform": null,
"description": "Welcome to django-listable's documentation!\n###########################################\n\n.. image:: https://travis-ci.org/randlet/django-listable.svg?branch=master\n :target: https://travis-ci.org/randlet/django-listable\n\n\n=====\nAbout\n=====\n\nListable is a Django package to make the integration of your Django\nmodels with `Datatables.js <https://datatables.net/>`_ easy.\n\nDjango-listable was motivated by my repeated need to generate sortable\nand filterable tables from my Django models for CRUD apps.\n\nThe idea is that you should easily be able to go from a model like this::\n\n class Staff(models.Model):\n\n first_name = models.CharField(max_length=255, help_text=_(\"Enter the name of the staff being rounded\"))\n last_name = models.CharField(max_length=255, help_text=_(\"Enter the name of the staff being rounded\"))\n active = models.CharField(max_length=10, choices = ACTIVE_CHOICES)\n\n position = models.ForeignKey(Position)\n department = models.ForeignKey(Department)\n\n limit = models.Q(app_label='staff', model='genericmodela') | models.Q(app_label='staff', model='genericmodelb')\n content_type = models.ForeignKey(ContentType, limit_choices_to=limit)\n object_id = models.PositiveIntegerField()\n generic_object = generic.GenericForeignKey(\"content_type\", \"object_id\")\n\nto a filterable/orderable table in a template like this with as little code as possible:\n\n.. image:: docs/_static/staff_table.png\n\nThere are a couple of other similar projects worth checking out to see if they fit your\nneeds better:\n\n- `django-datatables-view <https://pypi.python.org/pypi/django-datatables-view>`_\n- `django-datatables <https://pypi.python.org/pypi/django-datatables>`_\n- `django-eztables <https://github.com/noirbizarre/django-eztables>`_\n\n\n============\nInstallation\n============\n\n $ pip install django-listable\n\n\n========\nSettings\n========\n\nListable currently has 4 settings you can configure to be used\nas default values for your table (they can be overriden in the listable template tag).\n\n*LISTABLE_DOM*\n\nDefault datatables sDOM parameter to use. By default listable uses the Bootstrap 3 dom below.::\n\n # bootstrap 2\n # LISTABLE_DOM = '<\"row-fluid\"<\"span6\"ir><\"span6\"p>>rt<\"row-fluid\"<\"span12\"lp>>'\n\n #boostrap 3\n LISTABLE_DOM = '<\"row\"<\"col-sm-6\"i><\"col-sm-6\"rp>>rt<\"row\"<\"col-sm-12\"lp>>'\n\n\n*LISTABLE_PAGINATION_TYPE* ::\n\n # pagination types -> bootstrap2, bootstrap3, two_button, full_numbers\n LISTABLE_PAGINATION_TYPE = \"full_numbers\"\n\n*LISTABLE_STATE_SAVE*\n\nEnable sticky filters by default.::\n\n LISTABLE_STATE_SAVE = True\n\n*LISTABLE_PAGINATE_BY*\n\nDefault page size.::\n\n LISTABLE_PAGINATE_BY = 10\n\n\n=====\nUsage\n=====\n\nThere's four steps to using django-listable\n\n1. Including `listable` in your settings.INSTALLED_APPS\n2. Create a view by subclassing listable.views.BaseListableView\n3. Connect the view to a url pattern in your apps urls.py\n4. Include the `listable` template tag in a template\n\nThese steps will demonstrated below assuming we have\na Django application called staff and we want to create a page on our\nsite with a list of staff and the department and business they belong to.\n\nwith the following models defined::\n\n class Business(models.Model):\n\n name = models.CharField(max_length=255)\n\n\n class Department(models.Model):\n\n name = models.CharField(max_length=255)\n business = models.ForeignKey(Business)\n\n\n class Staff(models.Model):\n\n first_name = models.CharField(max_length=255, help_text=_(\"Enter the name of the staff being rounded\"))\n last_name = models.CharField(max_length=255, help_text=_(\"Enter the name of the staff being rounded\"))\n active = models.CharField(max_length=10, choices = ACTIVE_CHOICES)\n\n department = models.ForeignKey(Department)\n\n def name(self):\n return \"%s, %s\" % (self.last_name, self.first_name)\n\n def status(self):\n return self.get_active_display()\n\nA full functional example can be found in the demo app included with\ndjango-listable.\n\n\nAdding `listable` to settings.INSTALLED_APPS\n--------------------------------------------\n\nTo start using django-listable add `listable` to your INSTALLED_APPS::\n\n INSTALLED_APPS = (\n 'django.contrib.auth',\n 'django.contrib.contenttypes',\n 'django.contrib.sessions',\n 'django.contrib.sites',\n 'django.contrib.messages',\n 'django.contrib.staticfiles',\n 'django.contrib.admin',\n\n\n 'staff',\n 'listable',\n ...\n )\n\nDefining a Listable view\n------------------------\n\nTo define a `listable` view, sublcass `listable.views.BaseListableView`\nand set the model that is to be used as the source of data::\n\n from listable.views import BaseListableView\n from models import Staff\n\n\n class StaffList(BaseListableView):\n\n model = models.Staff\n\n ...\n\nDefining Columns for your table\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nEvery `listable` view must define one or more fields to be displayed as columns in the table.\n`listable` fields are defined in a manner similar to ModelForms::\n\n class StaffList(BaseListableView):\n\n model = models.Staff\n\n\n fields = (...)\n widgets = {...} # optional\n search_fields = {...} # optional\n order_fields = {...} # optional\n headers = {...} # optional\n select_related = (...) # optional\n prefetch_related = (...) # optional\n\n\n\n*fields*\n\nFields defines an iterable of the columns that you want to display in the table,\nthese fields can either be fields on your model, foreign key lookups, the name\nof a callable on your view, the name of a callable on your model or the result of an *extra*\nquery.\n\n\n*widgets*\n\nWidgets is a dictionary mapping a field to a search widget type. Currently you can use\neither text (default) or select inputs. For example::\n\n from listable.views import BaseListableView, SELECT\n\n from . import models\n\n class StaffList(BaseListableView):\n\n model = models.Staff\n\n fields = (\"id\", \"name\", \"active\", \"department__name\",)\n\n widgets = {\n \"department__name\": SELECT,\n \"active\": SELECT,\n }\n\nThe choices available in a select widget are currently automatically\npopulated although this will change to allow manual configuration of choices\nin the future. The choices are populated based on either the `choices` option\nfor a model field or in the case of a foreign key all the values of the foreign\nkey lookup. (*I hope to make this more flexible in the future*)\n\n*search_fields (optional)*\n\nSearch fields are a mapping of field names to the django filter syntax that should\nbe used for searching the table. This can either be a string, an iterable of\nstrings or a falsy value to disable searching on that field. For example::\n\n search_fields = {\n \"name\": (\"first_name__icontains\", \"last_name__icontains\",),\n \"last_name\": \"last_name__exact\",\n \"genericname\": \"genericname__icontains\",\n \"department__name\": False,\n }\n\nif a field is not declared in search_field's it a filter using `icontains` is assumed.\n\n *loose_text_search*\n\nIf set to True, will split search terms. E.g. \"Sm ti\" will return an object with field value of \"Small Ticket\".\nThis is very similar to how Django's admin backend does its searches. Be default, the value is False for backward\ncompatibility.\n\n\n*order_fields (optional)*\n\nOrder fields allows you to define how a column should be ordered (similar to\nDjango's ordering or order_by). For example::\n\n\n order_fields = {\n \"name\": (\"last_name\", \"first_name\",),\n }\n\n*headers (optional)*\n\nHeaders is a mapping of field names to the column name to be displayed. For example by default\na field name of `department__business__name` would be converted to \"Department Business Name\" but that\ncould be overriden like so::\n\n headers = {\n \"department__business__name\": _(\"Business\"),\n }\n\n*select_related*\n\nAllows you to use Django's queryset select_related option for reducing database queries. e.g::\n\n select_related = (\"department\", \"position\", \"department__business\",)\n\n*prefetch_related*\n\nAllows you to use Django's queryset prefetch_related option for reducing database queries. e.g::\n\n prefetch_related = (\"some_fk__some_field\",)\n\n\n*get_extra*\n\n*Due to a bug with pagination, using an extra query will result in your entire table being loaded into memory before\nbeing paginated :(*\n\nYou may define a callable `get_extra` method on your view that should return a dictionary suitable\nfor use in the Django queryset's `extra` method. For example::\n\n def get_extra(self):\n return {select: {'is_recent': \"pub_date > '2006-01-01'\"}}\n\n\nA more complex example is given in the \"Complete Example\" sample below.\n\n\n\nFormatting fields\n^^^^^^^^^^^^^^^^^\n\nThe order in which `listable` tries to find a method for formatting a field for display is as follows:\n\n1. A method on the actual view::\n\n class StaffList(BaseListableView):\n\n model = models.Staff\n\n fields = (..., \"name\",...)\n def name(self, staff):\n return staff.name()\n\n2. A `get_{field}_display` callable on the model.\n\n3. A callable on the model::\n\n class Staff(Model):\n ...\n def staff_name(self):\n return \"{0} {1}\".format(self.first_name, self.last_name)\n\n class StaffList(BaseListableView):\n\n model = models.Staff\n\n fields = (..., \"staff_name\",...)\n\n4. A field on the model.\n\nA `listable` column is defined using the `listable.views.Column` data structure.\nA `Column` is essentially a namedtuple with the following fields (detailed descriptions below):\n\n\nIncluding the `listable` template tag in a template\n---------------------------------------------------\n\nTo include `listable` in your templates you need to load the `listable` template\ntags and include the `listable_css`, a placeholder for the listable table\nand the listable tag which tells the template the name of the view to wire the table to.::\n\n\n {% extends 'base.html' %}\n\n {% load listable %}\n\n {% block extra_css %}\n {% listable_css %}\n {% endblock extra_css %}\n\n {% block content %}\n {{listable_table}}\n {% endblock %}\n\n {% block extra_js %}\n {% listable 'staff-list'%}\n {% endblock extra_js %}\n\n\nwith the example above requiring a url something like::\n\n\n urlpatterns = patterns('',\n url('staff-list/$', views.StaffList.as_view(), name=\"staff-list\"),\n )\n\n\nArguments to the listable tag\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe listable tag currently has 1 required argument and five optional keyword args.\nA full example of the listable template tag looks like::\n\n {% listable 'staff-list' dom=\"\", save_state=False, pagination_type=\"\", css_table_class=\"\", css_input_class=\"\" %}\n\n*dom*\n\nOverrides the default Datatables sDOM parameter to use. ::\n\n {% listable 'staff-list' dom='<\"row-fluid\"<\"span6\"ir><\"span6\"p>>rt<\"row-fluid\"<\"span12\"lp>>' %}\n\n*pagination_type*\n\nOverrides the default Datatables sDOM parameter to use. ::\n\n {% listable 'staff-list' pagination_type='bootstrap3' %}\n\n*save_state*\n\nSave state enables/disables sticky filters in `DataTables <Datahttp://www.datatables.net/examples/basic_init/state_save.html>`_.::\n\n {% listable 'staff-list' save_state=False %}\n\n*css_table_class*\n\nAdd a css class to your datatables table e.g.::\n\n {% listable 'staff-list' css_table_class=\"striped compact\" %}\n\n*css_input_class*\n\nAdd a css class to the datatables column filter inputs e.g.::\n\n {% listable 'staff-list' css_table_class=\"input-sm\" %}\n\n\n==================\nA Complete Example\n==================\n\nThis is a complete example of a `django-listable` table. It is included\nas a demo app under the django-listable/listable-demo/\n\nmodels.py\n---------\n\n::\n\n ACTIVE = 'active'\n INACTIVE = 'inactive'\n TERMINATED = 'terminated'\n\n ACTIVE_CHOICES = (\n (ACTIVE, \"Active\"),\n (INACTIVE, \"Inactive\"),\n (TERMINATED, \"Terminated\"),\n )\n\n ACTIVE_CHOICES_DISPLAY = dict(ACTIVE_CHOICES)\n\n\n class Business(models.Model):\n\n name = models.CharField(max_length=255)\n business_type = models.IntegerField(choices=zip(range(5), range(5)), default=1)\n\n class Meta:\n verbose_name_plural = \"Businesses\"\n\n def __unicode__(self):\n return self.name\n\n\n class Department(models.Model):\n\n name = models.CharField(max_length=255)\n business = models.ForeignKey(Business)\n\n def __unicode__(self):\n return self.name\n\n\n class Position(models.Model):\n\n name = models.CharField(max_length=255)\n\n def __unicode__(self):\n return self.name\n\n\n class AbstractGeneric(models.Model):\n\n name = models.CharField(max_length=255)\n description = models.TextField()\n\n staff = generic.GenericRelation(\n \"Staff\",\n content_type_field=\"content_type\",\n object_id_field=\"object_id\",\n )\n\n class Meta:\n abstract = True\n\n\n class GenericModelA(AbstractGeneric):\n\n class Meta:\n verbose_name_plural = \"Generic Model A's\"\n\n def __unicode__(self):\n return self.name\n\n\n class GenericModelB(AbstractGeneric):\n\n class Meta:\n verbose_name_plural = \"Generic Model B's\"\n\n def __unicode__(self):\n return self.name\n\n\n class Staff(models.Model):\n\n first_name = models.CharField(max_length=255, help_text=_(\"Enter the name of the staff being rounded\"))\n last_name = models.CharField(max_length=255, help_text=_(\"Enter the name of the staff being rounded\"))\n active = models.CharField(max_length=10, choices=ACTIVE_CHOICES)\n\n position = models.ForeignKey(Position)\n department = models.ForeignKey(Department)\n\n limit = models.Q(app_label='staff', model='genericmodela') | models.Q(app_label='staff', model='genericmodelb')\n content_type = models.ForeignKey(ContentType, limit_choices_to=limit)\n object_id = models.PositiveIntegerField()\n generic_object = generic.GenericForeignKey(\"content_type\", \"object_id\")\n\n class Meta:\n verbose_name_plural = \"staff\"\n ordering = (\"last_name\", \"first_name\",)\n\n def name(self):\n return \"%s, %s\" % (self.last_name, self.first_name)\n\n def status(self):\n return ACTIVE_CHOICES_DISPLAY[self.active]\n\n def __unicode__(self):\n return self.name()\n\nviews.py\n--------\n\n::\n\n class StaffList(BaseListableView):\n\n model = models.Staff\n\n fields = (\n \"id\",\n \"name\",\n \"active\",\n \"department__name\",\n \"position__name\",\n \"department__business__name\",\n \"department__business__business_type\",\n \"genericname\",\n )\n\n widgets = {\n \"department__business__name\": SELECT,\n \"department__business__business_type\": SELECT,\n \"position__name\": SELECT,\n \"choices\": SELECT,\n \"active\": SELECT,\n }\n\n search_fields = {\n \"name\": (\"first_name__icontains\", \"last_name__icontains\",),\n \"last_name\": \"last_name__exact\",\n \"genericname\": \"genericname__icontains\",\n \"department__name\": \"department__name__icontains\",\n }\n\n order_fields = {\n \"name\": (\"last_name\", \"first_name\",),\n }\n\n headers = {\n \"position__name\": _(\"Position\"),\n \"department__business__name\": _(\"Business\"),\n \"department__business__business_type\": _(\"Business Type\"),\n }\n\n select_related = (\"department\", \"position\", \"department__business\",)\n\n def generic(self, obj):\n return obj.generic_object.name\n\n def name(self, staff):\n return staff.name()\n\n def get_extra(self):\n cta = ContentType.objects.get_for_model(models.GenericModelA)\n ctb = ContentType.objects.get_for_model(models.GenericModelB)\n\n extraq = \"\"\"\n CASE\n WHEN content_type_id = {0}\n THEN (SELECT name from staff_genericmodela WHERE object_id = staff_genericmodela.id)\n WHEN content_type_id = {1}\n THEN (SELECT name from staff_genericmodelb WHERE object_id = staff_genericmodelb.id)\n END\n \"\"\".format(cta.pk, ctb.pk)\n\n return {\"select\": {'genericname': extraq}}\n\n\nstaff_list.html\n---------------\n\n::\n\n {% extends 'base.html' %}\n\n {% load listable %}\n\n {% block extra_css %}\n {% listable_css %}\n {% endblock extra_css %}\n\n {% block content %}\n {{listable_table}}\n {% endblock %}\n\n {% block extra_js %}\n {% listable 'staff-list' save_state=True %}\n {% endblock extra_js %}\n\n\n\n\n\n=======\nHistory\n=======\n\n0.8.2 (2023-12-22)\n------------------\n\n* Django 4.x compatibility\n\n\n0.8.1 (2023-05-25)\n------------------\n\n* In order to allow ``|`` characters in searches, the search term separator for\n multi selects has been updated to use ```|``` which is a 3 character sequence\n unlikely to apply in normal searches.\n\n0.8.0 (2023-04-18)\n------------------\n\n* Added a loose_text_search setting to views. Set ``loose_text_search = True``\n on your view to enable partial matching in your text searches. For example\n \"Fo Ba\" will match \"Foo Bar\".\n\n0.7.0 (2023-02-24)\n------------------\n\n* Listable for Django 3.2\n\n0.6.0 (2021-10-07)\n------------------\n\n* Add field names to column headers as data attributes\n* Add columnSearch to Listable context object\n\n0.5.2 (2021-08-20)\n------------------\n\n* Fix issue with encoding of search filters\n\n0.5.1 (2021-06-15)\n------------------\n\n* wrap datatables css/scripts in function so static is not called at import\n\n\n\n0.5.0 (2021-02-03)\n------------------\n* Fixed a same site cookie issue\n* Fixed a bug where select dropdowns were being truncated by bottom of page\n* Added a get_fields method to set fields dynamically\n* Fix an issue with incorrect timezones\n* Add support for Django 2-\n\n\n0.4.3 (2017-05-11)\n------------------\nFix values_to_dt to allow unicode\n\n0.4.1 (2016-10-14)\n------------------\nAdd fix for when using FORCE_SCRIPT_NAME setting\n\n0.4.0 (2016-10-02)\n------------------\nUpdate to support Django 1.8-1.10 and Python 2.7-3.5\n\n0.3.10 (2016-11-08)\n-------------------\nCast search term to lower case if case insensitive search requested to allow\neasier filtering with extra queries.\n\n0.3.9 (2016-09-27)\n------------------\nFix formatting bug introduced by 0.3.8\n\n0.3.8 (2016-09-27)\n------------------\nFix unicode encoding error\n\n0.3.7 (2016-08-25)\n------------------\nAdd date range picker\n\n0.3.6 (2016-06-29)\n------------------\nAdd multi select and date select widgets (thanks to @ryanbottema)\n\n0.3.5 (2016-06-22)\n------------------\nFix filtering and count queries for django-mssql\n\n0.3.3 (2015-04-12)\n------------------\n* Fix filtering of None values for SELECT fields\n\n0.3.1 (2015-02-25)\n------------------\n* Fix issue with boolean field filtering\n\n0.2.10 (2014-12-16)\n-------------------\n* Fix issue with pagination type\n\n0.2.9 (2014-12-15)\n------------------\n* Fix issue with namespaced urls\n\n0.2.6 (2014-10-30)\n------------------\n* add view args & kwargs to context to allow full reverse\n\n0.2.5 (2014-10-30)\n------------------\n* fix order_by\n\n0.2.0 (2014-10-29)\n------------------\n* Complete overhaul of api\n\n0.1.2 (2014-07-09)\n------------------\n* Fix saveState bug\n\n0.1.0 (2013-08-15)\n------------------\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A reusable Django app to make integrations with the DataTables javascript library easy.",
"version": "0.8.2",
"project_urls": {
"Homepage": "https://github.com/randlet/django-listable"
},
"split_keywords": [
"django-listable"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04802eaceb078cebf82359dcb042cd09806a97459e3cfb0cf952f1f91eee84b7",
"md5": "b39ef4d61045e9226316e9bc1795b09a",
"sha256": "694eff2cfb69a33e42dc745db0393bd0bf58238efe540a3c6340abd5de80492f"
},
"downloads": -1,
"filename": "django_listable-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b39ef4d61045e9226316e9bc1795b09a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 409012,
"upload_time": "2023-12-22T22:15:01",
"upload_time_iso_8601": "2023-12-22T22:15:01.678918Z",
"url": "https://files.pythonhosted.org/packages/04/80/2eaceb078cebf82359dcb042cd09806a97459e3cfb0cf952f1f91eee84b7/django_listable-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26d3e84020970158bd3dea793e69f7d815fd041f1830d7dad1018d2cf37e108b",
"md5": "d87c39f77941d8aabd890d408c056e2f",
"sha256": "5eeba60ea233748a6688b8758290e3effe6b5b2e78ed6b03730a8d7aa68abdb5"
},
"downloads": -1,
"filename": "django-listable-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "d87c39f77941d8aabd890d408c056e2f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 395490,
"upload_time": "2023-12-22T22:15:04",
"upload_time_iso_8601": "2023-12-22T22:15:04.246138Z",
"url": "https://files.pythonhosted.org/packages/26/d3/e84020970158bd3dea793e69f7d815fd041f1830d7dad1018d2cf37e108b/django-listable-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-22 22:15:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "randlet",
"github_project": "django-listable",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "django-listable"
}
JSON
