add bypass filter to remove months dropdown on post table

[norcross]

currently the months_dropdown function has a filter months_dropdown_results that can be used to remove the results (and thus hide the dropdown) but the SQL query is still run. this patch adds a filter to simply bypass the entire process (including post type to target specific types but allow others) and avoid running the query

[norcross]

the filter (including docblocks) to bypass the dropdown query and return

[mordauk]

+1

[travisnorthcutt]

+1

[tyxla]

+1

[markjaquith]

Works for me. Do we use the include_* naming convention elsewhere, or do we have a convention for filters that enable/disable things?

[DrewAPicture]

Replying to markjaquith:

Works for me. Do we use the include_* naming convention elsewhere, or do we have a convention for filters that enable/disable things?

We have a few what I call "boolean" filters with an "enable_" prefix on them. It helps to use a naming convention that is "positive" so that when we check if it's enabled/disabled it doesn't end up as a double negative, e.g. false === disable_*.

[norcross]

updated patch to change the filter name

[norcross]

updated patch to change the filter name (again) and doc block title

[GaryJ]

• Periods needed at the end of the summary, and @param descriptions.
• Optional param tag should also be indicated with the one-word sentence Optional. at the start of the description, per ​https://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/#1-functions-and-class-methods.
• First param also needs a named variable in it, which you can make up - can be (often?) is the name of the filter itself e.g. @param bool $hide_months_dropdown

[norcross]

updated docblock formatting per WP standards

[DrewAPicture]

Some notes on improving 30254.4.patch​:

• Add a version to the @since, probably 4.2.0
• Looks like the indentation is off on the line following @since
• Hook docs don't use @return as the first parameter is the return. So in this case, you could actually just use the @return description for the first parameter.
• Hook docs can't have "Optional" parameters. You can mention in the $post_type parameter description that it is optionally passed to the parent function, but otherwise remove the "Optional." sentence at the beginning

[norcross]

@GaryJ and @DrewAPicture - can you two decide which one it is for the optional context?

regarding the @return portion, it's a filter, not a hook (not sure if that matters).

also, I didn't add a @since because I don't know when it will get added. I would say 4.1 would be a good fit....but that's just me.

[norcross]

even BETTER DocBlocks. who doesn't like a good DocBlock, am I right?

[DrewAPicture]

Sorry this got confusing.

• All filters are hooks just the same as all actions are hooks.
• Parameters in hook docs can't be marked optional because that's a misnomer -- the value is always passed to the primary instance of the hook, optional or not.
• Adding a version now is no problem, most committers will happily fix it on commit.

[GaryJ]

On all things inline-docs, I defer to Drew for the official and correct advice. In this case, all data args for action and filter hooks are optional in that the customising function uses them or not, but they are always passed, so there's no need to document as Optional.. My point was on how to document optional args for functions, and I'd overlooked this was a hook, so my suggestion was somewhat irrelevant here.

This is going to be too late for 4.1, as we're in string freeze, past a couple of betas and approaching release sometime this week I believe.

[rmccue]

Replying to GaryJ:

This is going to be too late for 4.1, as we're in string freeze, past a couple of betas and approaching release sometime this week I believe.

I don't think string freeze matters too much in this instance, but enhancements in general (including new filters) are too late.

[iseulde]

has-patch 4.2-early so moving to 4.2.

[helen]

Couple nitpicks - we tend to use truthy/falsey checks on these (so ! apply_filters() or vice versa), and I think using enable/disable terminology would be more descriptive, as one of the goals is to avoid the query. No opinion at the moment which of those it should be.

[norcross]

Replying to helen:

Couple nitpicks - we tend to use truthy/falsey checks on these (so ! apply_filters() or vice versa), and I think using enable/disable terminology would be more descriptive, as one of the goals is to avoid the query. No opinion at the moment which of those it should be.

I'm totally fine with changing the verbiage and going truthy / falsey with it. just lemme know what y'all prefer and I'll update the patch.

[SergeyBiryukov]

30254.6.patch​ switches to 'disable' terminology and makes some minor adjustments.

[norcross]

Replying to SergeyBiryukov:

30254.6.patch​ switches to 'disable' terminology and makes some minor adjustments.

so is this good to go, or is anything additional needed from me?

[SergeyBiryukov]

Should be good to go, just wanted a second look from @DrewAPicture and @helen.

[helen]

In 31438:

Posts list table: Add a filter to disable the months dropdown.

It was previously possible to prevent it from displaying by filtering everything out from the results, but if one really doesn't want it, they should be able to short-circuit before the query even runs.

props norcross, SergeyBiryukov.
fixes #30254.