From 69d8f77432b4583a244eb23eb7f9aecf144427bd Mon Sep 17 00:00:00 2001
From: Tetrakern <26898880+Tetrakern@users.noreply.github.com>
Date: Mon, 14 Oct 2024 11:36:10 +0200
Subject: [PATCH] Extend fictioneer_post_{*} action hooks

---
 ACTIONS.md                               | 44 +++++++++++++++++------
 includes/functions/_setup-shortcodes.php |  2 +-
 includes/functions/hooks/_post_hooks.php | 46 +++++++++++++++++-------
 partials/_loop.php                       |  2 +-
 partials/_post.php                       | 12 ++++---
 single-post.php                          |  7 ++--
 6 files changed, 82 insertions(+), 31 deletions(-)

diff --git a/ACTIONS.md b/ACTIONS.md
index 0ec3355c..0bbedec9 100644
--- a/ACTIONS.md
+++ b/ACTIONS.md
@@ -816,37 +816,61 @@ Fires after opening the `.main-navigation__wrapper` container in the `_navigatio
 
 ---
 
-### `do_action( 'fictioneer_post_after_content', $post_id )`
-Fires between the article content and featured list (if any) in the `single-post.php` template.
+### `do_action( 'fictioneer_post_after_content', $post_id, $args )`
+Fires right after the article content in the `_post.php` partial and `single-post.php` template. Mind the render context, which can be `'loop'`, `'shortcode_fictioneer_blog'`, or `'single-post'`.
 
 **Parameters:**
 * $post_id (int) – Current post ID.
 
+**$args:**
+* `context` (string) – Render context of the partial.
+* `nested` (boolean|null) – Optional. Whether the post is nested inside another query.
+
 **Hooked Actions:**
-* `fictioneer_post_tags( $post_id )` – Tags of the post. Priority 10.
-* `fictioneer_post_featured_list( $post_id )` – Items featured in the post. Priority 20.
+* `fictioneer_post_tags( $post_id, $args )` – Tags of the post. Priority 10.
+* `fictioneer_post_featured_list( $post_id, $args )` – Items featured in the post. Priority 20.
 
 ---
 
-### `do_action( 'fictioneer_post_footer_left', $post_id )`
-Fires inside the `.post__footer-left` container within the article footer in the `single-post.php` template. Normally includes the sharing modal toggle and feed links.
+### `do_action( 'fictioneer_post_footer_left', $post_id, $args )`
+Fires inside the `.post__footer-left` container within the article footer in the `_post.php` partial and `single-post.php` template. Mind the render context, which can be `'loop'`, `'shortcode_fictioneer_blog'`, or `'single-post'`.
 
 **Parameters:**
 * $post_id (int) – Current post ID.
 
+**$args:**
+* `context` (string) – Render context of the partial.
+* `nested` (boolean|null) – Optional. Whether the post is nested inside another query.
+
 **Hooked Actions:**
-* `fictioneer_post_media_buttons()` – Buttons for sharing and webfeeds. Priority 10.
+* `fictioneer_post_media_buttons( $post_id, $args )` – Buttons for sharing and webfeeds. Priority 10.
 
 ---
 
-### `do_action( 'fictioneer_post_footer_right', $post_id )`
-Fires inside the `.post__footer-right` container within the article footer in the `single-post.php` template. Normally includes the subscribe button with popup menu.
+### `do_action( 'fictioneer_post_footer_right', $post_id, $args )`
+Fires inside the `.post__footer-right` container within the article footer in the `_post.php` partial and `single-post.php` template. Mind the render context, which can be `'loop'`, `'shortcode_fictioneer_blog'`, or `'single-post'`.
 
 **Parameters:**
 * $post_id (int) – Current post ID.
 
+**$args:**
+* `context` (string) – Render context of the partial.
+* `nested` (boolean|null) – Optional. Whether the post is nested inside another query.
+
 **Hooked Actions:**
-* `fictioneer_post_subscribe_button()` – Subscription popup menu. Priority 10.
+* `fictioneer_post_subscribe_button( $post_id, $args )` – Subscription popup menu. Priority 10.
+
+---
+
+### `do_action( 'fictioneer_post_header_open', $post_id, $args )`
+Fires right after the post header is opened in the `_post.php` partial and `single-post.php` template, before anything else is rendered. Mind the render context, which can be `'loop'`, `'shortcode_fictioneer_blog'`, or `'single-post'`.
+
+**Parameter:**
+* $post_id (int) – The ID of the post.
+
+**$args:**
+* `context` (string) – Render context of the partial.
+* `nested` (boolean|null) – Optional. Whether the post is nested inside another query.
 
 ---
 
diff --git a/includes/functions/_setup-shortcodes.php b/includes/functions/_setup-shortcodes.php
index feecfef2..7839d159 100644
--- a/includes/functions/_setup-shortcodes.php
+++ b/includes/functions/_setup-shortcodes.php
@@ -1643,7 +1643,7 @@ function fictioneer_shortcode_blog( $attr ) {
       <?php
         while ( $blog_query->have_posts() ) {
           $blog_query->the_post();
-          get_template_part( 'partials/_post', null, array( 'nested' => true ) );
+          get_template_part( 'partials/_post', null, array( 'nested' => true, 'context' => 'shortcode_fictioneer_blog' ) );
         }
 
         wp_reset_postdata();
diff --git a/includes/functions/hooks/_post_hooks.php b/includes/functions/hooks/_post_hooks.php
index b38074ac..aaca337f 100644
--- a/includes/functions/hooks/_post_hooks.php
+++ b/includes/functions/hooks/_post_hooks.php
@@ -8,11 +8,18 @@
  * Outputs the HTML for the post tags
  *
  * @since 5.0.0
+ * @since 5.25.0 - Added $args.
  *
- * @param int $post_id  The post ID.
+ * @param int   $post_id  The post ID.
+ * @param array $args     Additional arguments.
  */
 
-function fictioneer_post_tags( $post_id ) {
+function fictioneer_post_tags( $post_id, $args ) {
+  // Check render context
+  if ( ( $args['context'] ?? 0 ) !== 'single-post' ) {
+    return;
+  }
+
   // Setup
   $tags = get_the_tags( $post_id );
 
@@ -27,7 +34,7 @@ function fictioneer_post_tags( $post_id ) {
   </section>
   <?php // <--- End HTML
 }
-add_action( 'fictioneer_post_after_content', 'fictioneer_post_tags', 10 );
+add_action( 'fictioneer_post_after_content', 'fictioneer_post_tags', 10, 2 );
 
 // =============================================================================
 // FEATURED
@@ -37,11 +44,18 @@ add_action( 'fictioneer_post_after_content', 'fictioneer_post_tags', 10 );
  * Outputs the HTML for featured items in the post
  *
  * @since 5.0.0
+ * @since 5.25.0 - Added $args.
  *
- * @param int $post_id  The post ID.
+ * @param int   $post_id  The post ID.
+ * @param array $args     Additional arguments.
  */
 
-function fictioneer_post_featured_list( $post_id ) {
+function fictioneer_post_featured_list( $post_id, $args ) {
+  // Check render context
+  if ( ( $args['context'] ?? 0 ) !== 'single-post' ) {
+    return;
+  }
+
   global $post;
 
   // Abort if...
@@ -106,7 +120,7 @@ function fictioneer_post_featured_list( $post_id ) {
   </section>
   <?php // <--- End HTML
 }
-add_action( 'fictioneer_post_after_content', 'fictioneer_post_featured_list', 20 );
+add_action( 'fictioneer_post_after_content', 'fictioneer_post_featured_list', 20, 2 );
 
 // =============================================================================
 // POST MEDIA BUTTONS
@@ -116,18 +130,22 @@ add_action( 'fictioneer_post_after_content', 'fictioneer_post_featured_list', 20
  * Outputs the HTML for the post media buttons
  *
  * @since 5.0.0
+ * @since 5.25.0 - Added parameters.
+ *
+ * @param int   $post_id  The post ID.
+ * @param array $args     Additional arguments.
  */
 
-function fictioneer_post_media_buttons() {
+function fictioneer_post_media_buttons( $post_id, $args ) {
   // Abort if...
-  if ( post_password_required() ) {
+  if ( post_password_required() || ( $args['context'] ?? 0 ) !== 'single-post' ) {
     return;
   }
 
   // Render media buttons
   echo fictioneer_get_media_buttons();
 }
-add_action( 'fictioneer_post_footer_left', 'fictioneer_post_media_buttons', 10 );
+add_action( 'fictioneer_post_footer_left', 'fictioneer_post_media_buttons', 10, 2 );
 
 // =============================================================================
 // POST SUBSCRIBE BUTTONS
@@ -137,11 +155,15 @@ add_action( 'fictioneer_post_footer_left', 'fictioneer_post_media_buttons', 10 )
  * Outputs the HTML for the post subscribe button with popup menu
  *
  * @since 5.0.0
+ * @since 5.25.0 - Added parameters.
+ *
+ * @param int   $post_id  The post ID.
+ * @param array $args     Additional arguments.
  */
 
-function fictioneer_post_subscribe_button() {
+function fictioneer_post_subscribe_button( $post_id, $args ) {
   // Abort if...
-  if ( post_password_required() ) {
+  if ( post_password_required() || ( $args['context'] ?? 0 ) !== 'single-post' ) {
     return;
   }
 
@@ -157,4 +179,4 @@ function fictioneer_post_subscribe_button() {
     <?php // <--- End HTML
   }
 }
-add_action( 'fictioneer_post_footer_right', 'fictioneer_post_subscribe_button', 10 );
+add_action( 'fictioneer_post_footer_right', 'fictioneer_post_subscribe_button', 10, 2 );
diff --git a/partials/_loop.php b/partials/_loop.php
index bb1f6dc6..a6bfef3d 100644
--- a/partials/_loop.php
+++ b/partials/_loop.php
@@ -22,7 +22,7 @@ defined( 'ABSPATH' ) OR exit;
     <?php
       while ( have_posts() ) {
         the_post();
-        get_template_part( 'partials/_post' );
+        get_template_part( 'partials/_post', null, array( 'context' => 'loop' ) );
       }
 
       $pag_args = array(
diff --git a/partials/_post.php b/partials/_post.php
index 93fa480b..2d4c848e 100644
--- a/partials/_post.php
+++ b/partials/_post.php
@@ -10,7 +10,8 @@
  * @since 2.0
  * @see partials/_loop.php
  *
- * @internal $args['nested']  Whether the post is nested inside another query. Default null.
+ * @internal $args['nested']   Whether the post is nested inside another query. Default null.
+ * @internal $args['context']  Render context of the partial ('loop' or 'shortcode_fictioneer_blog').
  */
 
 
@@ -36,19 +37,22 @@ if (
 <article id="post-<?php echo $post_id; ?>" class="post">
 
   <header class="post__header">
+    <?php do_action( 'fictioneer_post_header_open', $post_id, $args ); ?>
     <h2 class="post__title h1"><a href="<?php the_permalink(); ?>"><?php echo $title; ?></a></h2>
     <div class="post__meta layout-links"><?php echo fictioneer_get_post_meta_items(); ?></div>
   </header>
 
   <section class="post__main content-section"><?php echo $content; ?></section>
 
-  <?php if ( has_action( 'fictioneer_blog_posts_footers_left' ) || has_action( 'fictioneer_blog_posts_footers_right' ) ) : ?>
+  <?php do_action( 'fictioneer_post_after_content', $post_id, $args ); ?>
+
+  <?php if ( has_action( 'fictioneer_post_footer_left' ) || has_action( 'fictioneer_post_footer_right' ) ) : ?>
     <footer class="post__footer">
       <div class="post__footer-box post__footer-left">
-        <?php do_action( 'fictioneer_blog_posts_footers_left', $post_id ); ?>
+        <?php do_action( 'fictioneer_post_footer_left', $post_id, $args ); ?>
       </div>
       <div class="post__footer-box post__footer-right">
-        <?php do_action( 'fictioneer_blog_posts_footers_right', $post_id ); ?>
+        <?php do_action( 'fictioneer_post_footer_right', $post_id, $args ); ?>
       </div>
     </footer>
   <?php endif; ?>
diff --git a/single-post.php b/single-post.php
index 14425934..550c6f1c 100644
--- a/single-post.php
+++ b/single-post.php
@@ -35,21 +35,22 @@ get_header();
       <article id="post-<?php the_ID(); ?>" class="post__article">
 
         <header class="post__header">
+          <?php do_action( 'fictioneer_post_header_open', $post_id, array( 'context' => 'single-post' ) ); ?>
           <h1 class="post__title"><?php echo $title; ?></h1>
           <div class="post__meta layout-links"><?php echo fictioneer_get_post_meta_items(); ?></div>
         </header>
 
         <section class="post__main content-section"><?php the_content(); ?></section>
 
-        <?php do_action( 'fictioneer_post_after_content', $post->ID ); ?>
+        <?php do_action( 'fictioneer_post_after_content', $post->ID, array( 'context' => 'single-post' ) ); ?>
 
         <?php if ( ! $password_required && ( has_action( 'fictioneer_post_footer_left' ) || has_action( 'fictioneer_post_footer_right' ) ) ) : ?>
           <footer class="post__footer">
             <div class="post__footer-box post__footer-left">
-              <?php do_action( 'fictioneer_post_footer_left', $post->ID ); ?>
+              <?php do_action( 'fictioneer_post_footer_left', $post->ID, array( 'context' => 'single-post' ) ); ?>
             </div>
             <div class="post__footer-box post__footer-right">
-              <?php do_action( 'fictioneer_post_footer_right', $post->ID ); ?>
+              <?php do_action( 'fictioneer_post_footer_right', $post->ID, array( 'context' => 'single-post' ) ); ?>
             </div>
           </footer>
         <?php endif; ?>