Plugin Settings Page
The documentation here has been updated for version 2.x of this plugin.
When you first install your plugin, you will need to activate it with the license key provided at the time of purchase. Visit the plugin setting page by selecting Settings then Featured Images for Categories Pro in your WordPress Dashboard.
The settings page is shown below.
You can set the default options for the plugin, the shortcodes and widgets discussed later in this documentation will override these defaults.
- When displaying all of your featured images you can select how much padding in pixels each image will have around it
- Select the number of columns for the output of featured images
- Select the image size for the display of featured images – this supports all registered images sizes in your WordPress theme
Display featured images with a shortcode
To display featured images for categories or tags on a page or post in your WordPress site use this shortcode.
[FeaturedImagesCat taxonomy='category' columns='3']
Leaving out the columns option will use the default as per the above settings or you can override the defaults by specifying the number of columns in the shortcode.
To use with tags instead change the ‘category’ value to ‘post_tags’.
[FeaturedImagesCat taxonomy='post_tag' columns='3']
The shortcode accepts these arguments to further control the output:
- taxonomy=”the name of your taxonomy” (eg taxonomy=’category’) *
- columns=”number of columns to display” (eg columns=’3′)
- imagesize=”the name of a registered image size in your theme” (eg imagesize=’medium’)
- randomly=”true or false” (eg randomly=’true’)
- showCatName=”true or false” (eg showCatName=’true’)
- showCatDesc=”true or false” (eg showCatDesc=’true’)
- include=”comma separated list of post IDs” (eg include=’2,4,6,23′)
- childrenonly=”comma separated list of post IDs” (eg childrenonly=’1,4,65′)
- hideempty=”0 or 1″ (eg hideempty=’1′ will not show categories with 0 posts)
Below is a more detailed explanation on these shortcode arguments.
To use the plugin with custom taxonomies change ‘category’ the the name of your taxonomy. This feature is only available with the Pro version of the plugin.
[FeaturedImagesCat taxonomy='mytaxonomy' columns='2']
Altering the image size
Instead of using the default image size (thumbnail), use any registered image size by adding a new option imagesize to the shortcode. Please note this must be the name of the registered image size (e.g. home_slider) in your WordPress theme.
[FeaturedImagesCat taxonomy='mytaxonomy' columns='3' imagesize='myImageSize']
Display the images in random order
If you would like to have the images displayed in random order each time a user visits a page, use the new shortcode option “randomly”. Set it to true to have the images ordered this way.
[FeaturedImagesCat taxonomy='category' randomly='true']
This option is also available in the widget.
Important to note, using this option will have preference over the ‘orderby’ option if they are both added to the one shortcode.
Display the Category name and description
There are two arguments that are available to allow the display of the category title and / or the category description:
- showCatName – set to ‘true’ to show the category name under the featured image
- showCatDesc – set to ‘true’ to show the category description under the featured image
[FeaturedImagesCat taxonomy='mytaxonomy' columns='2' showCatName='true']
[FeaturedImagesCat taxonomy='mytaxonomy' columns='2' showCatName='true' showCatDesc='true']
The screenshot below shows an example with category names being printed (click for a larger view).
Category descriptions are core functionality in WordPress, they are editable in the dashboard in the category or custom taxonomy editor.
The screenshot below shows this editor with a description added, it’s this description that can then be displayed by the showCatDesc argument.
Limit the categories that are displayed
The short code now also supports the ability to limit the categories that are printed. With the new argument include you can specify a list of categories using their IDs.
[FeaturedImagesCat taxonomy='mytaxonomy' columns='2' include='2,4,6,23']
There is also an argument that will force the shortcode to only show top level categories (i.e. categories that have no parent).
[FeaturedImagesCat taxonomy='mytaxonomy' columns='2' parentcatsonly="true"]
This option allows you to specify one or more category IDs. The shortcode will then display only categories that are child categories of those specified.
This is how the new option works.
[FeaturedImagesCat taxonomy='category' columns='2' childrenonly="1,4,65"]
From the example, categories that are children on 1, 4 or 65 would be displayed.
Hide categories / taxonomies without posts
Use the argument hideempty to not show categories that don’t have published posts.
[FeaturedImagesCat taxonomy='category' columns='2' hideempty='1']
Show all categories with a widget
There are two widgets available in the plugin. Go to Appearance then Widget in your WordPress Dashboard. The first widget Featured Images for Categories allows you to show all the categories or taxonomies in a widget area.
Start by choosing the data to work with. The Taxonomy drop down will show category, post_tag as well as all of your registered custom taxonomies.
Next choose the number of columns you would like the output to show.
The Order By field allows you to choose the sort order, for example by name, id or slug.
Hide Empty allows you to mute categories that don’t have any posts assigned to them.
The final option, padding, allows you to set the amount of padding (in pixels) each image will receive when displayed.
Show one featured category
The second widget Featured Images for Categories – Term allows you to select one item from a category, tag or custom taxonomy to be displayed in a widget area.
The options are similar to the above widget with the main difference being the Term option.
If you choose category in the taxonomy setting the widget will show you all of the category names for you to select one to feature in this widget.
There is a new option here Display term, this allows you to suppress the printing of the item’s name, or choose to print it above or below the featured image.
Options for developers
Featured Images for Categories Pro has a simple API that allows developers to access the featured images and featured colour information.
If you have questions for further problems that are not covered here please visit our support centre here.