diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index f7c86e66..179b12d4 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -615,13 +615,15 @@ Renders a two-column grid of small cards, showing the latest four stories ordere ### Latest Updates -Renders a two-column grid of small cards, showing the latest four updated stories ordered by date of the last chapter change, descending. Optional parameters are **count**, **type**, **author**, **order**, **post_ids**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. +Renders a two-column grid of small cards, showing the latest four updated stories ordered by date of the last chapter change, descending. Optional parameters are **count**, **type**, **author**, **order**, **post_ids**, **exclude_cat_ids**, **exclude_tag_ids**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. * **count:** Limit updates to any positive number, although you should keep it reasonable. Default `4`. * **type:** Either `default`, `simple`, or `compact`. The other variants are smaller with less data. * **author:** Only show updates of a specific author. Make sure to write the name right. * **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`. * **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **exclude_cat_ids:** Comma-separated list of category IDs to exclude. +* **exclude_tag_ids:** Comma-separated list of tag IDs to exclude. * **categories:** Comma-separated list of category names (case-insensitive), if you want to pick from a curated pool. * **tags:** Comma-separated list of tag names (case-insensitive), if you want to pick from a curated pool. * **fandoms:** Comma-separated list of fandom names (case-insensitive), if you want to pick from a curated pool. diff --git a/FILTERS.md b/FILTERS.md index e0d8bffb..e0f5f8f9 100644 --- a/FILTERS.md +++ b/FILTERS.md @@ -653,6 +653,8 @@ Filters the query arguments in the `fictioneer_latest_updates` shortcode. The op * $post_status (string) – `'publish'` * $author_name (string|null) – `$args['author']` * $post__in (array) – `$args['post_ids']` +* $category__not_in (array|null) – `$args['excluded_cats']` +* $tag__not_in (array|null) – `$args['excluded_tags']` * $meta_key (string) – `'fictioneer_chapters_added'` * $orderby (string) – `'meta_value'` * $order (string) – `$args['order']` @@ -665,6 +667,8 @@ Filters the query arguments in the `fictioneer_latest_updates` shortcode. The op * $count (int) – The number of posts provided by the shortcode. Default `1`. * $order (string) – Optional. Default `'desc'`. * $post_ids (\[string]) – Array of post IDs. Default empty. +* $excluded_cats (\[string]) – Array of category IDs to exclude. Default empty. +* $excluded_tags (\[string]) – Array of tag IDs to exclude. Default empty. * $taxonomies (\[array]) – Array of taxonomy arrays (names). Default empty. * $relation (string) – Relationship between taxonomies. Default `'AND'`. * $classes (\[string]) – Array of additional CSS classes. Default empty. diff --git a/includes/functions/_shortcodes.php b/includes/functions/_shortcodes.php index 774821fc..6d6fe7f2 100644 --- a/includes/functions/_shortcodes.php +++ b/includes/functions/_shortcodes.php @@ -474,17 +474,19 @@ add_shortcode( 'fictioneer_story_cards', 'fictioneer_shortcode_latest_stories' ) * * @since 4.3 * - * @param string|null $attr['count'] Optional. Maximum number of items. Default 4. - * @param string|null $attr['author'] Optional. Limit items to a specific author. - * @param string|null $attr['type'] Optional. Choose between 'default', 'simple', and 'compact'. - * @param string|null $attr['post_ids'] Optional. Limit items to specific post IDs. - * @param string|null $attr['categories'] Optional. Limit items to specific category names. - * @param string|null $attr['tags'] Optional. Limit items to specific tag names. - * @param string|null $attr['fandoms'] Optional. Limit items to specific fandom names. - * @param string|null $attr['genres'] Optional. Limit items to specific genre names. - * @param string|null $attr['characters'] Optional. Limit items to specific character names. - * @param string|null $attr['rel'] Optional. Relationship between taxonomies. Default 'AND'. - * @param string|null $attr['class'] Optional. Additional CSS classes, separated by whitespace. + * @param string|null $attr['count'] Optional. Maximum number of items. Default 4. + * @param string|null $attr['author'] Optional. Limit items to a specific author. + * @param string|null $attr['type'] Optional. Choose between 'default', 'simple', and 'compact'. + * @param string|null $attr['post_ids'] Optional. Limit items to specific post IDs. + * @param string|null $attr['exclude_tag_ids'] Optional. Exclude posts with these tags. + * @param string|null $attr['exclude_cat_ids'] Optional. Exclude posts with these categories. + * @param string|null $attr['categories'] Optional. Limit items to specific category names. + * @param string|null $attr['tags'] Optional. Limit items to specific tag names. + * @param string|null $attr['fandoms'] Optional. Limit items to specific fandom names. + * @param string|null $attr['genres'] Optional. Limit items to specific genre names. + * @param string|null $attr['characters'] Optional. Limit items to specific character names. + * @param string|null $attr['rel'] Optional. Relationship between taxonomies. Default 'AND'. + * @param string|null $attr['class'] Optional. Additional CSS classes, separated by whitespace. * * @return string The rendered shortcode HTML. */ @@ -519,6 +521,8 @@ function fictioneer_shortcode_latest_story_updates( $attr ) { 'author' => $author, 'order' => $order, 'post_ids' => $post_ids, + 'excluded_tags' => fictioneer_explode_list( $attr['exclude_tag_ids'] ?? '' ), + 'excluded_cats' => fictioneer_explode_list( $attr['exclude_cat_ids'] ?? '' ), 'taxonomies' => fictioneer_get_shortcode_taxonomies( $attr ), 'relation' => $rel, 'classes' => $classes diff --git a/partials/_latest-updates-compact.php b/partials/_latest-updates-compact.php index 427f3127..0648ab17 100644 --- a/partials/_latest-updates-compact.php +++ b/partials/_latest-updates-compact.php @@ -12,13 +12,15 @@ * @since 4.3 * @see fictioneer_remember_chapters_modified() * - * @internal $args['count'] Number of posts provided by the shortcode. - * @internal $args['author'] Author provided by the shortcode. - * @internal $args['order'] Order of posts. Default 'desc'. - * @internal $args['post_ids'] Array of post IDs. Default empty. - * @internal $args['taxonomies'] Array of taxonomy arrays. Default empty. - * @internal $args['relation'] Relationship between taxonomies. - * @internal $args['class'] Additional classes. + * @internal $args['count'] Number of posts provided by the shortcode. + * @internal $args['author'] Author provided by the shortcode. + * @internal $args['order'] Order of posts. Default 'desc'. + * @internal $args['post_ids'] Array of post IDs. Default empty. + * @internal $args['excluded_cats'] Array of category IDs to exclude. Default empty. + * @internal $args['excluded_tags'] Array of tag IDs to exclude. Default empty. + * @internal $args['taxonomies'] Array of taxonomy arrays. Default empty. + * @internal $args['relation'] Relationship between taxonomies. + * @internal $args['class'] Additional classes. */ ?> @@ -48,6 +50,16 @@ if ( ! empty( $args['taxonomies'] ) ) { $query_args['tax_query'] = fictioneer_get_shortcode_tax_query( $args ); } +// Excluded tags? +if ( ! empty( $args['excluded_tags'] ) ) { + $query_args['tag__not_in'] = $args['excluded_tags']; +} + +// Excluded categories? +if ( ! empty( $args['excluded_cats'] ) ) { + $query_args['category__not_in'] = $args['excluded_cats']; +} + // Apply filters $query_args = apply_filters( 'fictioneer_filter_shortcode_latest_updates_query_args', $query_args, $args ); diff --git a/partials/_latest-updates.php b/partials/_latest-updates.php index b7c2014a..3396d338 100644 --- a/partials/_latest-updates.php +++ b/partials/_latest-updates.php @@ -13,14 +13,16 @@ * @since 4.3 * @see fictioneer_remember_chapters_modified() * - * @internal $args['count'] Number of posts provided by the shortcode. - * @internal $args['author'] Author provided by the shortcode. - * @internal $args['order'] Order of posts. Default 'desc'. - * @internal $args['post_ids'] Array of post IDs. Default empty. - * @internal $args['taxonomies'] Array of taxonomy arrays. Default empty. - * @internal $args['relation'] Relationship between taxonomies. - * @internal $args['simple'] Whether to show the simple variant. - * @internal $args['class'] Additional classes. + * @internal $args['count'] Number of posts provided by the shortcode. + * @internal $args['author'] Author provided by the shortcode. + * @internal $args['order'] Order of posts. Default 'desc'. + * @internal $args['post_ids'] Array of post IDs. Default empty. + * @internal $args['excluded_cats'] Array of category IDs to exclude. Default empty. + * @internal $args['excluded_tags'] Array of tag IDs to exclude. Default empty. + * @internal $args['taxonomies'] Array of taxonomy arrays. Default empty. + * @internal $args['relation'] Relationship between taxonomies. + * @internal $args['simple'] Whether to show the simple variant. + * @internal $args['class'] Additional classes. */ ?> @@ -49,6 +51,16 @@ if ( ! empty( $args['taxonomies'] ) ) { $query_args['tax_query'] = fictioneer_get_shortcode_tax_query( $args ); } +// Excluded tags? +if ( ! empty( $args['excluded_tags'] ) ) { + $query_args['tag__not_in'] = $args['excluded_tags']; +} + +// Excluded categories? +if ( ! empty( $args['excluded_cats'] ) ) { + $query_args['category__not_in'] = $args['excluded_cats']; +} + // Apply filters $query_args = apply_filters( 'fictioneer_filter_shortcode_latest_updates_query_args', $query_args, $args );