Item Filter
The item filter is called every time an item is loaded from the blog’s database and before the index is either sorted or displayed. Using this filter allows you to affect the content of each item in the index and the order in which they are sorted.
To add a filter for all indexes in your blog use the following code:
add_filter('azindex_item', 'my_item_filter');
Then add the item filter function with the name you specified:
function my_item_filter($item) {
/* My item modifying code here */
return $item;
}
The $item parameter is an associative array containing all the information about the item being loaded into the index. It has the following keys names:
| Key Name | Description | |||
|---|---|---|---|---|
| id | Post id - the id of the post linked to by this item (cannot be modified) | |||
| 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 (cannot be modified) | |||
There are two copies of the heading, subheading, and description strings in the item array because you may not always want to use the same strings when sorting the index that you want displayed in the index. One common example is where you have some items with headings in quotes (e.g. “Red Dwarf”). This may be what you want to see in the index, but you also want it to appear in the R section of the index (e.g. between Really Fine Wines and Referees—the Most Thankless of Jobs?) and the quotation mark at the beginning of the heading would cause it to be sorted into completely the wrong place.
By turning on the “Ignore specified characters…” option in the index settings, you would see one of the heading strings has the leading quote removed, allowing the item to be sorted in the corrected order in the index.
So, if you just want to affect where an item will appear in the index, use the sort-head, sort-subhead, and sort-desc values, but if you want to modify the content of the item as it appears on the index page then use the head, subhead, and desc values.
The id value is the post id, and is provided so you can access other information about the item. For example, if you want to display the tags or categories the post has, you can use the post id to access this information and put it in the description field. (Note: you will have to know something about the WordPress PHP functions to do something like this.) Changing the value of id in the filter has no effect.
Finally, the key value is only used by indexes that have either tags or categories as the headings. When that is the case, there may be more than one item in the index for a single post (i.e. one for every tag/category the post has), and the key value is used to distinguish which tag/category the item is for. For indexes with tag headings, it is the tag id, and for indexes with category headings it is the category id. Changing the value of key in the filter has no effect.
More Item Filter Parameters
If you only want to use the item filter with one specific index, you need to know the id of the index your filter function is being called for. You can do this by specifying that you want your filter to receive all the available parameters, which is 2:
add_filter('azindex_item', 'my_item_filter', 10, 2);
Note: the third parameter in the add_filter() call, 10, is the default filter priority, and must be present so you can specify the number of parameters you want to be passed to your filter.
Now you can modify the filter function to receive the index id, so you can add a test in your code to see if you need to filter this item.
function my_item_filter($item, $idindex) {
/* My item modifying code here */
return $item;
}
Note: in future versions for AZIndex, $idindex may be a string, as well as a number.
Other Notes about the Item Filter
There are some other things to be aware of when you are using an item filter:
- The item filter is called after AZIndex has modified the item strings according to the options selected in the settings page. So, for example, if the “Ignore specified characters…” option is set, the sort- fields will already have those ignored characters removed from the front of the string.
- If you are changing the sort- values, make sure you remove all white-space from the beginning of the strings, otherwise your items will appear in the wrong place in the index.
- All strings passed into the filter use the UTF-8 encoding, where some characters (like those unique to certain languages) are more than one byte long. If you are going to manipulate text that contains these multi-byte characters, you should use the PHP multi-byte stringlibrary functions to do so.
- Before the index is sorted, all item filters will be called for every item in the index. So, if you are using an item filter with large indexes, make sure it doesn’t take a very long time to execute (e.g. don’t make an http request to another website!) or you may find the index sort timing out.
- Whenever you add an item filter, or change your item filter code, you may have to clear the index cache (from the index management admin page) before you see the changes in the index. It’s usually a good idea to turn off caching for the index (in the advanced options) while you are developing an item filter.
- You may find your item filter function being called at times when you least expect it. This is because when a post in your blog is changed in some way, AZIndex checks to see if the change affected its position in the index. For example, if you edit the title of a post then, when you save it, the plugin loads the item(s) for that post and the items before and after it in the index, and performs a mini-sort on them. If the sorted order has been changed by your edit, then AZIndex knows that next time the index is loaded, it will have to re-sort the index. In fact, your item filter will be called whenever you save a post, as well as when you add a custom field, a tag or a category to a post, and possibly at other times too.
- Other keys may be added to the $items array in future releases, so the number of keys and their order may change over time.
- This filter replaces the old azindex_heading filter. You can access the same data provided with that filter by using the $item['head'] or $item['sub-head'] value.
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