Fixed #18658 -- Improved ModelAdmin.message_user API

Thanks to Lowe Thiderman for the patch and tests

3 files changed, 26 insertions, 4 deletions

diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt
index 3f3b52983b..d7eef623d5 100644
--- a/docs/ref/contrib/admin/actions.txt
+++ b/docs/ref/contrib/admin/actions.txt
@@ -140,6 +140,15 @@ That's really all there is to it! If you're itching to write your own actions,
 you now know enough to get started. The rest of this document just covers more
 advanced techniques.
 
+Handling errors in actions
+--------------------------
+
+If there are foreseeable error conditions that may occur while running your
+action, you should gracefully inform the user of the problem. This means
+handling exceptions and and using
+:meth:`django.contrib.admin.ModelAdmin.message_user` to display a user friendly
+description of the problem in the response.
+
 Advanced action techniques
 ==========================
 
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 9336ce174e..38668a0a2c 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1303,11 +1303,19 @@ templates used by the :class:`ModelAdmin` views:
                     return qs
                 return qs.filter(author=request.user)
 
-.. method:: ModelAdmin.message_user(request, message)
+.. method:: ModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False)
 
-    Sends a message to the user. The default implementation creates a message
-    using the :mod:`django.contrib.messages` backend. See the
-    :ref:`custom ModelAdmin example <custom-admin-action>`.
+    Sends a message to the user using the :mod:`django.contrib.messages`
+    backend.  See the :ref:`custom ModelAdmin example <custom-admin-action>`.
+
+    .. versionadded:: 1.5
+
+    Keyword arguments allow you to change the message level, add extra CSS
+    tags, or fail silently if the ``contrib.messages`` framework is not
+    installed. These keyword arguments match those for
+    :func:`django.contrib.messages.add_message`, see that function's
+    documentation for more details. One difference is that the level may be
+    passed as a string label in addition to integer/constant.
 
 .. method:: ModelAdmin.get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)
 
diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt
index 5d5902d45d..b73bb041e9 100644
--- a/docs/releases/1.5.txt
+++ b/docs/releases/1.5.txt
@@ -313,6 +313,11 @@ Django 1.5 also includes several smaller improvements worth noting:
   DeprecationWarnings should be printed to the console in development
   environments the way they have been in Python versions < 2.7.
 
+* The API for :meth:`django.contrib.admin.ModelAdmin.message_user` method has
+  been modified to accept additional arguments adding capabilities similar to
+  :func:`django.contrib.messages.add_message`. This is useful for generating
+  error messages from admin actions.
+
 Backwards incompatible changes in 1.5
 =====================================