Custom Sorts
AZIndex is great for creating alphabetical indwinexes, it’s what the plugin does for a living. But, with a little extra code, you can use it to create other types of indexes too. Perhaps you’re using WordPress to maintain a catalogue of parts that you would like to sort by part number. If those numbers are not all the same length, then they will not be sorted in the right order by the default AZIndex sort.
There are also some cases where AZIndex may not always deliver the expected result—especially when using other languages. While it would be great if the plugin always delivered the correct result, it does not always happen.
So, what can you do if you can’t get the sorting you need from AZIndex but like everything else about the plugin? Well, there are two different things you can do customize the sorting in your index:
- Use an item filter to modify the data you are going to sort
- Use a custom comparison function in the sort
Item Filter
An item filter is called before the index is sorted and can be used to modify the data in preparation for the sort. For example, if you want to have an index where your posts are sorted in the order of the number of comments they have received, you can do this by using the filter code to query the number of comments each post has and placing that number in the sort-head field in the array you are passed (you would have to add leading zeros to make all the numbers line up and sort correctly, unless you also use a custom comparison function, of course). You could also add the comment count to one of the displayed fields (say, at the beginning of the head field) and end up with a cool index of all your posts in order of popularity!
There is much more information how to create and use an item filter on the Item Filter Reference Page.
Custom Comparison Function
A custom comparision function is called during the sort itself, as many times as is necessary to get the index sorted into the correct order. For very large indexes, this can be many, many times. If you add your own comparison function, you are in full control over how the index will be sorted. These are the steps to follow:
- On the index settings page, select the following advanced option:
- Use a customized comparison function for sorting the index
- A new text box titled Custom comparison function will appear at the bottom of the settings page. Type in the name of your comparison function (e.g. my_compare) into the text box and save the settings.
- Now all you need to do is create your comparison function. Find a place to add the function—creating another plugin for it would be great, or you could put it in the functions.php file in your current theme directory. It doesn’t matter as long as it is in a place where WordPress can find it.
The comparison function needs to have the following signature:
function my_compare($item1, $item2) {
/* My comparison code goes here */
}
$item1 and $item2 are the objects to be compared with each other. They are associative arrays (arrays with key/value pairs) containing data about two of the items in the index. They have the following keys:
| id | Post id – the id of the post linked to by this item. | |||
| initial | The initial character in the heading of the item. Useful when the index is divided up into alphabetical sections. | |||
| head | The item’s heading string, as it will be displayed in the index | |||
| subhead | The item’s subheading string, as it will be displayed in the index | |||
| desc | The item’s description string, as it will be displayed in the index | |||
| sort-head | The item’s sorted heading string – used only when sorting the index | |||
| sort-subhead | The item’s sorted subheading string – used only when sorting the index | |||
| sort-desc | The item’s sorted description string – used only when sorting the index | |||
| key | Category/tag id of the item – only if category/tag is selected as the heading for the index. | |||
AZIndex normally uses sort-head, sort-subhead, and sort-desc, for sorting, in that order. The sort values in the item may be different from the display values, depending on the settings used for the index, so it is usually advisable to use the sort values in you comparison function too, but the choice is yours.
The value you return from the function determines the order of the two items. The plugin uses the PHP function usort (sort an array by values using a user-defined comparison function) and defines the return value in this way:
The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
In other words, if $item1 should appear above $item2 in the index, return an integer less than zero. Otherwise the return value should be greater than zero. If you return zero the result is undefined, so your function should only return zero if you really do not care which item appears before the other.
Here is a simple example of a custom comparison function. If the headings in the index are all numbers, then you can sort the index in ascending numerical order with this one-line function:
function my_integer_compare($item1, $item2) {
return ($item1['sort-head'] - $item2['sort-head']);
}
Notes About Custom Sorts
- For most types of custom sort, it is probably quicker and more convenient to use an item filter to modify your items so that the default AZIndex sort will give you the result you need. That way, you only modify each item once before each sort rather than, perhaps, many times during each sort. Sometimes, however, a custom compare function may be the easier solution, or you might even need to use both to get the desired result. The choice is yours, depending on the circumstances.
- Be careful about querying information about each post in a custom comparison function. If you have a very large index, the query could be executed thousands of times and may hammer your database. I am not sure how good WordPress’s internal caching is, so you could be okay, but it is always advisable not to do too many complex and time consuming things during a custom compare function. Keep it quick!
- PHP support for collation (the sorting of words according to local language rules) does not work with UTF-8 on Windows. Therefore, before the sort begins (and after the item filter is called) the strings in sort-head, sort-subhead, and sort-dec, are all converted into the local windows codepage running on the server. This means that if you access these values in your custom comparison function, they will not be multibyte UTF-8 strings if your blog is running on Windows. These values will always be valid UTF-8 strings when your server is running on Linux.
- You can call the default AZIndex comparison function from your function. The name of the function is az_compare and takes the same two parameters as the your custom comparison function. For example, to sort the index in reverse alphabetical order, you can do this:
function my_reverse_compare($item1, $item2) { return az_compare($item2['sort-head'], $item1['sort-head']); } - The index option “Display alphabetical headings” may not work well with your custom sort. There isn’t much you can do at the moment to solve that problem except to turn headings off.
renderers said:
I was suggested this blog through my cousin. I am not positive whether this submit is written by means of him as nobody else recognize such special about my problem. You’re amazing! Thank you!
Marriage Certificates said:
I was just searching for this information for a while. After six hours of continuous Googleing, at last I got it in your web site. I wonder what’s the lack of Google strategy that don’t rank this kind of informative websites in top of the list. Generally the top websites are full of garbage.
Alec Nicolet said:
Haha, I’m only buying it because it won’t get boring super-fast.
Dan Rollins said:
I have been using the AZIndex for a while to do an alphabetical post listing and it has been great! Now I want to do a chronological index listing with the same look. Is there a way to do a sort by Published date so that it looks the same way?
Here is my current alpha page index: http://strongdisciple.com/alphabetical-listing
Thanks again for this great plugin!
Dan
Filters Toronto said:
Youre so cool! I dont suppose Ive read anything like this before. So good to seek out any person with some unique thoughts on this subject. realy thank you for beginning this up. this website is something that is needed on the internet, someone with a bit originality. helpful job for bringing something new to the web!
trane filters said:
I’ve learn several just right stuff here. Definitely value bookmarking for revisiting. I wonder how a lot effort you place to create this sort of great informative website.
Five seasons filters said:
naturally like your web site but you have to test the spelling on quite a few of your posts. Several of them are rife with spelling issues and I to find it very bothersome to tell the truth on the other hand I’ll definitely come back again.
ecu repair said:
excellent points altogether, you just received a emblem new reader. What could you recommend in regards to your post that you simply made some days in the past? Any certain?
color said:
Youre so cool! I dont suppose Ive read anything like this before. So nice to seek out somebody with some authentic ideas on this subject. realy thanks for beginning this up. this website is one thing that is needed on the web, someone with slightly originality. helpful job for bringing something new to the web!
Jeff said:
Hi Mike…
Big fan of the plugin. We use it everywhere.
Not sure where to make suggestions so I thought I would try here.
We have a directory and it would be really useful for us to be able to use the category as a sub head.
This way we could have a page that show all categories grouped by a custom field.
Would love to know if this will make the list.
Jeff
Auto Injury Clinic Atlanta said:
There is clearly a bunch to realize about this. I think you made some good points in features also.
Atlanta IME Disability DOT said:
This website online is mostly a walk-via for all of the information you wished about this and didn’t know who to ask. Glimpse here, and also you’ll positively discover it.
Stone Mountain Chiropractor said:
Wonderful paintings! This is the type of info that are supposed to be shared around the web. Disgrace on the seek engines for no longer positioning this post higher! Come on over and seek advice from my site . Thank you =)
Electric Visual Goggles said:
I found your weblog site on google and verify a couple of of your early posts. Continue to keep up the superb operate. I just additional up your RSS feed to my MSN Information Reader. Seeking forward to reading extra from you afterward!…
Hipolito Mccurren said:
Well I definitely liked reading it. This subject provided by you is very helpful for accurate planning.
peter said:
using AZIndex 0.8.1 on wordpress 2.7 that was installed a few years ago by original site developer. The website is for non-profit organization, run by volunteers.
I have no knowledge/experience with this plugin and has been working up till today, when noticed site had issue.
AZIndex Plug Error 101 – required database table wp_bfafaz_indexes – donot exist
deactivate then reactivate AZIndex to correct this problem
I deactivated then reactivated plugin- got same Error
Suggestions on how this issue can be resolved would be much appreciated.
Electronic kits said:
I think other web site proprietors should take this web site as an model, very clean and magnificent user friendly style and design, as well as the content. You’re an expert in this topic!
Michael Grant said:
This plugin does in fact seem to work on wordpress 3.x.
It would be fantastic if this plugin could be updated to be able to use custom types and taxonomies. I can see by playing with the code that it wouldn’t be too difficult.
Is there any active development being done on this? Can I make some code contributions?
wellington boot racks said:
I precisely needed to thank you very much yet again. I do not know the things I would have made to happen without those solutions contributed by you directly on that concern. It became an absolute challenging circumstance in my position, nevertheless being able to view the specialized way you treated the issue made me to leap over happiness. Extremely happy for the assistance and even expect you are aware of an amazing job you are getting into training other individuals with the aid of your web page. Probably you’ve never encountered all of us.
vityas said:
I appreciate, result in I discovered just what I used to be having a look for. You have ended my 4 day lengthy hunt! God Bless you man. Have a great day. Bye