From 1335aa2fb9f590d786a5baee1b781377dc3a2ec8 Mon Sep 17 00:00:00 2001
From: ramez <ramezashraf@gmail.com>
Date: Thu, 18 Jun 2015 19:27:58 +0300
Subject: Fixed #15760 -- Added JavaScript events for admin inline forms.

---
 docs/ref/contrib/admin/index.txt      |  3 ++
 docs/ref/contrib/admin/javascript.txt | 75 +++++++++++++++++++++++++++++++++++
 docs/releases/1.9.txt                 |  3 ++
 3 files changed, 81 insertions(+)
 create mode 100644 docs/ref/contrib/admin/javascript.txt

(limited to 'docs')

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 45f5e33df2..321c6d83ad 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -59,6 +59,7 @@ Other topics
 
    actions
    admindocs
+   javascript
 
 .. seealso::
 
@@ -1882,6 +1883,8 @@ The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends
 ``None``) to any asset paths. The same rules apply as :ref:`regular asset
 definitions on forms <form-asset-paths>`.
 
+.. _contrib-admin-jquery:
+
 jQuery
 ~~~~~~
 
diff --git a/docs/ref/contrib/admin/javascript.txt b/docs/ref/contrib/admin/javascript.txt
new file mode 100644
index 0000000000..f953b269ad
--- /dev/null
+++ b/docs/ref/contrib/admin/javascript.txt
@@ -0,0 +1,75 @@
+======================================
+JavaScript customizations in the admin
+======================================
+
+.. _admin-javascript-inline-form-events:
+
+Inline form events
+==================
+
+.. versionadded:: 1.9
+
+You may want to execute some JavaScript when an inline form is added or removed
+in the admin change form. The ``formset:added`` and ``formset:removed`` jQuery
+events allow this. The event handler is passed three arguments:
+
+* ``event`` is the ``jQuery`` event.
+* ``$row`` is the newly added (or removed) row.
+* ``formsetName`` is the formset the row belongs to.
+
+The event is fired using the :ref:`django.jQuery namespace
+<contrib-admin-jquery>`.
+
+In your custom ``change_form.html`` template, extend the
+``admin_change_form_document_ready`` block and add the event listener code:
+
+.. code-block:: html+django
+
+    {% extends 'admin/change_form.html' %}
+
+    {% block admin_change_form_document_ready %}
+    {{ block.super }}
+    <script type="text/javascript">
+    (function($) {
+        $(document).on('formset:added', function(event, $row, formsetName) {
+            if (formsetName == 'author_set') {
+                // Do something
+            }
+        });
+
+        $(document).on('formset:removed', function(event, $row, formsetName) {
+            // Row removed
+        });
+    })(django.jQuery);
+    </script>
+    {% endblock %}
+
+Two points to keep in mind:
+
+* The JavaScript code must go in a template block if you are inheriting
+  ``admin/change_form.html`` or it won't be rendered in the final HTML.
+* ``{{ block.super }}`` is added because Django's
+  ``admin_change_form_document_ready`` block contains JavaScript code to handle
+  various operations in the change form and we need that to be rendered too.
+
+Sometimes you'll need to work with ``jQuery`` plugins that are not registered
+in the ``django.jQuery`` namespace. To do that, simply change how the code
+listens for events. Instead of wrapping the listener in the ``django.jQuery``
+namespace, just listen to the event triggered from there. For example:
+
+.. code-block:: html+django
+
+    {% extends 'admin/change_form.html' %}
+
+    {% block admin_change_form_document_ready %}
+    {{ block.super }}
+    <script type="text/javascript">
+        django.jQuery(document).on('formset:added', function(event, $row, formsetName) {
+            // Row added
+        });
+
+        django.jQuery(document).on('formset:removed', function(event, $row, formsetName) {
+            // Row removed
+        });
+    </script>
+    {% endblock %}
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index f1eba56a1e..0bb1523f57 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -175,6 +175,9 @@ Minor features
   the display of empty values in admin change list. You can also customize the
   value for each field.
 
+* Added jQuery events :ref:`when an inline form is added or removed
+  <admin-javascript-inline-form-events>` on the change form page.
+
 * The time picker widget includes a '6 p.m' option for consistency of having
   predefined options every 6 hours.
 
-- 
cgit v1.3