WordPress.org

Make WordPress Core

Opened 3 years ago

Last modified 3 months ago

#19780 new enhancement

Named category functions/docs need cleaning up

Reported by: DrewAPicture Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Taxonomy Keywords: has-patch needs-refresh needs-unit-tests
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 2 years ago.
19780.2.diff (1.8 KB) - added by evansolomon 2 years ago.
Fixes gramatical typos. Props helenyhou
19780.3.diff (8.7 KB) - added by lkwdwrd 11 months ago.

Download all attachments as: .zip

Change History (15)

comment:1 DrewAPicture3 years ago

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

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

comment:2 helenyhou3 years ago

  • Description modified (diff)

evansolomon2 years ago

comment:3 evansolomon2 years 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 helenyhou2 years ago

  • Keywords has-patch added

evansolomon2 years ago

Fixes gramatical typos. Props helenyhou

comment:5 Offereins19 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 19 months ago by Offereins (previous) (diff)

lkwdwrd11 months ago

comment:6 lkwdwrd11 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 lkwdwrd11 months ago

  • Cc lkwdwrd added

comment:8 DrewAPicture11 months ago

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

comment:9 ramiy10 months ago

Related #16677

comment:10 wonderboymusic3 months ago

#19776 was marked as a duplicate.

comment:11 wonderboymusic3 months ago

  • Keywords needs-refresh needs-unit-tests added
  • Milestone changed from Awaiting Review to Future Release

If anyone wants to work on this, could be a 4.0 thing

comment:12 DrewAPicture3 months ago

I want to work on this. :-)

Note: See TracTickets for help on using tickets.