BNS Featured Category Plugin

Plugin with multi-widget functionality that displays most recent posts from specific category or categories (set with user options). Also includes user options to display: Category Description; Author and meta details; comment totals; post categories; post tags; and either full post, excerpt, or your choice of the amount of words (or any combination). Please make sure to read the latest changelog for new and modified features and options.
* Copyright 2009-2016 Edward Caissie (email : [email protected])

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2,
as published by the Free Software Foundation.

You may NOT assume that you can use any other version of the GPL.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

The license for this software can also likely be found here:
http://www.gnu.org/licenses/gpl-2.0.html

• Please note, support may be available on the WordPress Support forums; but, it may be faster to visit http://buynowshop.com/plugins/bns-featured-category/ and leave a comment with the issue you are experiencing.

This section describes how to install the plugin and get it working.

1. Upload bns-featured-category.php to the /wp-content/plugins/ directory
2. Activate through the ‘Plugins’ menu.
3. Place the BNS Featured Category widget appropriately in the Appearance | Widgets section of the dashboard.
4. Set options to personal preferences, for example:

• Widget Title
• Categories – separated by commas
• Show (first) Category Description (checkbox)
• Show Author and date/time details of post (checkbox)
• Show all categories attached to post (checkbox)
• Show all tags attached to post (checkbox)
• Show post in full or use default of post excerpt (checkbox)

— or –

1. Go to ‘Plugins’ menu under your Dashboard
2. Click on the ‘Add New’ link
3. Search for bns-featured-category
4. Install.
5. Activate through the ‘Plugins’ menu.
6. Place the BNS Featured Category widget appropriately in the Appearance | Widgets section of the dashboard.
7. Set options to personal preferences, for example:

• Widget Title
• Categories – separated by commas
• Show (first) Category Description (checkbox)
• Show Author and date/time details of post (checkbox)
• Show all categories attached to post (checkbox)
• Show all tags attached to post (checkbox)
• Show post in full or use default of post excerpt (checkbox)

Read this article for further assistance: http://wpfirstaid.com/2009/12/plugin-installation/

Shortcode: bnsfc

Parameters are very similar to the plugin:

• ‘title’ => __( ‘Featured Category’, ‘bns-fc’ ),
• ‘cat_choice’ => ‘1’,
• ‘display_children’ => false,
• ‘union’ => false,
• ‘use_current’ => false,
• ‘count’ => ‘0’,
• ‘show_count’ => ‘3’,
• ‘offset’ => ‘0’,
• ‘sort_order’ => ‘DESC’,
• ‘use_thumbnails’ => true,
• ‘content_thumb’ => ‘100’,
• ‘excerpt_thumb’ => ’50’,
• ‘show_meta’ => false,
• ‘show_comments’ => false,
• ‘show_cats’ => false,
• ‘show_cat_desc’ => false,
• ‘link_title’ => false,
• ‘show_tags’ => false,
• ‘featured_image_first’ => false,
• ‘only_titles’ => false,
• ‘no_titles’ => false,
• ‘show_full’ => false,
• ‘excerpt_length’ => ”,
• ‘no_excerpt’ => false

NB: Use the shortcode at your own risk!

1. 

   The options panel as it appears in default.

Where do I put my custom stylesheet?

You will need to use an FTP client to add the /bns-customs/ folder under the /wp-content/ folder, then place your bns-custom-style.css file in the /bns-customs/ folder.

Why did you add the `/bns-customs/` folder?

The /bns-customs/ folder will be used as an update safe location for all plugins I write.
As most of these plugins use the “BNS” designator, the folder name will make it easier to locate your customizations.

Can I use this in more than one widget area?

Yes, this plugin has been made for multi-widget compatibility. Each instance of the widget will display, if wanted, differently than every other instance of the widget.

How can I style the plugin output?

The plugin uses several “common” WordPress functions that create standard class and id elements that can be styled in the style.css file
* the classes generated by the post_class() function; and, the id generated by “post-” appended to the_ID() function wrap the general post output
* the plugin class post-details wraps the general meta details of the post, such as the Author, Categories, Tags, etc.
* the overall plugin may also be wrapped in a widget “container” class, or id, specific to the theme itself such as (but not limited to): widget, sidebar, left, right, etc.

As of version 1.9, you may create a custom stylesheet using the name bnsfc-custom-style.css; and save it to the BNS Featured Category plugin folder.
Elements you add into this file will not be overwritten with future plugin updates. With the addition of the display Category Description option an additional class was written into the plugin.
To style the category description displayed add the class ‘bnsfc-cat-desc’ to your bnsfc-custom-style.css file then use your choice of properties to style the text, for example:

.bnsfc-cat-desc {font-style: italic;} 

What style elements are specifically generated by the plugin?

The following CSS elements are generated by the plugin code:

• .bns-featured-category
• .bnsfc-widget-title
• .bnsfc-container
• .bnsfc-link
• .bnsfc-cat-class-< category choice(s) >
• .bnsfc-cat-desc
• .bnsfc-clear
• .bnsfc-content
• .bnsfc-no-posts-message

Additional style elements may be available but are most likely created through WordPress core functionality, the current active Theme, or another active plugin.

Can I increase the maximum posts to display?

As of version 1.6.2 the Total Posts to Display is independent of the “posts per page” setting as set under Settings | Reading.

2.8.2

• Released March 2016
• Added new custom meta field sort option (props Billy Solo)

2.8.1

• Released February 2016
• Added i18n language files

2.8

• Released February 2016
• Added “Title” option to sort order, both “A to Z” and “Z to A”
• Changed plugin class to “singleton” style
• Moved “in plugin update message” function into class
• Renamed BNS_Feature_Category_Widget to BNS_Featured_Category
• Replaced BNS_Featured_Category::custom_excerpt with wp_trim_words
• Updated copyright year in all files

2.7.2

• Released August 2015
• Updated to use PHP5 constructor objects

2.7.1

• Released March 2015
• Update copyright years
• Remove extraneous structure end comments …
• Changed textdomain from bns-fc to bns-featured-category
• Added “in plugin” update message

2.7

• Released August 2014
• Add new constants for use with plugin path and URL functionality
• Added CSS wrapper class to separate shortcode style elements from widget usage
• Added new option “Featured Image First” to display before balance of post
• Added new style enqueue statement to read from update safe folder
• Added sanity check to ensure there are “child categories” to display
• Fixed sort order implementation
• Updated inline documentation
• Updated readme.txt

2.6

• Released March 2014
• Added bnsfc-container wrapper CSS element
• Added bnsfc-widget-title class
• Added bnsfc_no_posts_message hook to no posts message
• Added option to only show posts from child categories
• Added a “wish link” and “support_link” to the plugin meta row
• Code Reformatting to better match current WordPress Coding Standards
• Extracted code to create plugin_data method
• Moved BNSFC Plugin Meta function into main class of plugin
• Raised required version to WordPress 3.6
• Updates to the readme.txt documentation

2.5

• Released December 2013
• Add new “union” option so posts must be in all categories chosen
• Add hook bnsfc_query allowing the query arguments to be over-written
• Add hook bnsfc_output allowing the entire output to be over-written
• Add hook bnsfc_link to allow the infinity symbol to be more easily changed
• Add plugin row meta details

2.4.3

• Released September 2013
• Added third parameter to shortcode_atts for automatic filter creation

2.4.2

• Released May 2013
• Version number compatibility update

2.4.1

• Released February 2013
• Added code block termination comments and other comments / documentation updates
• Changed call to query_posts to WP_Query
• Fixed conditionals for showing thumbnails
• Fixed where content and excerpt post thumbnail sizes are used
• Moved all code into class structure

2.4

• Released February 2013
• Assigned the string from get_the_excerpt to be used as the basis of the custom excerpt string
• Added conditional to only append link if there are words to be used in the excerpt
• Added termination comments to code blocks
• Added dynamic version to enqueue parameters used in Options
• Refactored code into a more OOP style

2.3

• Released November 2012
• Add option to use widget title as link to single category archive
• Add filters to allow modification of author and date post meta details
• Add filters to allow modification of category list post meta details
• Documentation updates
• Optimize output buffer closure in shortcode function
• Remove load_plugin_textdomain as redundant
• Updated widget option panel screenshot

2.2

• Documentation updates
• Corrected ‘no_excerpt” label issue
• Featured images link to post
• Remove ‘jQuery’ enqueue as it is enqueued as a dependency of the ‘bnsfc-options.js’ enqueue
• Added option to not show the Post Title
• Programmatically add version number to enqueue calls

2.1

• Added option to set post sort order – ascending, descending, and random
• Added ‘no excerpt at all’ checkbox option

2.0

• Added BNS_Options_Scripts_and_Styles
• Added inline documentation indicating what conditions will partially collapse the widget options panel
• Added *-toggle variables for collapse effect
• Added code to remove spaces (if used) when multiple categories are chosen
• Added current_theme_supports check for post-thumbnails; no support = no thumbnail options

1.9.3

• Fixed problem with non-existent custom stylesheet (see 1.9.1)

1.9.2

• Added ‘offset’ option
• Add CSS to set background to none; and width to 100% when shortcode used

1.9.1

• Removed extra slash in wp_enqueue_scripts parameters
• Added ‘content_thumb’ and ‘show_full’ to shortcode options – back to beta
• Fixed 404 error when ‘bnsft-custom-style.css’ is not available

1.9

• released November 2011
• confirmed compatible with WordPress 3.3
• added phpDoc Style documentation
• added i18n support
• added bnsfc-style.css for plugin specific elements
• added wp_link_pages after the_content
• changed code blocks order to more logical sequence
• changed bnsfc_first_words to bnsfc_custom_excerpt (refactored documentation)
• changed options panel width to 200px to fit within Administration Panel Sidebar
• changed bns-cat-class- to bnsfc-cat-class- CSS prefix for category choices for consistency
• corrected documentation typos
• fix ‘only_titles’ form issue
• minor code and format clean-up
• updated ‘readme.txt’ Frequently Asked Questions
• updated screenshot image

1.8.5

• released May 2011
• confirmed compatible with WordPress version 3.2
• addressed some minor items in the readme (this file)
• cleaned up some text strings in the code
• minor variable changes – load_bnsfc_widget(), bnsfc_custom_excerpt()

1.8.4 / 1.8.4.1

• released April 2011
• confirmed compatible with WordPress 3.1.1
• added option to use current category of post in single view

1.8.3

• released December 11, 2010
• Confirm compatible with WordPress 3.1 (beta)
• Change ‘the_time’ to date-format option
• Only show number of comments if not password protected

1.8.2

• released Sept 21, 2010
• added new and improved shortcode functionality – still may be considered beta

1.8.1

• removed shortcode function due to error issues

1.8

• released Sept 19, 2010
• increased minimum required WordPress version to 2.9
• add post_thumbnail support
• added experimental shortcode support – currently best used to generate the only content on a post or page

1.7.2

• released: 29 Aug 2010
• compatibility check for WordPress 3.0.1
• no other modifications

1.7.1

• released: July 5, 2010
• cleaned up code to meet WP Standards
• added wp_reset_query();

1.7

• compatible with WordPress version 3.0
• updated license declaration

1.6.3

• removed the_ID() function as redundant
• added category related span around widget title

1.6.2.3

• compatible with WordPress version 2.9.2
• updated license declaration

1.6.2.2

• clarified the plugin release under a GPL license

1.6.2.1

• compatibility check for 2.9.1 completed

1.6.2

• Total Posts to Display can now exceed the posts_per_page option value.

1.6.1

• Minor correction to variable structure to allow for multiple instances of the plugin with independent post counts

1.6

• added option to display the description for the (first) category choice as taken directly from the Categories panel under Posts in the Dashboard
• wrapped Category Description in its own class: ‘bnsfc-cat-desc’
• corrected issue with checkbox not displaying its state correctly
• Updated the screenshot to show the most recent version of the options panel

1.5.1

• modified excerpt function name to make more unique to plugin

1.5

• added option to set the quantity of the first words of the post to display instead of the default excerpt.
• modified description to reflect new functionality
• slightly increased the size of option panel to better display controls

1.4

• added version control compared against $wp_version
• added horizontal rule to option panel for clarity

1.3

• code cleanup and error trapping
• added dynamic reference of maximum posts based on blog Settings | Reading “posts per page”

1.2

• code clean up
• changed the_content(__(‘Read more …’)) to the_content() as a more “default” version

1.1

• added option for Post Titles only
• added <div style="overflow-x: auto"> wrapper to allow for images wider than the widget area

1.0

• Initial Release.