[WARNING: The HTML generated by AZIndex will be changed considerably in an upcoming release. Any page links filters written before then may have to be rewritten to work with the new HTML.]
The page links filter is called just before any index page that has page links in it is displayed, and contains the final HTML for formatted page 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_page_links', 'my_page_links_filter');
Then add the display index filter function with the name you specified:
function my_page_links_filter($output) { /* My HTML modifying code here */ return $output; }
The $output parameter contains the HTML for the page links to be displayed.
Page 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 6:
add_filter('azindex_page_links', 'my_page_links_filter', 10, 6);
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, $pagelink, $currentpage, $pagecount, $anchor) { /* 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. |
$pagelink | The URL of the index page (without the page number). Needed for links to the other pages in the index. |
$currentpage | The current page of the index to be displayed. |
$pagecount | The number of pages in the index. |
$anchor | This is the anchor for the index page. Add this to the links if you want the top of the index to appear at the top of the browser window when a link is clicked. |
Formatting the Links
If you are completely rebuilding page links HTML, you will need to create href attributes with the correct format. The each link contains URL of the index ($pagelink) and a page number in the format “?pgno=”.$pageno. Optionally, you can add $anchor to the end of the link. For example, the href for a link to the first page of an index appearing on this webpage would have the following format:
href="http://azindex.englishmike.net/page-links-filter/?pgno=1#azindex-11"
Note: the first page of an index is always pgno=1.
Other Notes about the Page Links Filter
There are some other things to be aware of when you are using the page links filter:
- If you just want to tweak the default appearance of the page 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 placed at the beginning and/or at the end of the index page (depending on the settings for the index). If you need them to be put somewhere else, then use a display index filter to move the HTML for for page links.
- The filter will not be called if the index is empty or if the page links option is not selected in the settings.