Ethan Lin

<p>Display posts, pages, and terms alphabetically in a Rolodex-, catalog-, or directory-style list with the AlphaListing plugin!</p>
<p>This plugin includes a block and shortcode for the list, along with a widget for linking to the list from any location on a site. If a letter has no associated pages, the widget will display the letter unlinked, while the list page will omit the letter entirely.</p>
<p>Show posts from any single or multiple post types, including built-in posts and pages. Post types from plugins like WooCommerce products are also supported. Alternatively, display terms such as categories or tags.</p>
<p><em>This plugin is based on the original <strong>A-Z Listing</strong> by Lucy (formerly Dani) Llewellyn, which is no longer maintained. Custom templates built for the original plugin may not work reliably with this version. For the most up-to-date example template, see the <a href="https://raw.githubusercontent.com/Lin87/alphalisting/refs/heads/main/templates/a-z-listing.example.php" rel="nofollow ugc">example template</a>.</em></p>
<h3>Gutenberg Block</h3>
<p>Use the AplhaListing block in most cases, as it provides guidance for configuring various options.</p>
<h3>Shortcode for compatibility and PHP use</h3>
<p>The plugin provides a shortcode for the full AlphaListing, enabling use without modifying theme templates.</p>
<p>Basic usage is as follows:</p>
<pre><code>[alphalisting]
</code></pre>
<p>To specify a post-type to display instead of <code>page</code> then use, e.g. <code>post</code>:</p>
<pre><code>[alphalisting display="posts" post-type="post"]
</code></pre>
<p>To filter the posts by a term from a taxonomy:</p>
<pre><code>[alphalisting display="posts" post-type="post" taxonomy="category" terms="my-term-slug"]
</code></pre>
<p>To display pages that are direct children of the page with ID <code>24</code>:</p>
<pre><code>[alphalisting display="posts" post-type="page" parent-post="24"]
</code></pre>
<p>To display pages that are children of any depth below the page with ID <code>24</code>:</p>
<pre><code>[alphalisting display="posts" post-type="page" parent-post="24" get-all-children="yes"]
</code></pre>
<p>To show terms from a taxonomy instead of posts and pages, e.g. Terms from the <code>Categories</code> taxonomy:</p>
<pre><code>[alphalisting display="terms" taxonomy="category"]
</code></pre>
<p>To show terms from the <code>Categories</code> taxonomy that are direct children of the term with ID of <code>42</code>:</p>
<pre><code>[alphalisting display="terms" taxonomy="category" parent-term="42"]
</code></pre>
<p>To show terms from the <code>Categories</code> taxonomy that are children of any depth in the tree below the term with ID of <code>42</code>:</p>
<pre><code>[alphalisting display="terms" taxonomy="category" parent-term="42" get-all-children="yes"]
</code></pre>
<p>To override the alphabet used by the plugin:</p>
<pre><code>[alphalisting display="posts" alphabet="Aa,Bb,Cc,Dd,Ee,Ff,Gg,Hh,Ii,Jj,Kk,Ll,Mm,Nn,Oo,Pp,Qq,Rr,Ss,Tt,Uu,Vv,Ww,Xx,Yy,Zz"]
</code></pre>
<p>To add numbers to the listing:</p>
<pre><code>[alphalisting display="posts" numbers="after"]
</code></pre>
<p>The numbers can also be shown before the alphabet:</p>
<pre><code>[alphalisting display="posts" numbers="before"]
</code></pre>
<p>Group the numbers into a single collection for all posts beginning with a numeral.:</p>
<pre><code>[alphalisting numbers="after" group-numbers="yes"]
</code></pre>
<p>To group the alphabet letters into a range:</p>
<pre><code>[alphalisting grouping="3"]
</code></pre>
<p>** The arguments are all optional **</p>
<h4>Common options</h4>
<ul>
<li><code>display</code>: specifies whether to display posts or terms from a taxonomy.
<ul>
<li>Default value: <code>posts</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to either <code>posts</code> or <code>terms</code>.</li>
<li>Any value other than <code>posts</code> or <code>terms</code> will default to displaying posts.</li>
</ul>
</li>
<li><code>numbers</code>: appends or prepends numerals to the alphabet.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to either <code>before</code> or <code>after</code>.</li>
<li>Any value other than <code>before</code> or <code>after</code> will default to <strong>appending</strong> numerals to the alphabet.</li>
</ul>
</li>
<li><code>grouping</code>: tells the plugin if and how to group the alphabet.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to any positive number greater than <code>1</code> or the value <code>numbers</code>.</li>
<li>Any value other than a positive number or the value <code>numbers</code> will default to disabling all grouping functionality.</li>
<li>When set to a number higher than <code>1</code> the listing will group letters together into ranges.</li>
<li>For example, choosing <code>3</code> groups the Latin alphabet so that <code>A</code>, <code>B</code>, and <code>C</code> become <code>A-C</code>, followed by <code>D-F</code>, <code>G-I</code>, and so on.</li>
<li>When using this setting, if numbers are also shown via the <code>numbers="before"</code> or <code>numbers="after"</code> attribute then they will be shown as a single separate group <code>0-9</code>.</li>
<li>When set to the value <code>numbers</code> it will group numerals into a single group <code>0-9</code>.</li>
<li>This requires the numbers to be displayed via the <code>numbers="before"</code> or <code>numbers="after"</code> attributes.</li>
</ul>
</li>
<li><code>group-numbers</code>: tells the plugin to group all items beginning with a numeral into a single collection.
<ul>
<li>Default value: <code>false</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to <code>true</code>, <code>yes</code>, <code>on</code>, or <code>1</code> to group items beginning with a numeral in a single collection. All other values will keep the default behaviour.</li>
</ul>
</li>
<li><code>symbols-first</code>: Tells the plugin to put the unknown alphabet letter (symbols) group before the main alphabet.
<ul>
<li>Default value: <code>false</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to <code>true</code>, <code>yes</code>, <code>on</code>, or <code>1</code> to put the symbols group before the alphabet. All other values will keep the default behaviour.</li>
</ul>
</li>
<li><code>alphabet</code>: overrides the alphabet used by the plugin..
<ul>
<li>Default value: <code>unset</code>.</li>
<li>If this attribute is not defined, the plugin uses either the untranslated default or a translation from <a href="https://translate.wordpress.org/projects/wp-plugins/alphalisting" rel="nofollow ugc">glotpress</a> if available for the site’s language, as set in <code>Admin -> Settings -> Site</code> Language.</li>
<li>The current untranslated default is: <code>AÁÀÄÂaáàäâ,Bb,Cc,Dd,EÉÈËÊeéèëê,Ff,Gg,Hh,IÍÌÏÎiíìïî,Jj,Kk,Ll,Mm,Nn,OÓÒÖÔoóòöô,Pp,Qq,Rr,Ssß,Tt,UÚÙÜÛuúùüû,Vv,Ww,Xx,Yy,Zz</code>.</li>
<li>Accepts a single line of letters/symbols, which need to be separated via the comma character <code>,</code>.</li>
<li>Including more than one letter/symbol in each group will display posts starting with any of those under the same section.</li>
<li>The first letter or symbol in each group serves as the group’s heading when displayed on the site.</li>
</ul>
</li>
</ul>
<h4>Posts options</h4>
<ul>
<li><code>post-type</code>: sets the listing to show a specific post-type.
<ul>
<li>Default value: <code>page</code>.</li>
<li>Multiple post-types may be specified by separating with commas (<code>,</code>) e.g. <code>post-type="page,post"</code>.</li>
<li>Must be the <code>slug</code> of the post-type(s).</li>
</ul>
</li>
<li><code>parent-post</code>: sets the parent post that all displayed posts must be descended from.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>May only contain one value.</li>
<li>Must be the <code>ID</code> of the parent post.</li>
<li>Add <code>get-all-children="yes"</code> to also include all descendants of any depth below the parent post.</li>
</ul>
</li>
<li><code>exclude-posts</code>: remove these posts from the list.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>Multiple posts may be specified by separating by commas: <code>,</code>.</li>
<li>Must be the <code>ID</code> of the post(s).</li>
</ul>
</li>
<li><code>taxonomy</code>: sets the taxonomy containing the terms specified in the <code>terms=""</code> option.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>May only contain one value.</li>
<li>Must be the <code>slug</code> of the taxonomy.</li>
</ul>
</li>
<li><code>terms</code>: sets the taxonomy terms for filtering posts.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>The taxonomy must also be specified in <code>taxonomy</code>.</li>
<li>Multiple terms may be specified by separating with commas: <code>,</code>.</li>
<li>Must be the <code>slug</code> of the term(s).</li>
</ul>
</li>
</ul>
<h4>Terms options</h4>
<ul>
<li><code>taxonomy</code>: sets the taxonomy to display terms from in the listing.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>Multiple taxonomies may be specified by separating with commas: <code>,</code>.</li>
<li>Must be the <code>slug</code> of the taxonomy.</li>
</ul>
</li>
<li><code>terms</code>: sets the taxonomy terms to include in the listing.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>The taxonomy must also be specified in <code>taxonomy</code>.</li>
<li>Multiple terms may be specified by separating with commas: <code>,</code>.</li>
<li>Must be the <code>ID</code> of the term(s).</li>
<li>Cannot be used with <code>exclude-terms=""</code>.</li>
</ul>
</li>
<li><code>exclude-terms</code>: sets the terms to exclude from display.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>The taxonomy must also be specified in <code>taxonomy</code>.</li>
<li>Multiple terms may be specified by separating with commas: <code>,</code>.</li>
<li>Must be the <code>ID</code> of the term(s).</li>
<li>Cannot be used with <code>terms=""</code>.</li>
</ul>
</li>
<li><code>parent-term</code>: set the parent that all displayed terms must be descended from.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>May only contain one value.</li>
<li>Must be the <code>slug</code> of the parent term.</li>
<li>Add <code>get-all-children="yes"</code> to also include all descendants of any depth below the parent term.</li>
</ul>
</li>
<li><code>get-all-children</code>: when a parent term is chosen this option is used to show all children of any depth or only direct children.
<ul>
<li>Default value: <code>false</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to <code>true</code>, <code>yes</code>, <code>on</code>, or <code>1</code> to include all children of any depth. Any value other will use the default behaviour of only showing direct children.</li>
</ul>
</li>
<li><code>hide-empty-terms</code>: hide terms that have no posts associated.
<ul>
<li>Default value: <code>false</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to <code>true</code>, <code>yes</code>, <code>on</code>, or <code>1</code> to hide the empty terms. Any other value will use the default behaviour of showing all terms.</li>
</ul>
</li>
</ul>
<h4>Internal-use options for completeness</h4>
<p>** These are intended for internal use by the plugin and should not require any modifications.**</p>
<ul>
<li><code>target</code>: the default target for a listing that doesn’t show any items.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to a URL which will be used as the target for the letters’ hyperlinks.</li>
</ul>
</li>
<li><code>return</code>: what type of listing to show, either <code>listing</code> or <code>letters</code>.
<ul>
<li>Default value: <code>listing</code>.</li>
<li>May only contain one value.</li>
<li>Must be set to either <code>listing</code> to display the default view, or <code>letters</code> to show only the letters without any items (posts or terms).</li>
</ul>
</li>
</ul>
<h3>PHP (expert)</h3>
<h4>Most compatible method</h4>
<p>The best way to use the plugin from PHP is to call <code>do_shortcode( '[alphalisting]' );</code> and save or <code>echo</code> the returned text. The parameter passed to <code>do_shortcode()</code> should be a complete AlphaListing shortcode with parameters as above.</p>
<h3>Multiple Column Output</h3>
<p>Multiple column layout is the default on wide screens. A letter’s group of items must contain at least 15 items to create two or more columns. This is to provide a more aesthetically pleasing view when a list is short with only a few items.</p>
<h3>Templates and Theming</h3>
<p>The plugin allows the site owner, developer, or themer to provide custom templates for the AlphaListing output.</p>
<p>To add a template to a theme, create a file similar to <code>templates/a-z-listing.php</code> from the plugin folder. Place the copy in the theme’s root directory and name it <code>a-z-listing.php</code> or <code>a-z-listing-section.php</code> (with <code>-section</code> as an optional top-level page slug for the section-targeting feature).</p>
<h4>The Loop</h4>
<p>The theme system this plugin implements is <em>very</em> similar to <a href="https://codex.wordpress.org/The_Loop" rel="nofollow ugc">the standard WordPress loop</a>, with a few added bits.</p>
<p>Important functions to include in the template are:</p>
<ul>
<li><code>$a_z_query->the_letters()</code> prints the full alphabet, and links the letters that have posts to their section within the index page.</li>
<li><code>$a_z_query->have_letters()</code> returns true or false depending on whether there are any letters left to loop-through. This is part of the Letter Loop.</li>
<li><code>$a_z_query->have_items()</code> behaves very similarly to Core’s <code>have_posts()</code> function. It is part of the Item Loop.</li>
<li><code>$a_z_query->the_letter()</code> similar to Core’s <code>the_post()</code>, this will set-up the next iteration of the AlphaListing’s Letter Loop. This needs to wrap-around the Item Loop.</li>
<li><code>$a_z_query->the_item()</code> similar to Core’s <code>the_post()</code>, this will set-up the next iteration of the AlphaListing’s Item Loop, the same way the normal WordPress Loop works. This needs to be <em>within</em> the Letter Loop.</li>
</ul>
<p>Within the Item Loop, all built-in WordPress Core post-related functions, such as <code>the_content()</code>, can be used. Titles and permalinks have helper functions to accommodate AlphaListing’s display of taxonomy terms (see the next section).</p>
<p>Starting with a copy of the <a href="https://raw.githubusercontent.com/Lin87/alphalisting/refs/heads/main/templates/a-z-listing.example.php" rel="nofollow ugc">default template</a> is recommended when creating a custom version. The provided template demonstrate the usage of most functions available in the plugin.</p>
<h4>Helper functions</h4>
<p>The plugin supports displaying taxonomy terms as though each term were a post. This means that the WordPress functions related to posts such as <code>the_title()</code> and <code>the_permalink()</code> are unreliable. We have therefore added helper functions which will return or print the correct output for the item.</p>
<p>These helper functions cope with the dual usage of the plugin supporting both <code>WP_Query</code>-based (returning <code>WP_Post</code> objects) and Taxonomy Terms (returning <code>WP_Term</code> objects) listings. These are:</p>
<ul>
<li><code>$a_z_query->the_title()</code> – prints the current item’s Title</li>
<li><code>$a_z_query->get_the_title()</code> returns the current item’s Title but does not print it directly</li>
<li><code>$a_z_query->the_permalink()</code> prints the current item’s Permalink</li>
<li><code>$a_z_query->get_the_permalink()</code> returns the current item’s Permalink but does not print it directly</li>
<li><code>$a_z_query->the_item_id()</code> prints the current item’s ID</li>
<li><code>$a_z_query->get_the_item_id()</code> returns the current item’s ID but does not print it directly</li>
</ul>


AlphaListing

Provides an A to Z index page and widget.

AltPress

<p>This plugin simply displays posts in alhpabetical order and inserts a jump-to bar the top of the page. Is it used by inserting the shortcode [a-z category=””].</p>
<h4>Compatibility</h4>
<p>Tested up to WordPress 4.8.1</p>


List Posts Alphabetically

Plugin is unfinished. Posts are not linked, neither letter on top of it.

AlphaListing vs List Posts Alphabetically