WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 2 weeks ago

#43060 closed enhancement (fixed)

register taxonomy should accept a label to affect the description under each field on the Add Tag form

Reported by: mclaurent Owned by: SergeyBiryukov
Milestone: 5.9 Priority: normal
Severity: normal Version:
Component: Taxonomy Keywords: has-patch needs-dev-note
Focuses: administration Cc:

Description

Hi

When registering a custom taxonomy WordPress uses the default UI to allow content editors to manage terms in this taxonomy. The descriptions under the Tag name and Slug may in some cases not be adequate and/or require additionnal guidance. For instance when the names of tags should follow a certain convention or standard.
For instance for a Countries taxonomy we would wish to give the user information on what standard to follow (for instance ISO-3166-2).

I have attached images of what it currently looks like on the Add Tag page, and what it should look like in my opinion.

Since there are no hooks allowing to add extra information under the tag-name field on the edit-tags.php:393, I think the best place for this change would be at the time of register_taxonomy. I would suggest introducing new labels for a taxonomy which would overwrite the labels displayed under each field.

The implementation would then look something like this:

<?php
register_taxonomy( 'countries', 'post',array(
        'label' => __( 'Countries' ),
        'labels' => array(
                'name' => __( 'Countries' ),
                'singular_name' => __( 'Countries' ),
                'menu_name' => __( 'Countries' ),
                'all_items' => __( 'All Countries' ),
                'edit_item' => __( 'Edit Country' ),
                'view_item' => __( 'View Country' ),
                'update_item' => __( 'Update Country' ),
                'add_new_item' => __( 'Add New Country' ),
                'new_item_name' => __( 'New Country name' ),
                // The below would be used on the edit-tags.php:393
                'new_item_name_description' => __( 'This name should adhere to the ISO-3166-2 standard.' ),
                'parent_item' => __( 'Parent Country' ),
                'parent_item_colon' => __( 'Parent Country:' ),
                'search_items' => __( 'Search Countries' ),
                'popular_items' => __( 'Popular Countries' ),
                'separate_items_with_commas' => __( 'Separate Countries with commas' ),
                'add_or_remove_items' => __( 'Add or remove Countries' ),
                'choose_from_most_used' => __( 'Choose from the most used Countries' ),
                'not_found' => __( 'No Countries found' ),
        ),
        'public' => true,
));

Attachments (8)

country-taxonomy-currently.PNG (15.9 KB) - added by mclaurent 4 years ago.
The admin screen without custom term naming guidance
country-taxonomy-shouldbe.PNG (20.1 KB) - added by mclaurent 4 years ago.
The admin screen with custom term naming guidance giving specific information (and even links to relevant resources)
43060.diff (7.7 KB) - added by dontgo2sleep 3 years ago.
43060_proper.patch (7.0 KB) - added by dontgo2sleep 3 years ago.
43060.1.diff (6.6 KB) - added by audrasjb 2 months ago.
Taxonomy: Add new labels to register_taxonomy() to allow developers to override the description of each field.
43060.2.diff (6.4 KB) - added by peterwilsoncc 3 weeks ago.
43060.3.diff (9.4 KB) - added by SergeyBiryukov 3 weeks ago.
43060.4.diff (9.2 KB) - added by SergeyBiryukov 2 weeks ago.
Fix syntax errors, tweak the order for more consistency

Download all attachments as: .zip

Change History (34)

@mclaurent
4 years ago

The admin screen without custom term naming guidance

@mclaurent
4 years ago

The admin screen with custom term naming guidance giving specific information (and even links to relevant resources)

#1 follow-up: @swissspidy
4 years ago

  • Type changed from defect (bug) to enhancement

I don't see why a new label is needed for that. This can be a regular do_action() call in the edit tag form.

#2 in reply to: ↑ 1 @mclaurent
4 years ago

Replying to swissspidy:

I don't see why a new label is needed for that. This can be a regular do_action() call in the edit tag form.

Yeap that would work aswell. I thought it'd be cleaner to do it in the register_taxonomy as that is where the other labels are defined, too.

Last edited 4 years ago by mclaurent (previous) (diff)

#3 @johnbillion
4 years ago

  • Keywords needs-patch added
  • Version 4.9.1 deleted

I think it makes sense for these to be taxonomy labels.

#4 follow-up: @jeremyescott
4 years ago

Something that seems weird to me about the original example is that the 'new_item_name_description' doesn't replace but appends the default description. The suggestion seems to imagine a behavior more like a filter would than an action or a label.

Which begs the question, should plugin editors have the ability to remove the "the name how it appears on your site" message? I'd say, "yes".

That said, I'm not so sure this should be in the array. If we added this, why wouldn't we do the same for the other tags fields? So 'new_item_name_description', 'new_item_slug_description', and 'new_item_description_description'? And there we find the awkwardness of taking this one step forward... 'description_description'. :D

I think a filter would be most appropriate. My head isn't in the mode to think up a name, but a filter that is dynamic to the post type key, e.g.: taxonomy_$keyname_name_field_description, and taxonomy_$keyname_description_field_description, etc.

#5 in reply to: ↑ 4 @theMikeD
4 years ago

I'd also like these to be part of the taxonomy declaration. And...

Replying to jeremyescott:

That said, I'm not so sure this should be in the array. If we added this, why wouldn't we do the same for the other tags fields? So 'new_item_name_description', 'new_item_slug_description', and 'new_item_description_description'? And there we find the awkwardness of taking this one step forward... 'description_description'. :D

I think a filter would be most appropriate. My head isn't in the mode to think up a name, but a filter that is dynamic to the post type key, e.g.: taxonomy_$keyname_name_field_description, and taxonomy_$keyname_description_field_description, etc.

...adding "_field" in there just to avoid "_description_description" is superfluous IMO.

#6 follow-up: @jeremyfelt
3 years ago

  • Keywords good-first-bug added

I think it makes sense to add these as part of taxonomy registration to encourage adapting the text for specific needs.

The possibility of new_item_description_description is a little strange, but we've probably seen stranger. :)

Adding good-first-bug to this as I think an initial patch will be relatively straight forward.

#7 @dontgo2sleep
3 years ago

I am on it!

@dontgo2sleep
3 years ago

#8 @dontgo2sleep
3 years ago

  • Keywords has-patch added; needs-patch removed

This ticket was mentioned in Slack in #core by sergey. View the logs.


4 months ago

#10 @SergeyBiryukov
4 months ago

  • Milestone changed from Awaiting Review to 5.9
  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

#11 @audrasjb
2 months ago

  • Keywords needs-refresh added

@audrasjb
2 months ago

Taxonomy: Add new labels to register_taxonomy() to allow developers to override the description of each field.

#12 @audrasjb
2 months ago

  • Keywords needs-testing added; good-first-bug needs-refresh removed

In 43060.1.diff I refreshed the previous patch and removed the use of esc_html as it is not needed here, and since it would not allow developers to use any bit of HTML markup. And I'm quite sure a description could contains some links to helpful resources (like formatting instructions, etc).

This ticket was mentioned in Slack in #core-test by hellofromtonya. View the logs.


4 weeks ago

#14 @Boniu91
4 weeks ago

  • Keywords has-testing-info added

Testing instructions

  1. Register new taxonomy using the code provided in the thread
  2. Use the following labels to mapnipulate the output: name_description parent_description slug_description description_description
  3. In the labels, use HTML markups like links, images, bolds, etc. to see how it behaves
  4. Confirm that the labels are printed correctly

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


3 weeks ago

#16 @audrasjb
3 weeks ago

  • Keywords commit added; needs-testing has-testing-info removed

As per today's bug scrub, this patch looks good to go. Marking for commit consideration.

#17 @peterwilsoncc
3 weeks ago

  • Keywords needs-refresh added; commit removed

I'm seeing some coding standards errors in 43060.1.diff so removing the commit keyword while I set up a fix.

#19 @peterwilsoncc
3 weeks ago

  • Keywords commit added

43060.2.diff is 43060.1.diff with four additional spaces.

#20 @peterwilsoncc
3 weeks ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 52094:

Taxonomy: Change some static strings to registration labels.

Add additional label options to register_taxonomy() to allow developers further flexibility for customizing the edit taxonomy screen.

Props mclaurent, swissspidy, johnbillion, jeremyescott, theMikeD, jeremyfelt, dontgo2sleep, SergeyBiryukov, audrasjb, Boniu91.
Fixes #43060.

#22 in reply to: ↑ 6 @SergeyBiryukov
3 weeks ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Replying to jeremyfelt:

The possibility of new_item_description_description is a little strange, but we've probably seen stranger. :)

I didn't quite like description_description, so I would like to propose some tweaks here:

  • The descriptions are technically not for the term name, slug, etc. itself, but for the Name field, Slug field, etc. So I would suggest these for clarity:
    • name_field_description
    • slug_field_description
    • parent_field_description
    • desc_field_description
  • Including those long strings in the array like that makes it hard to see if they are the same or different for hierarchical and non-hierarchial taxonomies. I would suggest assigning them to variables first, to make it clear that they are the same for both types of taxonomies, with the exception of parent_field_description.
  • These new labels need inline documentation and a @since note.

See 43060.3.diff.

#23 @peterwilsoncc
3 weeks ago

  • Keywords needs-patch added; has-patch commit removed

Keyword admin to keep workflow in order.

#24 @SergeyBiryukov
3 weeks ago

  • Keywords has-patch added; needs-patch removed

There is a patch :)

#25 @audrasjb
3 weeks ago

  • Keywords needs-dev-note added

@SergeyBiryukov
2 weeks ago

Fix syntax errors, tweak the order for more consistency

#26 @SergeyBiryukov
2 weeks ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 52163:

Taxonomy: Clarify the taxonomy labels for customizing the field descriptions on Edit Tags screen:

  • Update the label names to make it clear that these descriptions are not for the term name or slug itself, but for the Name, Slug, Parent, and Description fields:
    • name_field_description
    • slug_field_description
    • parent_field_description
    • desc_field_description
  • Update the array structure to make it clear that the default values for these labels are the same for both hierarchical and non-hierarchical taxonomies, with the exception of parent_field_description.
  • Add documentation and a @since note for the new labels.

Follow-up to [52094].

Fixes #43060.

Note: See TracTickets for help on using tickets.