Documentation

Taxonomy Power Widget

Compatibility: WordPress 4.3.1

Changelog

Version 1.1

  • Updated: Chosen updated to version 1.4.2
  • Fixed: Some improvements with default CSS

Version 1.0

  • Initial Release

Introduction

Taxonomy Power Widget creates a widget that acts as a filter for your WordPress categories, tags and taxonomies. Visitors will be able to do faceted searches on your site and filter posts using drop-downs, checkboxes and radio buttons. While built especially for sites with a variety of categories, custom taxonomies and custom posts (eg: shops, directories, tutorials, job boards or listings), this plugin will also do a great job at filtering the standard WordPress posts by categories, tags and even post format.

Installation


In the ZIP file called taxonomy-power-widget.zip, that you downloaded from your account, you will see a directory called taxonomy-power-widget. Inside this directory is where the actual WordPress plugin files are.

Now you can either:

  • Extract and upload this folder manually, using you favorite FTP software, inside the wp-content/plugins/  folder on your WordPress website. If you choose this option, you will have to activate this plugin after you upload it, by clicking the “Activate” link found in the wp-admin under “Plugins → Installed Plugins”, under the plugin called “Taxonomy Power Widget”.
  • Log In as an Admin on your WordPress website and click on the “Add New” link found under the “Plugins” tab in the left hand menu. Now, from the available options at the top of the page, click on “Upload” and then “Browse”. Locate the ZIP file taxonomy-power-widget.zip, press OK then click the “Install Now” button. After the upload is finished, click Activate Plugin.

add_plugins

Plugin Description


This is an example of the widget’s backend interface, found under Appearance → Widgets in the wp-admin. If you want to see the plugin in action, we have set up a live demonstration website here.

taxonomy_power_widget_config

Fields description

  1. Title: This is where you set the widget’s title.This title will be displayed on your website.
  2. Select Post Types: From this dropdown you can select which post type you want to be filtered. When you switch from one post type to another, you will still have the previous selected taxonomies available but i suggest you use only taxonomies specific to that post type.
  3. Taxonomies for: This is a list with all the available taxonomies registered on your website. Besides the built in ones (like: Categories, Tags, Post Formats), this list will also include all the custom taxonomies that you have registered for both regular and custom posts. Updates any time you change the post type.
    • This list is sortable. Just click on any item and drag it to the desired position.
    • Each taxonomy has its own specific display option (dropdown, radio, checkbox).
    • Each display option will respect taxonomy’s hierarchical structure.
    • Dropdowns will act as a drill down only for hierarchical taxonomies.
    • When you click the save button, taxonomies that you’ve selected will be put automatically on top of the list .
  4. Custom fields: This is a list with all the available custom fields registered on your website, for the post type you selected. This list will be populated only with the custom fields that have numeric values, because the filter will use the values to display posts that are between the minimum and maximum value set the by the user.
    • You enable the custom field as a filter by clicking on the checkbox placed on the left side of the name;
    • Use the label field to set the name displayed on the front-end.
    • Min and Max value will automatically load the minimum and maximum value found for that specific custom field, but you can set you own value!
    • Step is used by the range option and will set the step size of the slider when you drag it.
    • Unit will be displayed close to custom field value (left side). Ex: kg, $, EUR, m;
    • Mode allows you to change the way the custom field filter is displayed, you can choose between 2 input boxes (min and max) and a range slider.
  5. Suggestion: When you have custom posts, build your filters using only taxonomies registered for that specific custom post type. You can build as many widgets as you like, for each custom post that you have.

  6. Search box label: Only applies if “Display the checkbox?” option is checked. This option sets the label for the search input.
  7. Reset button label: Text displayed as the reset link.
  8. Search button label: Text displayed as the label of the submit button.
  9. Select all option: Text displayed on dropdowns, for selecting all taxonomies. Leave it empty if you don’t want that option.
  10. Chosen options:
    • Placeholder text for multiple: Text displayed before options are selected.
    • No results text: Text displayed if no results match user search criteria.
    • Search contains: Select this if you wish to limit the max selected options operating on a single search.
    • Max selected options: Select the max number of search selectors per search. “Search contains” above must also be selected.
    • Width (percentage): Enter the width percentage % of the chosen options box.

Getting Started


Assuming that you have followed the installation steps, now you are ready to set up your first filter. If you have followed all the steps and you still don’t see the widget added to your WordPress website, please feel free to email us via our user page contact form or by using the email specified in this help file.

Open widget’s options panel

  • Step 1: Open your widget’s configuration panel by clicking the down arrow on the right side (marked with yellow on the next image).

down_arrow

Set a title

  • Step 2: Set a title for your widget. Depending on your theme, this will be usually displayed above your widget as a heading.

title

Choosing what will be displayed

  • Step 3: From the dropdown menu, select which post type is this filter for. When you choose a post type, this list will automatically update with all the available taxonomies for that post type. From that list, select the ones that you want to be displayed on your website, by clicking on the corresponding checkbox. Whenever you add a new custom taxonomy to your website, this list will be automatically updated. There is nothing extra that you need to do.

post_type_selection

Ordering

  • Step 4: If you like the items to be displayed in a specific order, click on the one that you want to move and (while still having the mouse click pressed), drag into the desired position.
ordering

Display options

  • Step 5: For each taxonomy you checked, select how you want it displayed from the corresponding right side menu.
field_choices

For each taxonomy you have 5 available display options:

These options will set the way that specific taxonomies or fields will be displayed through the Taxonomy Power Widget on your WordPress website.

  1. Chosen
  2. Dropdowns
  3. Multiselect
  4. Checkboxes
  5. Radio Buttons
  6. Any combination or mix of these fields

Slider Settings

  • Step 6 (optional): If you’ve added a numeric field to a custom post type you can use this field data to display a range slider or input variables which can be used as search parameters. Some common uses would be price ranges, or any low/high numerical combinations.
slider_selection
  1. Label: This is what you want to call this item and will show up in the widget as the title of the item using the “taxlabel” css class.
  2. Min / Max: These are the minimum and maximum values used as search delineaters. For example, at least $100 but not more than $200.
  3. Step: This is the increment value. So each increment of the slider will move x steps forward or backwards, depending on the direction moved.
  4. Mode: There are 2 modes, range or input. Range is what produces the slider, input method are distinct values you enter for the search.
  5. Unit: This is the monetary, dimensions, distance ($/€/£/inches/mm/km) or other units of measure.

Settings page

  • Step 7: While your widget is ready to be used by now, let’s have a look at the “Settings page”, maybe we can find something that you’ll be interested in. Let’s start by clicking on the Taxonomy Power Widget link (under the Settings menu) or the Settings link from your plugins page. This will bring up the Taxonomy Power Widget Settings page:
main_settings
  1. Auto submit form: By checking this option, the submit button will hide and the form will auto-submit whenever one of the elements change.
  2. Default: Unchecked.

  3. Hide empty terms: By checking this option, terms which are not assigned to any post, will not be displayed on the frontend.
  4. Default: Unchecked.

  5. Display the search box: Check if you want a search input to be also added to the filter.
  6. Default: Unchecked.

  7. Display the reset button: Check if you want a reset link added at the bottom of the form.
  8. Default: Unchecked.

  9. Display post count: By checking this option, the number of posts to which this term as been assigned, will be appended to the right side, enclosed between round brackets.
    • Total: The total number of posts to which this term is assigned.
    • Dynamic: Number of posts that have the current search query and the current term. Updates on every change in the filter.
    • None: Do not display.
  10. Default: Dynamic.

  11. Multiple terms relation: This only applies to checkboxes. Please check here for a more detailed explanation.
  12. Search results template: From here you can choose what template file should be used to display the filtered results. If you choose “Custom”, you will have have to set “Custom template file name:” to be the name of the file you want to use. This file needs to be inside your theme directory and needs to have the Loop inside. A good way to create a custom template for your search results, would be to duplicate either the archive.php, search.php or any other template file that has the Loop inside, rename it and customize it to suit your needs.

Additional Explanations


Multiple terms relation

This option will alter how the filter behaves when someone selects multiple checkboxes.

This is how it works:

Let’s imagine we have a website with recipes, and someone is searching for a salad. We currently have 3 salad recipes available.

  1. Green salad: salad leaves, green olives
  2. Tropical salad: salad leaves, pineapple, cucumber, mint leaves
  3. Mixed salad: basil leaves, cucumber

Now the user selects from a lists of ingredients: salad leaves and cucumber then clicks submit.

They will receive:

  1. Case: ANDTropical salad – Only the recipe that has both ingredients:
    • salad leaves
    • cucumber
  2. Case: ORGreen salad, Tropical salad and Mixed salad – All the recipes that have at least one of the two ingredients:
    • salad leaves or
    • cucumber