Add 'help_text' property to methods in ModelAdmin.list_display

[Derek Hohls]

It would be helpful to allow for a help_text property to be supplied to a custom field in the admin.

For example:

from django.contrib import admin

class AuthorAdmin(admin.ModelAdmin):
    fields = ('name', 'title', 'view_birth_date')

    def view_birth_date(self, obj):
        return obj.birth_date

    view_birth_date.help_text = 'Authors birthday'

This help text could be displayed via a 'hover over' in the header(s) of the columns in the admin list display.

[ducdetronquito]

Hi,

I have made a Pull-Request for this ticket (Cf. ​https://github.com/django/django/pull/6880)

I am looking forward to have a review and made some changes if need be :)

[ducdetronquito]

Hi there,

I made some changes suggested by @profuel.
Now the PR passes all the tests \o/

Do not hesitate to tell me if something could be improved !

[Tim Graham]

I left some ideas for improvement on the PR.

[Guille López]

Since it has been a while since this problem it's posted and the required fixes of the sent PR seems stalled.... I'm taking ownership of it to send a new PR that covers the feature and the suggestions addressed in the old PR.

[Mariusz Felisiak <felisiak.mariusz@…>]

In fbe82f82:

Refs #26761 -- Removed extra space in admin change list result header.

[Mariusz Felisiak]

After reconsideration I think we shouldn't move it forward. First of all it's quite niche. Moreover adding title to the admin changelist headers only for callables will be really confusing. On the other hand using Field.help_text will cause many unexpected tooltips since it's used mainly for instructions of filling forms. title has also accessible concerns. In the end, this addition isn't worth the complexity.

[Derek Hohls]

After a 4 year wait, this is a disappointing response. I think its a fairly generally useful feature (not "niche") that allows custom fields similar functionality to original ones and enhances the admin.

Was the proposed patch not able to pass the required tests?

[Mariusz Felisiak]

Replying to Derek Hohls:

Was the proposed patch not able to pass the required tests?

It's not about tests, please take a look at my response.

[Hugo Osvaldo Barrera]

I think this ticket somehow manages to mix up two very different requests into one:

1. Add a help_text to methods:

from django.contrib import admin

class AuthorAdmin(admin.ModelAdmin):
    fields = ('name', 'date_of_birth', 'is_underage')

    def is_underage(self, obj):
        return obj.age < 18

    is_underage.help_text = 'Indicates if the author is under 18.'

2. Show help_text as a title in changelistheaders.

As far as I understand the reason to reject this feature request are that this second feature seems to niche (note: I agree on that).

On the other hand, help_text for method-fields seem to make perfect sense. They would be rendered on the changeform just like the help_text for any other readonly field.

They also don't seem niche at all, and align very well with the existing admin UX.

Do you think just the first item would be acceptable? Looks like the implementation can be extracted from #12309, excluding the changelist changes.

[Mariusz Felisiak]

Replying to Hugo Osvaldo Barrera:

On the other hand, help_text for method-fields seem to make perfect sense. They would be rendered on the changeform just like the help_text for any other readonly field.

They also don't seem niche at all, and align very well with the existing admin UX.

Do you think just the first item would be acceptable? Looks like the implementation can be extracted from #12309, excluding the changelist changes.

You can use short_description that already works for methods, that's more appropriate because you want to describe a value. help_text is rather an instruction for filling forms.

[Adam Johnson]

Carsten ​wrote to the mailing list asking the ticket to be reconsidered. This is my reply.

It’s already possible to return arbitrary rendered HTML for fields, so one can add "help text" that way. For example, using the internal "boolean icon" display from the admin and adding a paragraph of text below (untested!):

from django.contrib import admin
from django.contrib.admin.templatetags.admin_list import _boolean_icon
from django.utils.html import format_html


class AuthorAdmin(admin.ModelAdmin):
    fields = ("name", "date_of_birth", "is_underage")

    def is_underage(self, obj):
        return format_html(
            "{}<br><p>{}</p>",
            _boolean_icon(obj.age < 18),
            "Indicates if the author is under 18.",
        )

So I would be against making any change because complete customization is already possible. If you want terser syntax you can write a project-specific decorator that fits your needs.

[Carsten Fuchs]

Hello Adam, thanks for your reply!

I understand how this approach solves the problem, however it makes it difficult to achieve visual consistency with the genuine help_text attributes, because for that the Admin's HTML markup and styling must carefully be accounted for and be reproduced in format_html("…"). It also doesn't cover the double-use of the help_text in the tooltips in the table column headers on the list pages.

Using format_html() as you suggested properly covers my use case. I also understand that new features cannot be added lightheartedly to the Admin. However, it still feels to me that this is a (albeit small) piece of functionality that is missing.