From f14abaa298a537acff1aedff1adba6e088098127 Mon Sep 17 00:00:00 2001
From: Tetrakern <26898880+Tetrakern@users.noreply.github.com>
Date: Wed, 30 Oct 2024 20:56:06 +0100
Subject: [PATCH] Add filter to story page cover HTML

---
 FILTERS.md                                | 20 ++++++++++++++++++++
 includes/functions/_helpers-templates.php |  7 +++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/FILTERS.md b/FILTERS.md
index fa6733f1..36aea3e6 100644
--- a/FILTERS.md
+++ b/FILTERS.md
@@ -2126,6 +2126,26 @@ Filters the intermediate output array in the `_story-header.php` partial before
 
 ---
 
+### `apply_filters( 'fictioneer_filter_story_page_cover_html', $html, $story, $args )`
+Filters the HTML of the story page cover returned by the `fictioneer_get_story_page_cover()` function.
+
+**Parameters:**
+* $html (string) – The HTML to be rendered.
+* $story (array) – Array of story data.
+* $args (array) – Optional arguments.
+
+**Example:**
+```php
+function child_add_status_to_story_page_cover( $html, $story ) {
+  $extra_html = '<div>' . fcntr( $story['status'] ) . '</div></figure>'; // Does not have styling, though
+
+  return mb_ereg_replace( '</figure>', $extra_html, $html ); // Multi-byte safe
+}
+add_filter( 'fictioneer_filter_story_page_cover_html', 'child_add_status_to_story_page_cover', 10, 2 );
+```
+
+---
+
 ### `apply_filters( 'fictioneer_filter_story_word_count', $word_count, $post_id )`
 Filters the total word count of a story after sanitization (greater than or equal to 0) and before `fictioneer_multiply_word_count()` is applied, returning a positive integer. The word count is only calculated and updated when a post associated with the story is saved.
 
diff --git a/includes/functions/_helpers-templates.php b/includes/functions/_helpers-templates.php
index 08cdd159..e7e00676 100644
--- a/includes/functions/_helpers-templates.php
+++ b/includes/functions/_helpers-templates.php
@@ -594,6 +594,7 @@ function fictioneer_get_breadcrumbs( $args ) {
    *
    * @since 5.0.0
    * @since 5.9.4 - Removed output buffer.
+   * @since 5.26.0 - Added filter.
    *
    * @param array $story  Collection of story data.
    * @param array $args   Optional. Additional arguments.
@@ -605,8 +606,8 @@ function fictioneer_get_story_page_cover( $story, $args = [] ) {
     // Setup
     $classes = $args['classes'] ?? '';
 
-    // Build and return
-    return sprintf(
+    // Build, filter, and return
+    $html = sprintf(
       '<figure class="story__thumbnail ' . $classes . '"><a href="%s" %s>%s<div id="ribbon-read" class="story__thumbnail-ribbon hidden"><div class="ribbon">%s</div></div></a></figure>',
       get_the_post_thumbnail_url( $story['id'], 'full' ),
       fictioneer_get_lightbox_attribute(),
@@ -616,6 +617,8 @@ function fictioneer_get_story_page_cover( $story, $args = [] ) {
       )),
       _x( 'Read', 'Caption of the _read_ ribbon.', 'fictioneer' )
     );
+
+    return apply_filters( 'fictioneer_filter_story_page_cover_html', $html, $story, $args );
   }
 }