Add option filter for wp_dropdown_categories()

[theMikeD]

I have a case in which I have a two-level hierarchical taxonomy. The only way to enforce this two-level hierarchy is to filter the parent list to top/parent terms only.

For example, given this

parent term 1
    child term 11
    child term 12
parent term 2
    child term 21

the only terms that should show up in the 'Parent' list would be parent term 1 and parent term 2

On the term edit screen, this is handled by using the taxonomy_parent_dropdown_args and quick_edit_dropdown_pages_args filters to add the depth parameter, which works great for this purpose.

But I can't do this for the list presented when a new term is added in the post-edit screen because a similar filter does not exist in wp_dropdown_categories() (the function that creates the list in the post edit screen). This in turn means that I have to create a new metabox from scratch, with a custom walker and an almost verbatim copy of post_categories_meta_box() function just to add this parameter into the args sent to wp_dropdown_categories() which is an ugly hacky workaround.

So lets be consistent and add the new filter.

[theMikeD]

Patch for 33026

[theMikeD]

Patch 2 is updated to use a single argument. Works great in testing.

[theMikeD]

As far a writing a test for this goes, is it enough to test the modification of a single element to prove it works? Or must every option be modified and tested? Feels like I'm talking to myself a bit here :)

[boonebgorges]

Thanks for the patch, theMikeD. A general filter on the args in wp_dropdown_categories() is probably too general an solution here. Elsewhere in the Dashboard interface, we filter the arguments *before* they're passed to wp_dropdown_categories() (that's what 'taxonomy_parent_dropdown_args' etc do), so for consistency, let's do the same thing here. https://core.trac.wordpress.org/browser/tags/4.2.2/src/wp-admin/includes/meta-boxes.php?marks=504#L488

If it's put there, I'd say a better filter name is 'post_edit_category_parent_dropdown_args'.

[theMikeD]

No problem. Hows this?

[boonebgorges]

Thanks, theMikeD. A couple notes on the documentation:

• Short description should be in the third-person. "Filters" instead of "Filter".
• Needs a @since 4.4.0 annotation.
• Don't document every possible argument accepted by wp_dropdown_categories(). The only values passed to the filter are those in the $parent_dropdown_args array.

[theMikeD]

Replying to boonebgorges:

• Short description should be in the third-person. "Filters" instead of "Filter".

This was copied from the docbloc above. Should I fix it there too?

• Needs a @since 4.4.0 annotation.

I didn't want to be presumptive :) I'll add this.

• Don't document every possible argument accepted by wp_dropdown_categories(). The only values passed to the filter are those in the $parent_dropdown_args array.

I'll do this now. Thanks for the help.

[boonebgorges]

This was copied from the docbloc above. Should I fix it there too?

No, leave it where it already exists. DrewAPicture, could you please verify the recommended style here? See eg [33231]. We should have better documentation about this in ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-actions-and-filters.

[theMikeD]

Patch added. Note that I also changed

 * @param string|array $parent_dropdown_args {
 *     Optional. Array or string of arguments to generate a categories drop-down element.

to

 * @param array $parent_dropdown_args {
 *     Optional. Array of arguments to generate a categories drop-down element.

since it takes an array built in the immediately previous line.

[theMikeD]

Is it proper for me to change it to has-patch when I submit a new one? Is that the correct flow here?

[boonebgorges]

This looks good to me. Thanks!

Is it proper for me to change it to has-patch when I submit a new one? Is that the correct flow here?

Yes, that works.

[theMikeD]

Any chance this can make it into 4.3.1? 4.4 seems like a long way off :)

[boonebgorges]

Nope, 4.4 it is :)

[boonebgorges]

In 33682:

Filter the arguments passed to wp_dropdown_categories() in the Categories post edit metabox.

The new 'post_edit_category_parent_dropdown_args' provides parity with other
places in wp-admin where wp_dropdown_categories() args are filtered, such as
'taxonomy_parent_dropdown_args'.

Props theMikeD.
Fixes #33026.

[DrewAPicture]

In 33686:

Docs: Fix some minor inline documentation syntax issues in the hook docs for the post_edit_category_parent_dropdown_args filter, introduced in [33682].

See #32246. See #33026.

[theMikeD]

So once this is tagged as 4.4, it's included by default right? Is there anything else I should be doing?

[boonebgorges]

Replying to theMikeD:

So once this is tagged as 4.4, it's included by default right? Is there anything else I should be doing?

The filter was added in [33682], and it'll ship as part of 4.4 in a couple of weeks. Your work here is done :)