Alpha Links Filter

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

The alpha links filter is called just before any index page that has alphabetical links at the top is displayed, and contains the final HTML for formatted alphabetical links 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 links are displayed.

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

add_filter('azindex_alpha_links', 'my_alpha_links_filter');

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

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

The $output parameter contains the HTML for the alphabetical links to be displayed.

Alpha Links Filter Parameters

If you want to do more than tweak the links HTML, perhaps even build your own set of links from scratch, then you can opt to have  your filter receive all the available parameters, which is 5:

add_filter('azindex_alpha_links', 'my_alpha_links_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 receive the other parameters:

function my_item_filter($output, $idindex, $links, $pagelink, $currentpage) {
    /* My HTML modifying code here */
    return $output;
}

The parameters are as follows:

$output The generated HTML for the alphabetical links.
$idindex The id of the index being display (may be a string or numeric). Use this if you want your filter to do different things for different indexes.
$links Links is an array containing information about all the alphabetical links being displayed.  For more information on the contents of this array, see below.Note: the exact contents of this array depends on the settings used for the index.  For example, if the settings specify that unused characters are included in the links, then they will be in the array passed to the filter.
$pagelink The URL of the index page (without the page number). Needed for links to other pages in multipage indexes.
$currentpage Number of the current index page.  Needed for links to other pages in multipage indexes.

The $links parameter is an associative array with each key being one of the characters in the alpha links.  For example, if the links contain the letters A, G, and H, the array will contain the following keys:

$links['A']
$links['G']
$links['H']

So, although they are sorted into the order in which they should be displayed, you can’t iterate through the array with a regular for ($i = 0; $i < count($links); $i++) loop.  Use a foreach loop instead (see next section for an example).

The value of each item will either be false if the letter has no link, or an array containing the following keys:

char The link character (same as the key in the array)
page The page in the index the link is pointing to (only needed for multipage indexes)

Formatting the Links

If you are rebuilding alphabetical links that link to the existing index page HTML, you will need to create links with the correct format.  The each link contains the hexadecimal equivalent of the letter/character with a prefix of “#char_” .  For example, the link to the letter A will be #char_41.

Note: there may be multibyte characters in the links array, so you must use the bin2hex() function to ensure you convert all the bytes of the characters.

In multipage indexes, you will need to test $currentpage against each page number in the links to see if you need to add the $pagelink parameter and a page number to the link.  If the target is on another page, the format should be $pagelink.”?pgno=”.$pageno.”#char_”.bin2hex($char).

So, an example  loop to process all the links would be as follows:

foreach ($links as $char => $link) {
    if ($link !== false) {
        $hex = bin2hex($char);
        $href = ($link['page'] == $currentpage) ? "#char_$hex" :
                                  "$pagelink?pgno={$link['page']}#char_$hex";
        /* Build the HTML for the link */
    } else {
        /* Add non-link character to HTML */
    }
}

Other Notes about the Alpha Links Filter

There are some other things to be aware of when you are using the alpha links filter:

  • If you just want to tweak the default appearance of the alpha links, then you might find it easier use the custom CSS options in the index settings page to modify the style of the links.
  • The HTML you pass back to the plugin will always be place between the page links and the main body of the index page.  If you need them to be put somewhere else, then use a display index filter to move the links HTML.
  • The filter will not be called if the index is empty or if the alphabetical links option is not selected in the settings.
Continue to the next page »