WordPress.org

Make WordPress Core

Opened 2 years ago

Last modified 7 months ago

#19780 new enhancement

Named category functions/docs need cleaning up

Reported by: DrewAPicture Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: Taxonomy Keywords: has-patch
Focuses: Cc:

Description (last modified by helenyhou)

Spawning from a small discussion in #19776, I think it's about time something is done to deal with the older named category functions such as wp_category_dropdown and wp_list_categories in category-template.php

These functions aren't technically category-only as they accept a set $taxonomy. And because they are actually taxonomy-agnostic, I think we have a few different routes we can take to clean up after ourselves a bit:

A) Lock down these functions to 'categories'-only in favor of new, taxonomy-agnostic ones.

B) Leave the functions alone but let the inline-docs and hard-coded strings such as 'No Categories' reflect their versatility. e.g. 'No Terms' vs 'No Categories'.

C) Deprecate these older functions in deference to newer, taxonomy-agnostic ones.

Attachments (3)

19780.diff (1.8 KB) - added by evansolomon 22 months ago.
19780.2.diff (1.8 KB) - added by evansolomon 22 months ago.
Fixes gramatical typos. Props helenyhou
19780.3.diff (8.7 KB) - added by lkwdwrd 9 months ago.

Download all attachments as: .zip

Change History (12)

comment:1 DrewAPicture2 years ago

Sorry, should be #19776. Can somebody modify the description? Edit: Thanks, helenyhou

Last edited 2 years ago by DrewAPicture (previous) (diff)

comment:2 helenyhou2 years ago

  • Description modified (diff)

evansolomon22 months ago

comment:3 evansolomon22 months ago

19780.diff adds wp_dropdown_terms() and wp_list_terms() as wrappers for their respective "category" functions. It doesn't deprecate the existing functions or change their behavior, it just adds the new ones.

The main benefit here is making it easier for people to find the functions that do what they want. For example, when looking for a function to list terms I didn't realize that I could pass a taxonomy to wp_list_categories(), which was frustrating for a while.

comment:4 helenyhou22 months ago

  • Keywords has-patch added

evansolomon22 months ago

Fixes gramatical typos. Props helenyhou

comment:5 Offereins17 months ago

I'd prefer this rewrite to taxonomy-agnostic behaviour to be more complete. Therefor also the filters (like list_cats, wp_list_cats, wp_dropdown_cats) and the filters in the Walker classes should be rewritten to a taxonomy-agnostic style. Additionally 1) the list_cats filter in the Walker classes would do great when sending the $args variable as third parameter and 2) we might not wrap each list item with an <a> tag by default; I could think of use cases where I would want to set a custom href attribute on it or don't use an <a> tag at all (@see Walker_Category::start_el()).

Concerning the wp_dropdown_terms and wp_list_terms solutions, I'd say they'd be better off the other way around, as the base of the category functions instead of the wrapper type like it's suggested in 19780.diff. This would result in wp_dropdown_categories being a wrapper for wp_dropdown_terms etc.

Last edited 17 months ago by Offereins (previous) (diff)

lkwdwrd9 months ago

comment:6 lkwdwrd9 months ago

Ran into this the other day. wp_dropdown_categories is a misnomer, and should really be a wrapper for something like wp_dropdown_terms to make it more clear. Same with wp_list_categories and wp_list_terms. Finished patching for wp_dropdown_terms, and I will continue working on wp_list_terms when I have a chance, but I figure I'll post what I've got so far so others can give feedback if desired.

comment:7 lkwdwrd9 months ago

  • Cc lkwdwrd added

comment:8 DrewAPicture9 months ago

Now, 19780.3.diff is what I call a great first patch! (wcpdx contributor day)

comment:9 ramiy7 months ago

Related #16677

Note: See TracTickets for help on using tickets.