billerickson/display-posts-shortcode — pull request #77 by DrewAPicture (2014-09-07 22:15:15+00:00)
Title: Add date_query support

As requested in #38, this PR implements date_query support for a single date query.

This would be considered "phase 1" with the option to later add support for incremented (multiple) date queries. The reasoning for not including multiples with this PR, is that while the logical progression is to move to supporting multiples in the future, it would probably be best to first nail down the best approach to implementing a single date query in terms of attribute naming and architecture :)

Note: In the attribute descriptions below, you'll notice that I reference the "top-level" and "second-level" areas of the date query. Top-level arguments serve in a "global" capacity to all date queries contained on the second-level. The actual individual date queries are defined on the second-level of the associative array.

This introduces a total of 8 new attributes (yikes, I know):
* `date`
— Serves as a shortcut to setting the 'year', 'month', and 'day' arguments for a given date query struct on the second-level. It accepts either a strictly-formatted 'YYYY-MM-DD' date string or a relative-formatted date string, such as 'Sunday, September 7'. The relative-formatted string is intended as a fallback for the easier-to-sanitize 'YYYY-MM-DD' formatted string and could prove fickle when supplied with too little information.

* `date_column`
— The first of two top-level arguments, this serves as the "global" column to query for all date queries in the associative date query arrays on the second-level. This defaults to 'post_date'.

* `date_compare`
— The second of two top-level arguments, this serves as the "global" comparison operator for all date queries in the associative date query arrays on the second-level. This defaults to '='.

* `date_query_before`
— Sets the 'before' argument for a date query on the second level. It accepts either a strictly-formatted date, 'YYYY-MM-DD', or as a fallback, a relative-formatted date string (using the same logic as the `date` attribute).

* `date_query_after`
— Sets the 'after' argument for a date query on the second level. Like the `date_query_before` attribute, It accepts either a a strictly-formatted date, 'YYYY-MM-DD', or as a fallback, a relative-formatted date string (using the same logic as the `date` attribute.

* `date_query_column`
— Sets the column to query by for the second-level date query. If not set, falls back to the value of `date_column`.

* `date_query_compare`
— Sets the comparison operator for the second-level date query. If not set, falls back to the value of `date_compare`.

* `time`
— Serves as a shortcut to populating the 'hour', 'minute', and 'second' arguments in the second-level date query. It accepts only a strictly-formatted string in the format of 'HH:MM:SS' or 'HH:MM'. This does NOT have a string falback.

It also introduces a new function, `be_sanitize_date_time()` for handling date and time sanitization, as this logic is reused in 3 or 4 different instances, I thought it best to keep it DRY :)

`be_sanitize_date_time()` includes a filter though it does not include the early-return-fallback logic at the top.