Opened 8 years ago

Closed 4 years ago

Last modified 10 months ago

#26761 closed New feature (wontfix)

Add 'help_text' property to methods in ModelAdmin.list_display

Reported by: Derek Hohls Owned by: Hasan Ramezani
Component: contrib.admin Version: dev
Severity: Normal Keywords:
Cc: Guille López, Carlton Gibson, Carsten Fuchs Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Tim Graham)

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.

Change History (22)

comment:1 by Tim Graham, 8 years ago

Description: modified (diff)
Keywords: admin removed
Summary: Admin - add 'help_text' property to custom fieldsAdd 'help_text' property to methods in ModelAdmin.list_display
Triage Stage: UnreviewedAccepted

comment:2 by ducdetronquito, 8 years ago

Owner: changed from nobody to ducdetronquito
Status: newassigned

comment:3 by ducdetronquito, 8 years ago

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 :)

comment:4 by Tim Graham, 8 years ago

Has patch: set

comment:5 by ducdetronquito, 8 years ago

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 !

comment:6 by Tim Graham, 7 years ago

Patch needs improvement: set

I left some ideas for improvement on the PR.

comment:7 by Guille López, 5 years ago

Owner: changed from ducdetronquito to Guille López
Version: 1.9master

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.

comment:8 by Guille López, 5 years ago

Cc: Guille López added

comment:9 by Hasan Ramezani, 4 years ago

Owner: changed from Guille López to Hasan Ramezani

comment:10 by Hasan Ramezani, 4 years ago

Patch needs improvement: unset
Last edited 4 years ago by Mariusz Felisiak (previous) (diff)

comment:11 by Mariusz Felisiak, 4 years ago

Needs tests: set
Patch needs improvement: set

comment:12 by Hasan Ramezani, 4 years ago

Needs tests: unset
Patch needs improvement: unset

comment:13 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In fbe82f82:

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

comment:14 by Mariusz Felisiak, 4 years ago

Resolution: wontfix
Status: assignedclosed
Triage Stage: AcceptedUnreviewed

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.

comment:15 by Derek Hohls, 4 years ago

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?

in reply to:  15 comment:16 by Mariusz Felisiak, 4 years ago

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.

comment:17 by Carlton Gibson, 4 years ago

Cc: Carlton Gibson added

comment:18 by Hugo Osvaldo Barrera, 4 years ago

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.'
  1. 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.

in reply to:  18 comment:19 by Mariusz Felisiak, 4 years ago

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.

comment:20 by Carsten Fuchs, 10 months ago

Cc: Carsten Fuchs added

comment:21 by Adam Johnson, 10 months ago

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.

comment:22 by Carsten Fuchs, 10 months ago

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.

Note: See TracTickets for help on using tickets.
Back to Top