This release makes a number of changes for the benefit of flexibility and future development.
utils.get_datatable_structure() and DatatableStructure
Unfortunately, I made a decision to reverse the 2nd and 3rd arguments of this utility function. The only reason the model class was being sent to the utility at all was because of certain default conditions that, if options weren't specified (like a column list, or the preferred ordering), the internals could look up those details and fill them in.
The reality was that supplying the model here was 9 times out of 10 not required. The argument has been moved to the end of the parameter list, and now accepts ``None`` as a default value, making the signature:
python
get_datatable_structure(ajax_url, options, model=None)
The constructor to the internal context variable object ``DatatableStructure`` matches this signature.
Helpers
* ``format_date``: This helper used to have trouble with columns that were ``null=True``, and would likely raise an error, worse even when the ``localize=True`` argument was set. The helper now aborts sooner in its rendering process if the value is ``None``, returning the blank string.
* ``through_filter``: A new helper that takes a simple callable mapping function (e.g., takes one argument, returns a new value), wrapping that target function so that it is compatible with use as a column callback. Django template filters are good examples of target functions. These can not be used directly as callbacks because they don't accept extra ``**kwargs`` that get sent by the caller. This helper swallows those extra arguments so that the target function can do its work.
* ``itemgetter`` and ``attrgetter``: While still convenient shorthand, these aren't strictly necessary anymore. ``through_filter`` can wrap the built-in ``operator.itemgetter`` and ``operator.attrgetter`` and accomplish the same thing. ``itemgetter`` still supports an ``ellipsis="..."`` argument, but more robust behavior can probably be found using ``through_filter(django.template.defaultfilters.truncatechars)``.
datatableview.js
Automatic initialization of tables via a jQuery ``document.ready`` event is still enabled by default, but it can be turned off via a global object property. If the following is executed after you include the ``datatableview.js`` file, but before the jQuery ready handler, no tables will be initialized:
javascript
datatableview.auto_initialize = false;
In this scenario, you can do late initialization and option declaration on your own, using the same global object:
javascript
var datatableOptions = {};
datatableview.initialize($(".mytable"), datatableOptions);
Note that all of the configuration options specified on the view are represented on the DOM in ``data-*`` attributes. dataTables.js doesn't actually support these, but this ``datatableview.initialize`` function does. This method of late binding can also replace the need to use the global javascript hook ``confirm_datatable_options`` to specify options for tables that were previously being auto-initialized.
Bootstrap integration
To make your life slightly easier, we've included a new template fragment at ``datatableview/bootstrap_structure.html``. This inclusion template simply adds the Bootstrap-esque ``table striped-table bordered-table`` classes to the main ``<table>`` tag.
To use this template, you can either specify on your view's options ``datatable_options["structure_template"] = "datatableview/bootstrap_structure.html"``, or you can copy the contents of this file into your own overridden ``"datatableview/default_structure.html"`` as a starting point for customization.
Tests
This release adds a set of tests for the ``helpers`` and ``utils`` modules, and for the new example project's views.
Example project
http://django-datatable-view.appspot.com/ — This is a public instance of the new example project, which includes live demos, descriptions, and short code examples.
The goal of this example project is to replace the incredibly long-winded README that was previously the only real information resource. While a Django-powered example project might feel more annoying to set up, it's the only way to provide actual live demos, instead of faking them and defeating the purpose of the exercise.
The new example project is included as part of the ``datatableview.tests`` module. The easiest way to get it running on your own machine is to do something like this:
bash
$ git clone https://github.com/pivotal-energy-solutions/django-datatable-view.git
$ cd django-datatable-view
$ mkvirtualenv datatableview
(datatableview)$ pip install -r requirements.txt
(datatableview)$ datatableview/tests/example_project/manage.py syncdb
(datatableview)$ datatableview/tests/example_project/manage.py runserver
This downloads the latest code, uses virtualenvwrapper to set up a new environment, and installs the basic requirements for the project (Django and python-dateutil). After that, it's just a matter of sync-ing the sqlite3 database and running the dev server.
Smaller things
Less important for the average use cases, but maybe good to know:
* Detection of the default column value sent to a helper has been improved. If values were ``False``-like, they were sometimes ignored as not being present, which led to the helper trying to act upon the row's instance as a fallback value. This usually didn't produce an intuitive result.
* Due to the above point, the ``key`` argument to a few of the helpers is facing removal sometime in the future.
* Minor parameter-passing bug with the new ``make_xeditable`` helper.
* Added a utility that normalizes field definitions to an internal format. Unless there was a lot of modification of the ``DatatableView``'s internal methods for deriving column data, this change shouldn't have an outward impact.
* Fixed bug concerning default "show all columns" mode and no data appearing in the rows
* Fixed bug that prevented the same field from being represented in multiple columns. The field was reduced to a dictionary mapping to column definitions, which resulted in dropping one at random. All column definitions are now properly respected.
* Fixed bug with Django < 1.5 versions using the ``XEditableDatatableView``. The asynchronous ajax updates failed due to the use of a Django 1.5 ``update_fields`` parameter to the ``save()`` method. Django 1.5 will still attempt to use this option, but older versions will not.
* Fixed bug with status code in ``make_xeditable`` responses.