Display Index Filter

[WARNING: The HTML generated by AZIndex will be changed considerably in an upcoming release.  Any display index filters written before then will almost certainly have to be rewritten to work with the new HTML.]

The display index filter is called just before any page of an index is displayed, and contains the final HTML for formatted index page to be set to the browser.  Using this filter allows you to modify the content of the HTML so that you can effect changes in the way the index page is displayed.

To add a filter for all indexes in your blog use the following code:

add_filter('azindex_display_index', 'my_display_index_filter');

Then add the display index filter function with the name you specified:

function my_display_index_filter($output) {
    /* My HTML modifying code here */
    return $output;
}

The $output parameter contains all the HTML for the index page being displayed.  This includes the HTML for the alphabetical links and the page links, if they are present, even though there are separate filters for modifying those parts of the index page.  This ensures that all of the index page, including the enclosing <div></div> tags are passed to the filter.

More Display Index Filter Parameters

If you want to know which index is being displayed, or if you need to do more than just tweak the index page’s HTML, your filter function can be configured to receive all the available information about the contents of the index page.  This is useful if you want to build your own HTML for the page, or if you want to search for specific items to change.

To obtain this extra data, you need specify that you want your filter to receive all the available parameters, which is 5:

add_filter('azindex_display_index', 'my_display_index_filter', 10, 5);

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 handle the additional parameters:

function my_item_filter($output, $idindex, $items, $start, $count) {
    /* My HTML modifying code here */
    return $output;
}

The parameters are as follows:

$output The complete HTML for the whole page (including the enclosing div, links, and stylesheet, if present
$idindex The id of the index being display (may be a string or numeric)
$items An array of items containing the details of every item displayed on the current page. Each item is an associative array.  The keys for the item array are listed in the table below.

Modifying these values will not change the output of the plugin, but you can use the information in the array to build you own version of the index page.

Note: the first item and last items in this array may not actually be displayed on the page.  If the index has multiple pages, they are included to allow text like (continued) and (more) to be added where a section spills over more than one page.  Use the following two parameters to determine which items in the array belong on the page.

$start The index in the $items array of the first item displayed on the current index page.
$count The number of items displayed on the current index page.

Here is a list of the keys for each of the items in the $items array:

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.

Other Notes about the Display Index Filter

There are some other things to be aware of when you are using the display index filter:

  • The content of the HTML passed to this filter will vary depending on the options and settings selected for the index.  So, if you write your filtering code to handle just one specific set of options, make sure you always use the settings values your filter can handle.
  • If you are also modifying the alphabetical links and/or page links with the other filters, you will have to find a way to identify and extract that HTML from the full index page passed into this filter if you want to rebuild the page output from scratch.  You can use the PHP DOM function library to help you do that.
  • The index’s CSS stylesheet may or may not be present in the HTML, depending on the settings for the index.
  • The filter will not be called if the index is empty.