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

[mclaurent]

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,
));

[mclaurent]

The admin screen without custom term naming guidance

[mclaurent]

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

[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.

[mclaurent]

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.

[johnbillion]

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

[jeremyescott]

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.

[theMikeD]

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.

[jeremyfelt]

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.

[dontgo2sleep]

I am on it!

[audrasjb]

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

[audrasjb]

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

[Boniu91]

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

[audrasjb]

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

[peterwilsoncc]

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

https://core.trac.wordpress.org/ticket/43060#comment:17

[peterwilsoncc]

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

[peterwilsoncc]

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.

https://core.trac.wordpress.org/changeset/52094

[SergeyBiryukov]

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-hierarchical 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​.

[peterwilsoncc]

Keyword admin to keep workflow in order.

[SergeyBiryukov]

There is a patch :)

[SergeyBiryukov]

Fix syntax errors, tweak the order for more consistency

[SergeyBiryukov]

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.

[audrasjb]

Dev note published: ​https://make.wordpress.org/core/2021/12/13/posts-post-types-and-taxonomy-changes-in-wordpress-5-9/

[SergeyBiryukov]

#52462 was marked as a duplicate.

[SergeyBiryukov]

#52462 was marked as a duplicate.