=== Plugin Name ===
Contributors: stringfold 
Tags: index, indexing, alphabet, alphabetical, organize, atoz, posts
Requires at least: 2.5
Tested up to: 2.5.1
Stable tag: 0.5

Create alphabetical indexes of your posts, with headings, subheadings, and descriptions, based on post title, extract, author name or custom fields.

== Description ==

Enhance your blog by creating multiple, three-level alphabetical indexes of your posts based on any combination of post title, author, extract, or custom fields of your choice. Select which posts are included in your indexes using a combination of categories and tags, display them in up to four columns on a single page or over multiple pages.

For example, the AZIndex plugin can be used to:

* create an alphabetical index of all your blog posts, based on their titles, using extracts as short descriptions.
* create a music review index, sorted by the name of the artist and the name of their albums.
* on blogs with multiple authors, create an index of posts by each author's name.
* create a full alphabetical index of all your blog's published pages in seconds with no PHP, HTML, or CSS required.

Full list of features:

* Index blog posts by title, extract, author, or any custom field.
* Create indexes for your blog pages. Now you can create a full alphabetical index of every page and post on your site. 
* Select index contents using a combination of categories and tags.
* One, two or three-level entries - heading, subheading, and description, all customizable.
* Up to four columns on a page.
* Multiple indexes can be created, each customized with its own settings.
* Indexes may be embedded in posts as well as pages.
* Fully customizable from the WordPress admin console. No need to know HTML or PHP.
* Single or multi-page indexes with page links.
* Optional alphabetical links.
* **NEW!** Display alphabetical headings in your index with links back to the top of the page.
* Group items with the same heading under one entry (e.g. all the novels of the same author).
* Add your own text to the index page.
* Control over the number of index items per page.
* **NEW!** Indexes are cached to ensure speedy operation when dealing with large indexes.
* Customize the stylesheets for the index contents directly from the index administration page.
* Use CSS style striping to decorate your index entries (e.g. add a gray background to alternate entries). 
* Use your own customized sort to sort an index.
* Customize which alphabetical links appear with your index. 
* Index entries that do not begin with a character or number can be placed at the beginning or the end of the index.
* Punctuation like quotes or double-quotes can be ignored while sorting the index.  

**IMPORTANT NOTE:** This is a **BETA** release, meaning that while the plugin is stable and has undergone considerable testing, there may be a bug or two. I have not been able to test all the plugin's features on all combinations of WordPress versions and browsers.

Please read the Other Notes section before installing.

If you try this plugin and like what you see, email to mike@englishmike.net or visit [AZIndex Plugin Home Page](http://englishmike.net/azindex-plugin/) to provide your feedback. 

If you're reporting a bug, requesting a new feature, or just wanting to make a comment, I will be happy to hear from you.

== Installation ==

Installation Instructions:

1. Download the plugin zip file. 
1. Upload the plugin contents into your WordPress installation's plugin directory.
1. The plugin's .php files and readme.txt should be installed in the 'wp-content/plugins/azindex/' directory. 
1. From the Plugin Management page, activate the AZIndex plugin.
   
Getting Started:   
   
1. To create a new index, go to Manage >> AZIndexes and click on the 'Add New' link.
1. Enter a title for your index and select the options you want. 
1. Click the 'Add Index' button and a new index, along with a new unpublished blog page, will be created.
1. To view the contents of your new index page, go to Manage >> Pages and preview the page from there.
1. Make sure you try out all the options. They can be used to tailor the look and feel of the index to your satisfaction.
1. Once you are happy with the results, publish the index page (from Manage >> Pages) so your users can access it.
1. Hint: Consider using custom fields in your posts to set the headings and sub-headings of your index. For example, if you are indexing book reviews you have posted, you can create an index that uses custom fields to access the authors' names as headings, and the book titles as sub-headings. That way you can have a well organized index without having to mess with the titles of your reviews.

== Frequently Asked Questions ==

= How can I include all my posts in the index? =

Easy, just leave the 'Included tags' and 'Included categories' fields empty.

= How do I add my index to another page or post? =

1. Make a note of the ID of the index from the table on the Manage >> AZIndexes administration page.
1. Edit the page/post in which you want to display the index.
1. Insert the following "short-code" into your page/post:   [az-index id="x"]   (where x is the ID of the index).  

= Can I index pages as well as posts? =

Yes!  Just check the appropriate option in the settings for your index.  If you only want to index pages, remember to check the option to exclude posts from the index.

= But I only want to add some of my pages to the index.  How do I do that? =

With posts it's easy, you can tag or categorize the ones you want to put in an index and you're done.  

Unfortunately, there is no easy way to categorize or tag pages, but don't worry, there is a nice little plugin called [tags4page](http://wordpress.org/extend/plugins/tags4page/) which allows you to tag pages when you edit them. Once you have tagged the pages you want in the index simply specify that tag in the index settings. 

= When I have more than one column on a page, why are the columns sometimes different lengths? =

That is because the index items are split evenly between the columns, but some items can take up more column space than others.  If there are several large items in one of the columns, it may end up being much longer than the others.

= Help! The headings in my index have no links.  What gives? =

You probably have the 'Group items..." option selected for your index.  If you don't have any subheadings, then make sure you deselect this option.

= Why does the layout of my index look strange with some WordPress themes? =

Well, just like anything else appearing in a page or post on your blog, your blog's current theme will affect the appearance of the index.

Most of the time that's a good thing, because you don't want your indexes to look out of place in your blog.  But occasionally a WordPress theme's stylesheet just may not work well with your index.  

If that happens there are two ways to resolve the problem:

1. Modify the theme's stylesheet so that it doesn't interfere with the appearance of the index.
1. Turn on the "Use customized stylesheets" option for your index then modify the index's stylesheet to fix any unsightly styling.

Note: One common problem with some themes is that you'll see bullets appearing next to items in the index.  This happens when there is a CSS style in the theme's stylesheet that defines the style tag 'list-style-type' or 'list-style'.  The easiest way to fix this is to comment out or delete this line from your theme's stylesheet, but you should check to see if this causes other formatting issues in your blog.  If you feel you can't remove that line, the next easiest way to solve the problem is to make a copy of that style (it will begin something like "#content .page ul ol {"), turn on custom CSS styling for the index and paste the style into the stylesheet for the index.  Then all you have to do is modify the "list-style" (or "list-style-type") element and replace "disc" (or whatever the type is) with "none".

Once I have some time, I will write a longer article about modifying stylesheets since this is an important topic in getting your index to look just the way you want it.    

= You say that this is a BETA release, what exact does that mean? =

It means that this is an early release of the plugin.  While I have tested many of the features as thoroughly as possible, I am not able to test all the features of the plugin with all the browsers on all versions of WordPress, PHP and MySQL.  So it is possible you will come across a combination where there is still a one or two bugs.

It also means that there are one or two features left to be finished, like internationalization.

Finally, you may have to delete and recreate your indexes when you decide to move up to a new version.  Please read the release notes before upgrading.

However, the vast majority of users should be able to use this version of the plugin without any trouble.  Just make sure to test it out before you publish your index page.

Any feedback you can provide me is most welcome.  

= I still have more questions/problems/requests, where do I go for answers? =

Simple, either leave a comment at the [AZIndex Plugin Home Page](http://englishmike.net/azindex-plugin/), or email me at mike@englishmike.net if you want to keep your comments private. 

== Screenshots ==

Please visit the [AZIndex Demo Page](http://englishmike.net/azindex-test-page/) for two examples of indexes generated by the AZIndex plugin.

Here is another cool example of the style of index you can create with this plugin: [AZIndex Demo: Book Review Index with Ratings](http://englishmike.net/azindex-test-page/azindex-demo-book-reviews-with-ratings/) 

== Release Notes version 0.5 ==

**Minimum versions tested**

* WordPress 2.5 is the minimum required (will not work with older versions of WordPress)
* PHP4 (4.4.8) & PHP5 (5.2.6)
* MYSQL 4.1.22 & MYSQL 5.0.5

**Known issues**
 
* This plugin is English-only and does not use the internationalization APIs as yet.
* The plugin still contains some debug code. It will not affect the behavior or performance of the plugin.  It will be removed in later versions.
* The wp_nonce functions have yet to be implemented.

**Known bugs**

* In the Safari browser, the text input fields do not appear when you select "Custom field" when adding or editing an index's settings. The workaround is to select "Custom field" then save the settings. When you edit the index's settings again, the text input field will be visible.

**Changes in version 0.5**

* Caching has arrived!  Large indexes are now many times faster to load (if you use multiple pages) than before.
* The cache can be cleared manually if necessary, or even disabled completely (though I would recommend against it!)
* Added option to add alphabetical headings to your index. Each new letter of the alphabet now has its own heading.
* Added further options to put an alphabetical heading at the beginning of each page or at the top of each column.
* Improved the pagelinks so that they will never overflow the bounds of the page if you have many pages in your index.
* Added "(continued)" and "(more...)" when a grouped heading crosses between columns or pages. 
* Fixed bug that was resulting in the wrong number of items going into a column.

**Upgrading to version 0.4**

* No incompatible changes from 0.4.x.  Indexes created with versions 0.3.x and 0.4.x will continue to work on 0.5.
* New CSS styles for the indexes will be added if you have defined custom CSS for your index.  Your own modifications will not be affected.  

== Release Notes version 0.4 ==

**Changes in version 0.4**

* Added option for including blog pages in an index.
* Added option for striping index entries (e.g. giving alternate entries a different backgound color).
* Added option for custom sorting of an index.  Simply create your own comparison function and add its name to the index's settings page.
* Added option for filtering out punctuation when sorting the index, so entries don't get out of order if they begin with a quote or double-quote, for example.
* Added option for placing entries that begin with non-alphanumeric characters at the end of the index.
* Fixed bug causing the URL to grow when clicking on the index page links.
* Fixed bug where entries with no heading were appearing in the index. 
* You can now upgrade to the latest version of the plugin without losing your existing index settings (from v0.3 and above). 

**Upgrading to version 0.4**

* No incompatible changes from 0.3.x.  Indexes created with version 0.3.x will continue to work on 0.4.

**Changes in version 0.3.1**

* Fixed bug preventing plugin working with PHP4.
* Added better error checking and error messages to help users during problem determination.

**Upgrading to version 0.3.1**

* No incompatible changes from 0.3.  Indexes created with version 0.3 will continue to work on 0.3.1.

**Changes in version 0.3**

* Fixed bug that prevented the plugin working with MySQL 4.1 and some early versions of MySQL 5.0

**Upgrading to version 0.3**

* **VERY IMPORTANT** You *must* uninstall any earlier versions of the AZIndex plugin by clicking the **Uninstall AZIndex Plugin** link in the Manage >> AZIndexes admin page before you install the latest version.  

**Changes in version 0.2.1**

* Fixed bug where duplicate entries appear in the index when specifying more than one tag or category for the index.
* Fixed bug where the Author (the author of the post) was not displayed correctly when specified.

**Upgrading to version 0.2.1**

* Indexes created on v0.2 should continue to work on v0.2.1

**Changes in version 0.2**

* Indexes are no longer tied to a specific blog page.  For you convenience, a new page containing the '[az-index id="x"]' short-code will be created when you add an index, but you can copy that shortcode to any post or page you like.
* Posts can now have indexes embedded within them.  Just insert the short-code '[az-index id="x"]' where x is the id of the index. e.g. [az-index id="1"]. 
* You can embed the same short-code in more than one post/page.

**Upgrading to version 0.2**

* Delete all the indexes created with version 0.1.  They will no longer work correctly.  The quickest way to do this is to click 'Uninstall' and uninstall the plugin before you upgrade.
* You can no longer preview the index page from the 'Manage Indexes' table.  Go to Manage >> Pages instead.
* The plugin's administration page has been renamed from 'Index Pages' to 'AZIndexes'