diff --git a/FILTERS.md b/FILTERS.md index 92d16658..94c0607e 100644 --- a/FILTERS.md +++ b/FILTERS.md @@ -416,24 +416,6 @@ Filters the intermediate output array of the `fictioneer_mobile_user_menu()` fun --- -### `apply_filters( 'fictioneer_filter_orderby_popup_menu', $menu, $args )` -Filters the array of URLs and labels of the orderby popup menu in the `fictioneer_sort_order_filter_interface( $args )` function before it is rendered. - -**$menu:** -* $modified (array) – Tuple of $label (Updated) and unescaped $url (`...?orderby=modified&order={$order}#sof`). -* $date (array) – Tuple of $label (Published) and unescaped $url (`...?orderby=date&order={$order}#sof`). -* $title (array) – Tuple of $label (Title) and unescaped $url (`...?orderby=title&order={$order}#sof`). - -**$args:** -* $current_page (int) – Current page if paginated or `1`. -* $post_id (int) – Current post ID. -* $queried_type (string) – Queried post type. -* $query_args (array) – Query arguments used. -* $order (string) – Current order or `'desc'`. -* $orderby (string) – Current orderby or `'modified'`. - ---- - ### `apply_filters( 'fictioneer_filter_post_meta_items', $output, $args )` Filters the intermediate output array of the `fictioneer_get_post_meta_items()` function before it is imploded and returned. @@ -757,6 +739,77 @@ Filters the query arguments in the `fictioneer_showcase` shortcode. The optional --- +### `apply_filters( 'fictioneer_filter_sof_date_options', $options, $current_url, $args )` +Filters the option array of URL/label tuples for the date popup menu in the `fictioneer_sort_order_filter_interface( $args )` function before it is rendered. Can be any positive integer (days) or [strtotime](https://www.php.net/manual/en/function.strtotime.php) compatible string. See `fictioneer_append_date_query(...)`. Includes '0', '1', '3', '1 week ago', '1 month ago', '3 months ago', '6 months ago', and '1 year ago'. + +**$options:** +* '0' (array) – Tuple of $label (Any Date) and unescaped $url (`...ago=0&...#sof`). +* '1' (array) – Tuple of $label (Past 24 Hours) and unescaped $url (`...ago=1&...#sof`). +* '3' (array) – Tuple of $label (Past 3 Days) and unescaped $url (`...ago=3&...#sof`). +* '1_week_ago' (array) – Tuple of $label (Past Week) and unescaped $url (`...ago=1+week+ago&...#sof`). +* '1_month_ago' (array) – Tuple of $label (Past Month) and unescaped $url (`...ago=1+month+ago&...#sof`). +* '3_months_ago' (array) – Tuple of $label (Past 3 Months) and unescaped $url (`...ago=3+months+ago&...#sof`). +* '6_months_ago' (array) – Tuple of $label (Past 6 Months) and unescaped $url (`...ago=6+months+ago&...#sof`). +* '1_year_ago' (array) – Tuple of $label (Past Year) and unescaped $url (`...ago=1+year+ago&...#sof`). + +**Parameters:** +* $current_url (array) – Current URL with all query parameters to sort, order, and filter included. Used to build option links. + +**$args:** +* $current_page (int) – Current page if paginated or `1`. +* $post_id (int) – Current post ID. +* $queried_type (string) – Queried post type. +* $query_args (array) – Query arguments used. +* $order (string) – Current order. Defaults to `'desc'`. +* $orderby (string) – Current orderby. Defaults to `'modified'` in list templates and `'date'` in archives. + +--- + +### `apply_filters( 'fictioneer_filter_sof_orderby_options', $options, $current_url, $args )` +Filters the option array of URL/label tuples for the orderby popup menu in the `fictioneer_sort_order_filter_interface( $args )` function before it is rendered. Allows and includes 'modified', 'date', 'title', and 'rand' (excluded). + +**$options:** +* 'modified' (array) – Tuple of $label (Updated) and unescaped $url (`...orderby=modified&...#sof`). +* 'date' (array) – Tuple of $label (Published) and unescaped $url (`...orderby=date&...#sof`). +* 'title' (array) – Tuple of $label (By Title) and unescaped $url (`...orderby=title&...#sof`). + +**Parameters:** +* $current_url (array) – Current URL with all query parameters to sort, order, and filter included. Used to build option links. + +**$args:** +* $current_page (int) – Current page if paginated or `1`. +* $post_id (int) – Current post ID. +* $queried_type (string) – Queried post type. +* $query_args (array) – Query arguments used. +* $order (string) – Current order. Defaults to `'desc'`. +* $orderby (string) – Current orderby. Defaults to `'modified'` in list templates and `'date'` in archives. + +--- + +### `apply_filters( 'fictioneer_filter_sof_post_type_options', $options, $current_url, $args )` +Filters the option array of URL/label tuples for the post type popup menu in the `fictioneer_sort_order_filter_interface( $args )` function before it is rendered. Only rendered in archives. Includes 'any', 'post, 'fcn_story', 'fcn_chapter', 'fcn_collection', and 'fcn_recommendation'. + +**$options:** +* $any (array) – Tuple of $label (All Posts) and unescaped $url (`...post_type=any&...#sof`). +* $post (array) – Tuple of $label (Blog Posts) and unescaped $url (`...post_type=post&...#sof`). +* $fcn_story (array) – Tuple of $label (Stories) and unescaped $url (`...post_type=fcn_story&...#sof`). +* $fcn_chapter (array) – Tuple of $label (Chapters) and unescaped $url (`...post_type=fcn_chapter&...#sof`). +* $fcn_collection (array) – Tuple of $label (Collections) and unescaped $url (`...post_type=fcn_collection&...#sof`). +* $fcn_recommendation (array) – Tuple of $label (Recommendations) and unescaped $url (`...post_type=fcn_recommendation&...#sof`). + +**Parameters:** +* $current_url (array) – Current URL with all query parameters to sort, order, and filter included. Used to build option links. + +**$args:** +* $current_page (int) – Current page if paginated or `1`. +* $post_id (int) – Current post ID. +* $queried_type (string) – Queried post type. +* $query_args (array) – Query arguments used. +* $order (string) – Current order. Defaults to `'desc'`. +* $orderby (string) – Current orderby. Defaults to `'modified'` in list templates and `'date'` in archives. + +--- + ### `apply_filters( 'fictioneer_filter_stories_card_args', $card_args, $args )` Filters the arguments passed to the `partials/_card-story` template part in the `fictioneer_stories_list( $args )` function, normally added via the `fictioneer_stories_after_content` hook. diff --git a/includes/functions/hooks/_general_hooks.php b/includes/functions/hooks/_general_hooks.php index 24ddcdbc..32890ca9 100644 --- a/includes/functions/hooks/_general_hooks.php +++ b/includes/functions/hooks/_general_hooks.php @@ -199,225 +199,241 @@ add_action( 'fictioneer_header', 'fictioneer_header_background', 10 ); // SORT, ORDER & FILTER QUERIES // ============================================================================= -/** - * Renders interface to sort, order, and filter queries - * - * @since Fictioneer 5.4.0 - * - * @param array $args { - * Array of arguments. - * - * @type int $current_page Optional. Current page if paginated or `1`. - * @type int $post_id Optional. Current post ID. - * @type string $queried_type Optional. Queried post type. - * @type array $query_args Optional. Query arguments used. - * @type string $order Current order or `desc`. - * @type string $orderby Current orderby or `'modified'`. - * @type int|string $ago Current date query argument part or `0`. - * } - */ +if ( ! function_exists( 'fictioneer_sort_order_filter_interface' ) ) { + /** + * Renders interface to sort, order, and filter queries + * + * @since Fictioneer 5.4.0 + * + * @param array $args { + * Array of arguments. + * + * @type int $current_page Optional. Current page if paginated or `1`. + * @type int $post_id Optional. Current post ID. + * @type string $queried_type Optional. Queried post type. + * @type array $query_args Optional. Query arguments used. + * @type string $order Current order or `desc`. + * @type string $orderby Current orderby or `'modified'`. + * @type int|string $ago Current date query argument part or `0`. + * } + */ -function fictioneer_sort_order_filter_interface( $args ) { - // Setup - $current_url = fictioneer_get_clean_url(); - $post_type = null; + function fictioneer_sort_order_filter_interface( $args ) { + // Setup + $current_url = fictioneer_get_clean_url(); + $post_type = null; - // Archive? - if ( is_archive() ) { - $post_type = strtolower( sanitize_text_field( $_GET['post_type'] ?? '' ) ); - $post_type = array_intersect( - [ $post_type ], - ['any', 'post', 'fcn_story', 'fcn_chapter', 'fcn_collection', 'fcn_recommendation'] - ); - $post_type = reset( $post_type ) ?: null; - } - - // Post type? - if ( ! empty( $post_type ) ) { - $current_url = add_query_arg( - array( 'post_type' => $post_type ), - $current_url - ); - } - - // Order? - if ( ! empty( $args['order'] ) ) { - $current_url = add_query_arg( - array( 'order' => $args['order'] ), - $current_url - ); - } - - // Orderby? - if ( ! empty( $args['orderby'] ) ) { - $current_url = add_query_arg( - array( 'orderby' => $args['orderby'] ), - $current_url - ); - } - - // Ago? - if ( ! empty( $args['ago'] ) ) { - // Validate - if ( ! is_numeric( $args['ago'] ) && strtotime( $args['ago'] ) === false ) { - $args['ago'] = '0'; + // Archive? + if ( is_archive() ) { + $post_type = strtolower( sanitize_text_field( $_GET['post_type'] ?? '' ) ); + $post_type = array_intersect( + [ $post_type ], + ['any', 'post', 'fcn_story', 'fcn_chapter', 'fcn_collection', 'fcn_recommendation'] + ); + $post_type = reset( $post_type ) ?: null; } - // Add if valid - if ( $args['ago'] != '0' ) { + // Post type? + if ( ! empty( $post_type ) ) { $current_url = add_query_arg( - array( 'ago' => $args['ago'] ), + array( 'post_type' => $post_type ), $current_url ); } + + // Order? + if ( ! empty( $args['order'] ) ) { + $current_url = add_query_arg( + array( 'order' => $args['order'] ), + $current_url + ); + } + + // Orderby? + if ( ! empty( $args['orderby'] ) ) { + $current_url = add_query_arg( + array( 'orderby' => $args['orderby'] ), + $current_url + ); + } + + // Ago? + if ( ! empty( $args['ago'] ) ) { + // Validate + if ( ! is_numeric( $args['ago'] ) && strtotime( $args['ago'] ) === false ) { + $args['ago'] = '0'; + } + + // Add if valid + if ( $args['ago'] != '0' ) { + $current_url = add_query_arg( + array( 'ago' => $args['ago'] ), + $current_url + ); + } + } + + // Post type menu options + $post_type_menu = array( + 'any' => array( + 'label' => __( 'All Posts', 'fictioneer' ), + 'url' => add_query_arg( array( 'post_type' => 'any' ), $current_url ) . '#sof' + ), + 'post' => array( + 'label' => __( 'Blog Posts', 'fictioneer' ), + 'url' => add_query_arg( array( 'post_type' => 'post' ), $current_url ) . '#sof' + ), + 'fcn_story' => array( + 'label' => __( 'Stories', 'fictioneer' ), + 'url' => add_query_arg( array( 'post_type' => 'fcn_story' ), $current_url ) . '#sof' + ), + 'fcn_chapter' => array( + 'label' => __( 'Chapters', 'fictioneer' ), + 'url' => add_query_arg( array( 'post_type' => 'fcn_chapter' ), $current_url ) . '#sof' + ), + 'fcn_collection' => array( + 'label' => __( 'Collections', 'fictioneer' ), + 'url' => add_query_arg( array( 'post_type' => 'fcn_collection' ), $current_url ) . '#sof' + ), + 'fcn_recommendation' => array( + 'label' => __( 'Recommendations', 'fictioneer' ), + 'url' => add_query_arg( array( 'post_type' => 'fcn_recommendation' ), $current_url ) . '#sof' + ) + ); + + // Filter post type options + $post_type_menu = apply_filters( 'fictioneer_filter_sof_post_type_options', $post_type_menu, $current_url, $args ); + + // Order menu options + $orderby_menu = array( + 'modified' => array( + 'label' => __( 'Updated', 'fictioneer' ), + 'url' => add_query_arg( array( 'orderby' => 'modified' ), $current_url ) . '#sof' + ), + 'date' => array( + 'label' => __( 'Published', 'fictioneer' ), + 'url' => add_query_arg( array( 'orderby' => 'date' ), $current_url ) . '#sof' + ), + 'title' => array( + 'label' => __( 'By Title', 'fictioneer' ), + 'url' => add_query_arg( array( 'orderby' => 'title' ), $current_url ) . '#sof' + ) + ); + + // Filter orderby options + $orderby_menu = apply_filters( 'fictioneer_filter_sof_orderby_options', $orderby_menu, $current_url, $args ); + + // Date menu options + $date_menu = array( + '0' => array( + 'label' => __( 'Any Date', 'fictioneer' ), + 'url' => remove_query_arg( 'ago', $current_url ) . '#sof' + ), + '1' => array( + 'label' => __( 'Past 24 Hours', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => 1 ), $current_url ) . '#sof' + ), + '3' => array( + 'label' => __( 'Past 3 Days', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => 3 ), $current_url ) . '#sof' + ), + '1_week_ago' => array( + 'label' => __( 'Past Week', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => urlencode( '1 week ago' ) ), $current_url ) . '#sof' + ), + '1_month_ago' => array( + 'label' => __( 'Past Month', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => urlencode( '1 month ago' ) ), $current_url ) . '#sof' + ), + '3_months_ago' => array( + 'label' => __( 'Past 3 Months', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => urlencode( '3 months ago' ) ), $current_url ) . '#sof' + ), + '6_months_ago' => array( + 'label' => __( 'Past 6 Months', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => urlencode( '6 months ago' ) ), $current_url ) . '#sof' + ), + '1_year_ago' => array( + 'label' => __( 'Past Year', 'fictioneer' ), + 'url' => add_query_arg( array( 'ago' => urlencode( '1 year ago' ) ), $current_url ) . '#sof' + ) + ); + + // Filter date options + $date_menu = apply_filters( 'fictioneer_filter_sof_date_options', $date_menu, $current_url, $args ); + + // Order toggle link + $order_link = esc_url( + add_query_arg( + array( 'order' => $args['order'] === 'desc' ? 'asc' : 'desc' ), + $current_url + ) . '#sof' + ); + + // Start HTML ---> ?> +
+ + + '; + ?>
+ + + + '; + ?> + + + + '; + ?> + + + + + + + + array( - 'label' => __( 'All Posts', 'fictioneer' ), - 'url' => add_query_arg( array( 'post_type' => 'any' ), $current_url ) . '#sof' - ), - 'post' => array( - 'label' => __( 'Blog Posts', 'fictioneer' ), - 'url' => add_query_arg( array( 'post_type' => 'post' ), $current_url ) . '#sof' - ), - 'fcn_story' => array( - 'label' => __( 'Stories', 'fictioneer' ), - 'url' => add_query_arg( array( 'post_type' => 'fcn_story' ), $current_url ) . '#sof' - ), - 'fcn_chapter' => array( - 'label' => __( 'Chapters', 'fictioneer' ), - 'url' => add_query_arg( array( 'post_type' => 'fcn_chapter' ), $current_url ) . '#sof' - ), - 'fcn_collection' => array( - 'label' => __( 'Collections', 'fictioneer' ), - 'url' => add_query_arg( array( 'post_type' => 'fcn_collection' ), $current_url ) . '#sof' - ), - 'fcn_recommendation' => array( - 'label' => __( 'Recommendations', 'fictioneer' ), - 'url' => add_query_arg( array( 'post_type' => 'fcn_recommendation' ), $current_url ) . '#sof' - ) - ); - - // Order menu options - $orderby_menu = array( - 'modified' => array( - 'label' => __( 'Updated', 'fictioneer' ), - 'url' => add_query_arg( array( 'orderby' => 'modified' ), $current_url ) . '#sof' - ), - 'date' => array( - 'label' => __( 'Published', 'fictioneer' ), - 'url' => add_query_arg( array( 'orderby' => 'date' ), $current_url ) . '#sof' - ), - 'title' => array( - 'label' => __( 'By Title', 'fictioneer' ), - 'url' => add_query_arg( array( 'orderby' => 'title' ), $current_url ) . '#sof' - ) - ); - - // Date menu options - $date_menu = array( - '0' => array( - 'label' => __( 'Any Date', 'fictioneer' ), - 'url' => remove_query_arg( 'ago', $current_url ) . '#sof' - ), - '1' => array( - 'label' => __( 'Past 24 Hours', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => 1 ), $current_url ) . '#sof' - ), - '3' => array( - 'label' => __( 'Past 3 Days', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => 3 ), $current_url ) . '#sof' - ), - '1 week ago' => array( - 'label' => __( 'Past Week', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => urlencode( '1 week ago' ) ), $current_url ) . '#sof' - ), - '1 month ago' => array( - 'label' => __( 'Past Month', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => urlencode( '1 month ago' ) ), $current_url ) . '#sof' - ), - '3 months ago' => array( - 'label' => __( 'Past 3 Months', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => urlencode( '3 months ago' ) ), $current_url ) . '#sof' - ), - '6 months ago' => array( - 'label' => __( 'Past 6 Months', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => urlencode( '6 months ago' ) ), $current_url ) . '#sof' - ), - '1 year ago' => array( - 'label' => __( 'Past Year', 'fictioneer' ), - 'url' => add_query_arg( array( 'ago' => urlencode( '1 year ago' ) ), $current_url ) . '#sof' - ) - ); - - // Order toggle link - $order_link = esc_url( - add_query_arg( - array( 'order' => $args['order'] === 'desc' ? 'asc' : 'desc' ), - $current_url - ) . '#sof' - ); - - // Apply filters - $orderby_menu = apply_filters( 'fictioneer_filter_orderby_popup_menu', $orderby_menu, $args ); - - // Start HTML ---> ?> -
- - - '; - ?>
- - - '; - ?> - - '; - ?> - - - - - - -