Add `search_help_text` to `admin.ModelAdmin`

[Caram]

The admin changelist_view has a search box, but the user does not know which fields will be searched. They can only find out by trial and error.

There is a need for users to know which fields will be searched.

This patch ​https://github.com/django/django/pull/14117 adds a new search_help_text field to ModelAdmin that will display a help text below the search bar.

[Virtosu Bogdan]

This would have been useful a lot of times. Thank you!
It would work well the way it's implemented now, but I have a couple of minor suggestions/questions.

The default could be something like "Search by <search field labels>" and you can opt out or change the text yourself by defining search_help_text. I guess this depends on how many people would find this useful.
Couldn't the placeholder attribute on input be used for it ? It seems to be a common pattern and then changing the default behavior would be even less disruptive.

[Carlton Gibson]

Maybe the placeholder idea (and disabling) is worth looking at, but the basic idea from the screenshot seems nice enough, so let's accept.

Caram, I didn't look at the patch in detail yet, but do go over the patch review checklist that was linked in the comment on the PR. Look at the naming, which should begin Fixed #32543 -- ... which let's us auto-link back to the PR from here, and other similar conveniences. 🙂

[Nick Pope]

This is a good idea, I too have often wondered what I am able to search by.

The current implementation in the PR is only allowing some free-form text to be set. I think it can be useful to allow this, but the default should be to create a @property on the base class that uses the contents of search_fields. This will require looking up the verbose_name on the model's field based on the value in search_fields.

My concern about not doing this in an automated way by default is that search_fields will become out of sync with search_help_text which will be a worse situation than the status quo.

The placeholder idea element is nice, but if there are more than about 3 fields we'll not be able to see the entire placeholder. Again, perhaps more misleading than helpful.

[Caram]

Thanks @Hasan!

[Mariusz Felisiak <felisiak.mariusz@…>]

In 1143f3b:

Fixed #32543 -- Added search_help_text to ModelAdmin.