1. Start
  2. Introduction
  3. Installation
  4. Plugin Description
    1. Fields description
  5. Getting Started
    1. Open widget's options panel
    2. Set a title
    3. Choosing what will be displayed
    4. Ordering
    5. Display options
    6. Settings Page
  6. Additional explanations
    1. Multiple terms relation
  7. CSS Files and Structure
    1. admin.css
    2. widget.css
    3. Edit the CSS file
  8. JavaScript
    1. admin.js
    2. widget.js
  9. PHP Files
    1. plugin.php
    2. admin.php
    3. widget.php
  10. Sources and Credits

Taxonomies Filter Widget

WordPress plugin


Thank you for purchasing my plugin. If you have any questions that are beyond the scope of this help file, please feel free to email me via my user page contact form here. Thanks so much!

Introduction


Taxonomies Filter 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 that you downloaded from Codecanyon, you will see a directory called twf_wordpress_plugin. Inside this directory is a ZIP file called taxonomies-filter-widget.zip which is the actual WordPress plugin. Now you can either:

Regardless of the installation method you used, after you have activated the plugin, please click on the "Widgets" link under the "Appearance" tab. There, you will see a new Widget available for you, called Taxonomies Filter. This is how it should look like:

preview

Now drag the Taxonomies Filter widget inside the widgetized area you want it displayed (eg: Sidebar).

The last step is to click the down arrow handle in order to customize your widget. Please see the next section for the available options.

 

 

Plugin Description


This is an example of the widget's backend interface. If you want to see it live, i have set up a demonstration website here.

Fields description

Title: This is where you set the widget's title.This title will be displayed on your website. 

Select Post Type: 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. 

Taxonomies for: This is a list with all the available taxonomies registered on your website. Besides the built in ones (like: Categories, Tags, Post Format), 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.

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.

 

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 blog,  please feel free to email me via my user page contact form here or by using the email specified on this help file.

Open widget's options panel

Set a title

 

Choosing what will be displayed

Whenever you add a new custom taxonomy to your blog, this list will be automatically updated. There is nothing extra that you need to do.

Ordering

Display options

For each taxonomy you have 3 available options:

  1. dropdown
  2. multiselect
  3. checkbox
  4. radio

This option will set the way that specific option will be displayed on blog.

Settings page

Default: Unchecked.

Default: Unchecked.

Default: Unchecked.

Default: Unchecked.

Default: Dynamic.

 

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. He will receive:

CSS Files and Structure


I'm using two CSS files in this plugin located inside the /css folder. The first one (admin.css) is used for the admin page only while the second one (widget.css), adds some basic display rules for the widget on the front end.

admin.css

This file sets some basic rules for the widget's admin interface. You don't need to modify this file unless you want them to be displayed in a different way.

  1. /* This stylesheet is used to style the admin option form of the widget. */
  2. .taxonomies-admin-list li{
  3. border: 1px solid #DDDDDD;
  4. clear: both;
  5. cursor: move;
  6. line-height: 2.1em;
  7. overflow: hidden;
  8. padding: 0 5px;
  9. }
  10. .taxonomies-admin-list li select{
  11. float:right;
  12. }
  13. .taxonomies-admin-list li input[type="checkbox"],
  14. .taxonomies-admin-list li input[type="radio"],
  15. #taxonomies-filter-advanced input[type="checkbox"],
  16. #taxonomies-filter-advanced input[type="radio"]{
  17. margin: 0;
  18. }
  19. .taxonomies-admin-list .tfw_taxonomy{
  20. background-color: #E7F2F5;
  21. }
  22. .taxonomies-admin-list .tfw_cf_li{
  23. padding: 5px 10px;
  24. background-color: #F2F2E9;
  25. }
  26. .taxonomies-admin-list .tfw_cf_li label{
  27. width:25px;
  28. }
  29. .taxonomies-admin-list .tfw_cf_label{
  30. float: right;
  31. width: 80%;
  32. }
  33. .taxonomies-admin-list .tfw_cf_mode{
  34. float: none;
  35. width: 43%;
  36. }
  37. .taxonomies-admin-list .tfw_cf_unit{
  38. float: none;
  39. width: 23%;
  40. }
  41. .taxonomies-admin-list .tfw_cf_min_max{
  42. width: 42px;
  43. }
  44. .taxonomies-admin-list .tfw_cf_step{
  45. width: 24px;
  46. }

widget.css

This is the stylesheet responsable for how the widget displays on you blog. The CSS options set here are just to make sure the labels, dropdowns, checkboxes, radio buttons and input elements display correctly.

The stylesheet does not apply any colors, borders or fixed width (except the size of the Ajax loading image). This way, the widget will obey the CSS rules applied by your theme and it will nicely blend in.

  1. /* This stylesheet is used to style the public view of the widget. */
  2.  
  3. .taxonomies-filter-widget{
  4. clear: both;
  5. }
  6.  
  7. .taxonomies-filter-widget-form{
  8. max-width: 100%;
  9. padding: 0 0.5em 1em;
  10. overflow: hidden;
  11. }
  12.  
  13. .taxonomies-filter-widget-form label.taxlabel{
  14. font-size: 1.1em;
  15. font-weight: bold;
  16. line-height: 2em;
  17. padding: 0 0.5em;
  18. }
  19. .taxonomies-filter-widget-form select,
  20. .taxonomies-filter-widget-form .input_search{
  21. width:100%;
  22. }
  23. .taxonomies-filter-widget-form .input_cf{
  24. width:25%;
  25. }
  26. .taxonomies-filter-widget-form input[type="text"]{
  27. -webkit-box-sizing: border-box;
  28. -moz-box-sizing: border-box;
  29. box-sizing: border-box;
  30. }
  31. .taxonomies-filter-widget-form button,
  32. .taxonomies-filter-widget-form input,
  33. .taxonomies-filter-widget-form select{
  34. font-size: 100%;
  35. margin: 0 0 0.3em;
  36. vertical-align: baseline;
  37. }
  38. .taxonomies-filter-widget-form ul {
  39. margin: 0;
  40. }
  41. .taxonomies-filter-widget-form ul ul{
  42. margin-bottom: 0;
  43. margin-left: 1.2em;
  44. }
  45. .taxonomies-filter-widget-form li{
  46. list-style: none;
  47. }
  48. .taxonomies-filter-widget-form input[type="submit"]{
  49. margin:0.3em 0 0 0;
  50. float:right;
  51. }
  52. .taxonomies-filter-widget-form .loading_img{
  53. width:43px;
  54. height:11px;
  55. background-image: url('ajax-loader.gif');
  56. display:block;
  57. margin:7px auto 8px;
  58. overflow: hidden;
  59. }
  60. .taxonomies-filter-widget-form .reset_button{
  61. display: block;
  62. float: left;
  63. padding: 0.5em;
  64. }
  65. .taxonomies-filter-widget-form li span{
  66. zoom: 1;
  67. filter: alpha(opacity=60);
  68. opacity: 0.6;
  69. font-size: 0.9em;
  70. }

Edit the CSS file

Let's imagine that you wish to change the color of the labels displayed on the website.

For that, click on the Editor link under the Plugins panel. Now, on the right side, there's a dropdown with all the plugins installed on your blog. Please choose "Taxonomies Filter Widget" and then click on the "taxonomies-filter-widget/css/widget.css" link displayed beneath. After doing that, this is what you should see:

 

Note: As a general rule, before modifying any files in your WordPress installation, please make a backup of that file, just in case something goes wrong. Also, for PHP files, if you modify them using this procedure (not recommended), besides the backup, please disable the plugin before modifying it.

Inside that window, find the .taxonomies-filter-widget-form .taxlabel (highlighted with yellow in the image). By default it should look like that:

.taxonomies-filter-widget-form .taxlabel{
    font-weight: bold;
    margin: 0;
    padding:0.2em 0.4em;
}

Replace it with:

.taxonomies-filter-widget-form .taxlabel{
    font-weight: bold;
    margin: 0;
    padding:0.2em 0.4em;
    color: red;
}

Notice the color:red; added? By using that, from now on, all the labels will be red.

Make sure that you press the "Update file" button for changes to take effect.

 

JavaScript


There are 2 separate files inside the /js folder. First one, (admin.js), is used in the admin panel for ordering and to toggle the advanced options pane while the second one, (widget.js), is used to handle functions like the drill down for dropdowns on the front end.

Both JS files depend on jQuery and are enqued accordingly

admin.js

  1. (function ($) {
  2. "use strict";
  3. $(function () {
  4.  
  5.  
  6. // update the list with available taxonomies whenever you change the post type
  7. $('.widget-liquid-right').on('change', '.tfw_post_type', function(){
  8. var widget = $(this).closest('div.widget');
  9. wpWidgets.save(widget, 0, 1, 0);
  10. });
  11.  
  12. // make the taxonomies lis sortable
  13. $('.widget-liquid-right').on('mouseenter', 'ul.taxonomies-admin-list', function() {
  14. $(this).sortable();
  15. });
  16. });
  17. }(jQuery));

 

widget.js

  1. (function ($) {
  2. "use strict";
  3. $(function () {
  4.  
  5.  
  6. var twfForm = $(".taxonomies-filter-widget-form");
  7. var twfFormAjax = $(".tfw_auto");
  8. // Handle Ajax DrillDowns
  9. twfForm.on('change','.tax-with-childrens', function(e) {
  10. e.preventDefault();
  11. var myForm = $(this).closest("form");
  12. var tax = $(this).attr('id');
  13. var term = $(this).val();
  14. var current_selection = $(this);
  15. var ajaxLoader = '<div class="loading_img"></div>';
  16. $(this).after(ajaxLoader);
  17. $.ajax
  18. (
  19. {
  20. type: "POST",
  21. url: ajax_object.ajax_url,
  22. data: {
  23. action: 'get_term_childrens',
  24. taxonomy: tax,
  25. term: term
  26. },
  27. success:function(results)
  28. {
  29.  
  30. if (results){
  31. $(current_selection).nextAll("#sub_cat_" + tax + ", .loading_img").remove();
  32. $(current_selection).after(results);
  33. if (myForm.hasClass("tfw_auto")) { myForm.submit(); };
  34. } else {
  35. $(current_selection).nextAll("#sub_cat_" + tax + ", .loading_img").remove();
  36. if (myForm.hasClass("tfw_auto")) { myForm.submit(); };
  37. }
  38. }
  39. }
  40. );
  41. });
  42.  
  43. // Select Multiple
  44. $('.taxonomies-filter-widget-form select[multiple]').change(function() {
  45. var values = $(this).closest('li').find("select[multiple] option:selected").map(function () { return this.value; }).get().join(ajax_object.relation);
  46. $(this).closest('li').find("input[type=hidden]").val(values);
  47. });
  48.  
  49. // Multiple Checkboxes
  50. $('.taxonomies-filter-widget-form input:checkbox').change(function() {
  51. var values = $(this).closest('ul.checkboxes_list').find("input:checked").map(function () { return this.value; }).get().join(ajax_object.relation);
  52. $(this).closest('ul.checkboxes_list').find("input[type=hidden]").val(values);
  53. });
  54. // Auto submit
  55. twfFormAjax.on('change', ".noUiSlider, input, select:not(.tax-with-childrens)", function() {
  56. $(this).closest('form').submit();
  57. })
  58.  
  59. // Clear the url from empty elements
  60. twfForm.on('submit', function() {
  61.  
  62. $(this).find('input:not([name=s], [type=hidden], .input_cf), select').each(function() {
  63. if (this.value == '0' || this.value == '') {
  64. $(this).prop("disabled", true);
  65. }
  66. });
  67.  
  68. });
  69.  
  70. // Enable all previously disabled elements
  71. twfForm.find('input[type=text], select').each(function() {
  72. $(this).prop("disabled", false);
  73. });
  74.  
  75. });
  76. }(jQuery));
  77.  

 

PHP Files


This plugin has 3 PHP files responsable for creating the widget, displaying the admin panel and for displaying the widget on your blog. These files are:

plugin.php

This file is located in the root of the "taxonomies-filter-widget" folder. This is the main file that holds the php Class responsable with the creation and registration of the widget.

Please do not modify this file, unless you are familiar with PHP and you know what your doing.

 

To separate business logic from presentation logic, the next two files are included in the main plugin.php file when required.

admin.php

This file is located inside the /views folder and it is used to markup the administration form of the widget.

widget.php

This file is located inside the /views folder and it is used to markup the public-facing widget.

 

Sources and Credits


This plugin uses only one image "css/ajax-loader.gif"  which has been generated with http://www.ajaxload.info/ (it is stated at the bottom of the website that "Generated gifs are totally free for use"). For the range slider, this plugin uses noUiSlider jQuery slider (jquery.nouislider.min.js and nouislider.fox.css) which is free to use in commercial projects. No other images or sounds are provided with this plugin. The PHP code used to create the plugin has been written by following the standards set by the WordPress Codex. The plugin is written in OOP PHP, using the Widgets API


Once again, thank you so much for purchasing this plugin. As I said at the beginning, I'd be glad to help you if you have any questions relating to this plugin. No guarantees, but I'll do my best to assist. If you have a more general question relating to the plugins on Codecanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.

Cristian Ionel