Templates and Theming

Display and layout

AlphaListing automatically adapts the directory layout to improve readability on wide screens.  

Multiple column output

On larger viewports, AlphaListing switches to multiple columns when a letter group contains at least 15 items. A second column appears at 11 items (6 items in the first column and 5 in the second), and a third column is added at 21 items if the layout allows it. The plugin continues balancing items across columns up to a practical limit of 15 columns, ensuring listings remain visually balanced.

Templates and theming

Customize AlphaListing by overriding its templates inside your theme.

Creating a custom template

1. Copy templates/a-z-listing.php from the plugin into your theme's root directory.
2. Rename the file to a-z-listing.php for the main listing or a-z-listing-section.php when targeting a specific section.

Starting with the example template is recommended because it demonstrates the available helper methods.

Working with the loop

AlphaListing's templating API mirrors the standard WordPress loop with a separate loop for letters and items.

Key methods include:

• $a_z_query->the_letters() — prints the alphabet and links letters that have items.
• $a_z_query->have_letters() — returns whether additional letters remain in the letter loop.
• $a_z_query->the_letter() — advances to the next letter; wrap the item loop inside this loop.
• $a_z_query->have_items() — mirrors have_posts() for iterating the items within the current letter.
• $a_z_query->the_item() — prepares the current item, similar to the_post().

Within the item loop you can call familiar WordPress template tags such as the_content(). When displaying taxonomy terms, use AlphaListing's helper methods to ensure titles and permalinks resolve correctly.

Helper functions

• $a_z_query->the_title() — prints the current item's title.
• $a_z_query->get_the_title() — returns the title without printing it.
• $a_z_query->the_permalink() — prints the current item's permalink.
• $a_z_query->get_the_permalink() — returns the permalink without printing it.
• $a_z_query->the_item_id() — prints the current item's ID.
• $a_z_query->get_the_item_id() — returns the ID without printing it.

These helpers normalize output whether the listing is built from posts (WP_Post) or taxonomy terms (WP_Term).