Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

readonly_fields documentation amended ticket #19120 #459

Closed
wants to merge 2 commits into from

2 participants

@jaddison

EDIT: scratch that - I see the changes in your next commit! ;)

You've got "specifying specify" in the sentence now, due to your change. Read through the resulting text to make sure it makes grammatical and contextual sense.

@evildmp
Collaborator

I squashed these two commits into one, at #468. I've closed this pull request.

@evildmp evildmp closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 25 additions and 6 deletions.
  1. +25 −6 docs/ref/contrib/admin/index.txt
View
31 docs/ref/contrib/admin/index.txt
@@ -179,8 +179,6 @@ subclass::
values defined in :attr:`ModelAdmin.readonly_fields` to be displayed as
read-only.
- .. versionadded:: 1.4
-
To display multiple fields on the same line, wrap those fields in their own
tuple. In this example, the ``url`` and ``title`` fields will display on the
same line and the ``content`` field will be displayed below them in its
@@ -807,14 +805,35 @@ 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 function, or a model's method, or a method of
+ the ``ModelAdmin`` class itself, if these are declared in
+ ``readonly_fields``. This is very similar to the way
+ :attr:`ModelAdmin.list_display` behaves.
+
+ This provides an effective and 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',)
+
+ # instance is the instance of the model we are editing
+ def address_report(self, instance):
+ return "%s" % (", ".join(instance.get_full_address)) or "<span class='errors'>Warning: I can't determine this person's address.</span>"
+
+ # the 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
Something went wrong with that request. Please try again.