[1.5.X] Fixed #19120 - Added an example of using ModelAdmin methods for read-only fields.

Thanks Daniele Procida for the patch.

Backport of d1de7596b2 from master

1 files changed, 23 insertions, 4 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index b661806c76..f6da5b6cb2 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -816,15 +816,34 @@ subclass::
 
     By default the admin shows all fields as editable. Any fields in this
     option (which should be a ``list`` or ``tuple``) will display its data
-    as-is and non-editable. This option behaves nearly identical to
-    :attr:`ModelAdmin.list_display`. Usage is the same, however, when you
-    specify :attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets` the
-    read-only fields must be present to be shown (they are ignored otherwise).
+    as-is and non-editable. Note that when specifying :attr:`ModelAdmin.fields`
+    or :attr:`ModelAdmin.fieldsets` the read-only fields must be present to be
+    shown (they are ignored otherwise).
 
     If ``readonly_fields`` is used without defining explicit ordering through
     :attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets` they will be
     added last after all editable fields.
 
+    A read-only field can not only display data from a model's field, it can
+    also display the output of a a model's method or a method of the
+    ``ModelAdmin`` class itself. This is very similar to the way
+    :attr:`ModelAdmin.list_display` behaves. This provides an easy way to use
+    the admin interface to provide feedback on the status of the objects being
+    edited, for example::
+
+        class PersonAdmin(ModelAdmin):
+            readonly_fields = ('address_report',)
+
+            def address_report(self, instance):
+                return ", ".join(instance.get_full_address()) or \
+                   "<span class='errors'>I can't determine this address.</span>"
+
+            # short_description functions like a model field's verbose_name
+            address_report.short_description = "Address"
+            # in this example, we have used HTML tags in the output
+            address_report.allow_tags = True
+
+
 .. attribute:: ModelAdmin.save_as
 
     Set ``save_as`` to enable a "save as" feature on admin change forms.