diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 2aeb4a16..0148b9b2 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -423,10 +423,10 @@ Renders a two-column grid of small bookmark cards, ordered by date of creation. ### Chapter List -Renders a list of chapters identical to those on story pages, ordered by sequence in the source. Must have either the **story** or **chapters** parameter. Optional parameters are **count**, **offset**, **group**, **heading**, and **class**. +Renders a list of chapters identical to those on story pages, ordered by sequence in the source. Must have either the **story_id** or **chapter_ids** parameter. Optional parameters are **count**, **offset**, **group**, **heading**, and **class**. -* **story:** ID of a single story. You need either this or **chapters**. -* **chapters:** Comma-separated list of chapter IDs. You need either this or **story**. +* **story_id:** ID of a single story. You need either this or **chapters**. +* **chapter_ids:** Comma-separated list of chapter IDs. You need either this or **story**. * **count:** Limit chapters to any positive number. Default `-1` (all). * **offset:** Skip a number of chapters, which can make sense if you query all. * **heading:** Show a heading with collapse toggle above the list. @@ -487,7 +487,7 @@ Renders two buttons to deal with cookies, "Reset Consent" and "Clear Cookies". B ### Latest Chapters -Renders a two-column grid of small cards, showing the latest four chapters ordered by publishing date, descending. Optional parameters are **count**, **type**, **author**, **order**, **orderby**, **spoiler**, **source**, **chapters**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. +Renders a two-column grid of small cards, showing the latest four chapters ordered by publishing date, descending. Optional parameters are **count**, **type**, **author**, **order**, **orderby**, **spoiler**, **source**, **post_ids**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. * **count:** Limit chapters 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. @@ -496,7 +496,7 @@ Renders a two-column grid of small cards, showing the latest four chapters order * **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters). * **spoiler:** The excerpt is obfuscated, set `true` if you want to reveal it. Default `false`. * **source:** Set `false` to hide the author and story nodes. Default `true`. -* **chapters:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool. * **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. @@ -521,11 +521,11 @@ Renders a two-column grid of small cards, showing the latest four chapters order ### Latest Posts -Renders the last blog post or a list of blog posts, ignoring sticky posts, ordered by publishing date, descending. Optional parameters are **count**, **author**, **posts**, **categories**, **tags**, **rel**, and **class**. +Renders the last blog post or a list of blog posts, ignoring sticky posts, ordered by publishing date, descending. Optional parameters are **count**, **author**, **post_ids**, **categories**, **tags**, **rel**, and **class**. * **count:** Limit posts to any positive number, although you should keep it reasonable. Default `1`. * **author:** Only show posts of a specific author. Make sure to write the name right. -* **posts:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool. * **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. * **rel:** Relationship between different taxonomies, either `AND` or `OR`. Default `AND`. @@ -547,14 +547,14 @@ Renders the last blog post or a list of blog posts, ignoring sticky posts, order ### Latest Recommendations -Renders a two-column grid of small cards, showing the latest four recommendations ordered by publishing date, descending. Optional parameters are **count**, **type**, **author**, **order**, **orderby**, **recommendations**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. +Renders a two-column grid of small cards, showing the latest four recommendations ordered by publishing date, descending. Optional parameters are **count**, **type**, **author**, **order**, **orderby**, **post_ids**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. * **count:** Limit recommendations to any positive number, although you should keep it reasonable. Default `4`. * **type:** Either `default` or `compact`. The compact variant is smaller with less data. * **author:** Only show recommendations by a specific author. Make sure to write the name right. * **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`. * **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters). -* **recommendations:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool. * **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. @@ -579,14 +579,14 @@ Renders a two-column grid of small cards, showing the latest four recommendation ### Latest Stories -Renders a two-column grid of small cards, showing the latest four stories ordered by publishing date, descending. Optional parameters are **count**, **type**, **author**, **order**, **orderby**, **stories**, **exclude_cat_ids**, **exclude_tag_ids**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. +Renders a two-column grid of small cards, showing the latest four stories ordered by publishing date, descending. Optional parameters are **count**, **type**, **author**, **order**, **orderby**, **post_ids**, **exclude_cat_ids**, **exclude_tag_ids**, **categories**, **tags**, **fandoms**, **genres**, **characters**, **rel**, and **class**. * **count:** Limit stories to any positive number, although you should keep it reasonable. Default `4`. * **type:** Either `default` or `compact`. The compact variant is smaller with less data. * **author:** Only show stories of a specific author. Make sure to spell the _username_ right. * **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`. * **orderby:** The default is `date`, but you can also use `modified` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters). -* **stories:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **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. @@ -613,13 +613,13 @@ 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**, **stories**, **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**, **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`. -* **stories:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool. * **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. @@ -661,14 +661,14 @@ Renders the search form with advanced options (if not disabled in the settings). ### Showcase -Renders dynamic grid of thumbnails with title, showing the latest eight posts of the specified type ordered by publishing date, descending. Requires **for** parameter. Optional parameters are **count**, **author**, **order**, **orderby**, **posts**, **no_cap**, and **class**. The thumbnail is either the **Landscape Image** or **Cover Image** (if available), with chapters defaulting to the parent story. +Renders dynamic grid of thumbnails with title, showing the latest eight posts of the specified type ordered by publishing date, descending. Requires **for** parameter. Optional parameters are **count**, **author**, **order**, **orderby**, **post_ids**, **no_cap**, and **class**. The thumbnail is either the **Landscape Image** or **Cover Image** (if available), with chapters defaulting to the parent story. * **for:** Desired post type, either `stories`, `chapters`, `collections`, or `recommendations`. * **count:** Limit posts to any positive number, although you should keep it reasonable. Default `8`. * **author:** Only show posts for a specific author. Make sure to write the name right. * **order:** Either `desc` (descending) or `asc` (ascending). Default `desc`. * **orderby:** The default is `date`, but you can also use `rand` and [more](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters). -* **posts:** Comma-separated list of post IDs, if you want to pick from a curated pool. +* **post_ids:** Comma-separated list of post IDs, if you want to pick from a curated pool. * **no_cap:** Set `true` if you want to hide the caption. * **class:** Additional CSS classes, separated by whitespace. diff --git a/includes/functions/_shortcodes.php b/includes/functions/_shortcodes.php index f6e99377..97e11632 100644 --- a/includes/functions/_shortcodes.php +++ b/includes/functions/_shortcodes.php @@ -237,8 +237,8 @@ function fictioneer_shortcode_showcase( $attr ) { $classes = []; // Post IDs - if ( ! empty( $attr['posts'] ) ) { - $post_ids = fictioneer_explode_list( $attr['posts'] ); + if ( ! empty( $attr['post_ids'] ) ) { + $post_ids = fictioneer_explode_list( $attr['post_ids'] ); } // Relation @@ -304,7 +304,7 @@ add_shortcode( 'fictioneer_showcase', 'fictioneer_shortcode_showcase' ); * @param string|null $attr['type'] Optional. Choose between 'default', 'simple', and 'compact'. * @param string|null $attr['spoiler'] Optional. Whether to show spoiler content. * @param string|null $attr['source'] Optional. Whether to show author and story. - * @param string|null $attr['chapters'] Optional. Limit items to specific post IDs. + * @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. @@ -330,8 +330,8 @@ function fictioneer_shortcode_latest_chapters( $attr ) { $classes = []; // Post IDs - if ( ! empty( $attr['chapters'] ) ) { - $post_ids = fictioneer_explode_list( $attr['chapters'] ); + if ( ! empty( $attr['post_ids'] ) ) { + $post_ids = fictioneer_explode_list( $attr['post_ids'] ); $count = count( $post_ids ); } @@ -390,7 +390,7 @@ add_shortcode( 'fictioneer_chapter_cards', 'fictioneer_shortcode_latest_chapters * @param string|null $attr['author'] Optional. Limit items to a specific author. * @param string|null $attr['type'] Optional. Choose between 'default' and 'compact'. * @param string|null $attr['orderby'] Optional. Order argument. Default 'date'. - * @param string|null $attr['stories'] Optional. Limit items to specific post IDs. + * @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. @@ -414,8 +414,8 @@ function fictioneer_shortcode_latest_stories( $attr ) { $classes = []; // Post IDs - if ( ! empty( $attr['stories'] ) ) { - $post_ids = fictioneer_explode_list( $attr['stories'] ); + if ( ! empty( $attr['post_ids'] ) ) { + $post_ids = fictioneer_explode_list( $attr['post_ids'] ); $count = count( $post_ids ); } @@ -434,6 +434,8 @@ function fictioneer_shortcode_latest_stories( $attr ) { 'order' => $order, 'orderby' => $orderby, '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 @@ -469,7 +471,7 @@ add_shortcode( 'fictioneer_story_cards', 'fictioneer_shortcode_latest_stories' ) * @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['stories'] Optional. Limit items to specific post IDs. + * @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. @@ -492,8 +494,8 @@ function fictioneer_shortcode_latest_story_updates( $attr ) { $classes = []; // Post IDs - if ( ! empty( $attr['stories'] ) ) { - $post_ids = fictioneer_explode_list( $attr['stories'] ); + if ( ! empty( $attr['post_ids'] ) ) { + $post_ids = fictioneer_explode_list( $attr['post_ids'] ); $count = count( $post_ids ); } @@ -544,17 +546,17 @@ add_shortcode( 'fictioneer_update_cards', 'fictioneer_shortcode_latest_story_upd * * @since 4.0 * - * @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' and 'compact'. - * @param string|null $attr['recommendations'] 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' 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. * * @return string The rendered shortcode HTML. */ @@ -571,8 +573,8 @@ function fictioneer_shortcode_latest_recommendations( $attr ) { $classes = []; // Post IDs - if ( ! empty( $attr['recommendations'] ) ) { - $post_ids = fictioneer_explode_list( $attr['recommendations'] ); + if ( ! empty( $attr['post_ids'] ) ) { + $post_ids = fictioneer_explode_list( $attr['post_ids'] ); $count = count( $post_ids ); } @@ -625,7 +627,7 @@ add_shortcode( 'fictioneer_recommendation_cards', 'fictioneer_shortcode_latest_r * * @param string|null $attr['count'] Optional. Maximum number of items. Default 1. * @param string|null $attr['author'] Optional. Limit items to a specific author. - * @param string|null $attr['posts'] Optional. Limit items to specific post IDs. + * @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['rel'] Optional. Relationship between taxonomies. Default 'AND'. @@ -643,8 +645,8 @@ function fictioneer_shortcode_latest_posts( $attr ) { $classes = []; // Post IDs - if ( ! empty( $attr['posts'] ) ) { - $post_ids = fictioneer_explode_list( $attr['posts'] ); + if ( ! empty( $attr['post_ids'] ) ) { + $post_ids = fictioneer_explode_list( $attr['post_ids'] ); $count = count( $post_ids ); } @@ -743,13 +745,13 @@ add_shortcode( 'fictioneer_cookie_buttons', 'fictioneer_shortcode_cookie_buttons * @see fictioneer_validate_id() * @see fictioneer_get_story_data() * - * @param string $attr['story'] Either/Or. The ID of the story the chapters belong to. - * @param string|null $attr['chapters'] Either/Or. IDs of chapters to display. - * @param string|null $attr['count'] Optional. Maximum number of items. Default -1 (all). - * @param string|null $attr['offset'] Optional. Skip a number of posts. - * @param string|null $attr['group'] Optional. Only show chapters of the group. - * @param string|null $attr['heading'] Optional. Show