Merge pull request #1676 from INN/1595-add-note-about-largos-category…

…-featured-posts-function-to-category.php

Added note to category.php to explain how to...

category.php

@@ -44,7 +44,33 @@
 				); ?>
 			</div>
 
-			<?php $secondary_featured = array_slice( $featured_posts, 1 );
+			<?php
+
+			/*
+			 * NOTE: If you are trying to accomplish something other than displaying no featured posts 
+			 * or displaying 5 featured posts, you will need to modify the `largo_category_archive_posts` function
+			 * located at https://github.com/INN/largo/blob/master/inc/featured-content.php#L167, since it modifies the 
+			 * category posts query in order to obtain the category featured posts. If you modify this section, but not 
+			 * `largo_category_archive_posts`, some of your posts will go missing on the category page.
+			 *
+			 * There are two primary ways to replace the `largo_category_archive_posts` function:
+			 *
+			 * 1. Modify the `largo_category_archive_posts` function to not perform the featured post removal from certain queries
+			 *      - This will require using `remove_action( 'pre_get_posts', 'largo_category_archive_posts', 15 )` to remove
+			 *        the current function and using `add_action` to add in your replacement function.
+			 * 
+			 * 2. Modify the `largo_category_archive_posts` function to use a modified `largo_get_featured_posts_in_category`
+			 *    function that will return a different selection of posts for the specified category.
+			 *      - This will also require using `remove_action( 'pre_get_posts', 'largo_category_archive_posts', 15 )` to remove
+			 *        the current function and using `add_action` to add in your replacement function.
+			 *      - This also requires creating a modified version of the `largo_get_featured_posts_in_category` function
+			 *        and replacing it in templates where it is used.
+			 *      - In order to change the number of posts returned by your modified `largo_category_archive_posts` function,
+			 *        ->get( 'category_name' ) );`
+			 *        to reflect your preferred number of featured posts.
+			 */
+
+			$secondary_featured = array_slice( $featured_posts, 1 );
 			if ( count( $secondary_featured ) > 0 ) { ?>
 				<div class="secondary-featured-post">
 					<div class="row-fluid clearfix"><?php

changelog.md

@@ -42,6 +42,7 @@ This release contains bug fixes for Largo 0.6.
 - Fixes issue where the header ad widget area and before-footer widget area could extend beyond hte viewport, causing horizontal scrolling on narrower screens. [Pull request #1673](https://github.com/INN/largo/pull/1673) for [issue #1670](https://github.com/INN/largo/issues/1670).
 - Uses `validate_file()` when using `require_once`. [Pull request #1589](https://github.com/INN/largo/pull/1589) for [issue #1494](https://github.com/INN/largo/issues/1494).
 - Further cleans up undefined variables.
+- Added note to `category.php` template explaining how to modify displaying the featured posts on category pages. [Pull request #1676](https://github.com/INN/largo/pull/1676) for [issue #1595](https://github.com/INN/largo/issues/1595).
 - Added `display: block;` style attribute to `.navis-slideshow.navis-full` to prevent full size images from not displaying properly due to the `display: table;` attribute on all `.wp-block-image` alignment classes. [Pull request #1675](https://github.com/INN/largo/pull/1675) for [issue #1664](https://github.com/INN/largo/issues/1664).
 
 ### Upgrade notices