Updates to README.

Version bump to 2.1.6

README.md

@@ -100,7 +100,6 @@ class MySortableClass(SortableMixin):
         ordering = ['the_order']
 
 
-
     # define the field the model should be ordered by
     the_order = models.PositiveIntegerField(default=0, editable=False, db_index=True)
 
@@ -429,6 +428,71 @@ which can make them difficult to sort. If you anticipate the height of a
 stacked inline is going to be very tall, I would suggest using
 SortableTabularInline instead.
 
+#### Custom JS callbacks after sorting is complete
+If you need to define a custom event or other callback to be executed after sorting is completed, you'll need to:
+
+1. Create a custom template for to add your JavaScript
+2. Populate the `after_sorting_js_callback_name` on your model admin
+
+An example of this can be found in the "samples" application in the source. Here's a model admin for a model called "Project":
+
+```python
+class ProjectAdmin(SortableAdmin):
+    inlines = [
+        CreditInline, NoteInline, GenericNoteInline,
+        NonSortableCreditInline, NonSortableNoteInline
+    ]
+    list_display = ['__str__', 'category']
+
+    after_sorting_js_callback_name = 'afterSortCallback'  # do not include () - just function name
+    sortable_change_list_template = 'adminsortable/custom_change_list.html'
+    sortable_change_form_template = "adminsortable/custom_change_form.html"
+```
+
+This example is going to add a custom callback on the parent model, and it's inlines. Here is the JavaScript added to the custom change list:
+
+```html+django
+{% extends 'adminsortable/change_list.html' %}
+
+{% block extrahead %}
+  {{ block.super }}
+
+  <script>
+    django.jQuery(document).on('order:changed', function(event) {
+      console.log(event.message);
+      // your code here
+    });
+
+    window['{{ after_sorting_js_callback_name }}'] = function() {
+      django.jQuery(document).trigger({ type: 'order:changed', message: 'Order changed', time: new Date() });
+    };
+  </script>
+{% endblock %}
+```
+
+and the custom change form, for the inline models:
+
+```html+django
+{% extends "adminsortable/change_form.html" %}
+
+{% block extrahead %}
+  {{ block.super }}
+
+  <script>
+    django.jQuery(document).on('order:changed', function(event) {
+      console.log(event.message);
+      // your code here
+    });
+
+    window['{{ after_sorting_js_callback_name }}'] = function() {
+      django.jQuery(document).trigger({ type: 'order:changed', message: 'Order changed', time: new Date() });
+    };
+  </script>
+{% endblock %}
+```
+
+Ideally, you'd pull in a shared piece of code for your callback to keep your code DRY.
+
 ### Django-CMS integration
 Django-CMS plugins use their own change form, and thus won't automatically
 include the necessary JavaScript for django-admin-sortable to work. Fortunately,
@@ -531,8 +595,8 @@ ordering on top of that just seemed a little much in my opinion.
 ### Status
 django-admin-sortable is currently used in production.
 
-### What's new in 2.1.5?
+### What's new in 2.1.6?
-- Support for Django Admin filters. Credit to [timur-orudzhov](https://github.com/timur-orudzhov).
+- Added inclusion of custom JavaScript callbacks after sorting is performed, if desired.
 
 ### Future
 - Better template support for foreign keys that are self referential. If someone would like to take on rendering recursive sortables, that would be super.

README.rst

@@ -1,7 +1,9 @@
 Django Admin Sortable
 =====================
 
-|PyPI version| |Python versions| |Build Status|
+`PyPI version <https://pypi.python.org/pypi/django-admin-sortable>`__
+`Python versions <https://pypi.python.org/pypi/django-admin-sortable>`__
+`Build Status <https://travis-ci.org/alsoicode/django-admin-sortable>`__
 
 This project makes it easy to add drag-and-drop ordering to any model in
 Django admin. Inlines for a sortable model may also be made sortable,
@@ -136,7 +138,6 @@ Sample Model:
            ordering = ['the_order']
 
 
-
        # define the field the model should be ordered by
        the_order = models.PositiveIntegerField(default=0, editable=False, db_index=True)
 
@@ -242,8 +243,8 @@ Backwards Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 If you previously used Django Admin Sortable, **DON’T PANIC** -
-everything will still work exactly as before ***without any changes to
+everything will still work exactly as before **without any changes to
-your code***. Going forward, it is recommended that you use the new
+your code**. Going forward, it is recommended that you use the new
 ``SortableMixin`` on your models, as pre-2.0 compatibility might not be
 a permanent thing.
 
@@ -542,6 +543,77 @@ make them difficult to sort. If you anticipate the height of a stacked
 inline is going to be very tall, I would suggest using
 SortableTabularInline instead.
 
+Custom JS callbacks after sorting is complete
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to define a custom event or other callback to be executed
+after sorting is completed, you’ll need to:
+
+1. Create a custom template for to add your JavaScript
+2. Populate the ``after_sorting_js_callback_name`` on your model admin
+
+An example of this can be found in the “samples” application in the
+source. Here’s a model admin for a model called “Project”:
+
+.. code:: python
+
+   class ProjectAdmin(SortableAdmin):
+       inlines = [
+           CreditInline, NoteInline, GenericNoteInline,
+           NonSortableCreditInline, NonSortableNoteInline
+       ]
+       list_display = ['__str__', 'category']
+
+       after_sorting_js_callback_name = 'afterSortCallback'  # do not include () - just function name
+       sortable_change_list_template = 'adminsortable/custom_change_list.html'
+       sortable_change_form_template = "adminsortable/custom_change_form.html"
+
+This example is going to add a custom callback on the parent model, and
+it’s inlines. Here is the JavaScript added to the custom change list:
+
+.. code:: html+django
+
+   {% extends 'adminsortable/change_list.html' %}
+
+   {% block extrahead %}
+     {{ block.super }}
+
+     <script>
+       django.jQuery(document).on('order:changed', function(event) {
+         console.log(event.message);
+         // your code here
+       });
+
+       window['{{ after_sorting_js_callback_name }}'] = function() {
+         django.jQuery(document).trigger({ type: 'order:changed', message: 'Order changed', time: new Date() });
+       };
+     </script>
+   {% endblock %}
+
+and the custom change form, for the inline models:
+
+.. code:: html+django
+
+   {% extends "adminsortable/change_form.html" %}
+
+   {% block extrahead %}
+     {{ block.super }}
+
+     <script>
+       django.jQuery(document).on('order:changed', function(event) {
+         console.log(event.message);
+         // your code here
+       });
+
+       window['{{ after_sorting_js_callback_name }}'] = function() {
+         django.jQuery(document).trigger({ type: 'order:changed', message: 'Order changed', time: new Date() });
+       };
+     </script>
+   {% endblock %}
+
+Ideally, you’d pull in a shared piece of code for your callback to keep
+your code DRY.
+
 Django-CMS integration
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -674,10 +746,3 @@ License
 ~~~~~~~
 
 django-admin-sortable is released under the Apache Public License v2.
-
-.. |PyPI version| image:: https://img.shields.io/pypi/v/django-admin-sortable.svg
-   :target: https://pypi.python.org/pypi/django-admin-sortable
-.. |Python versions| image:: https://img.shields.io/pypi/pyversions/django-admin-sortable.svg
-   :target: https://pypi.python.org/pypi/django-admin-sortable
-.. |Build Status| image:: https://travis-ci.org/alsoicode/django-admin-sortable.svg?branch=master
-   :target: https://travis-ci.org/alsoicode/django-admin-sortable

adminsortable/__init__.py

@@ -1,4 +1,4 @@
-VERSION = (2, 1, 5)
+VERSION = (2, 1, 6)
 DEV_N = None