dexxaye

Comment Archive

Dani Llewellyn

<p><a href="https://liberapay.com/diddledan/donate" rel="nofollow ugc"></a></p>
<p>Show your posts, pages, and terms alphabetically in a Rolodex-, catalogue-, or directory-style list with the A-Z Listing plugin!</p>
<p>The plugin has a short-code for the list, and a widget so you can link to the list from anywhere on your site. If a letter doesn’t have any pages then the widget will display the letter unlinked. The list page will omit the display for that letter entirely.</p>
<p>Show posts from any or multiple post types including the in-built posts and pages. Also supported are post-types from plugins like WooCommerce products. Alternatively, show terms like categories or tags.</p>
<h3>block</h3>
<p>Version 4.0.0 introduces new block editor support. You should use the block in most cases, as it helps to guide you through configuring the various options.</p>
<h3>short-code for compatibility and PHP use</h3>
<p>The plugin supplies a short-code for the full A-Z listing allowing use without modifying your theme’s templates.</p>
<p>Basic usage is as follows:</p>
<pre><code>[a-z-listing]
</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>[a-z-listing display="posts" post-type="post"]
</code></pre>
<p>To filter the posts by a term from a taxonomy:</p>
<pre><code>[a-z-listing 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>[a-z-listing 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>[a-z-listing 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>[a-z-listing 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>[a-z-listing 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>[a-z-listing 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>[a-z-listing 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>[a-z-listing display="posts" numbers="after"]
</code></pre>
<p>The numbers can also be shown before the alphabet:</p>
<pre><code>[a-z-listing display="posts" numbers="before"]
</code></pre>
<p>You can group the numbers into a single collection for all posts beginning with a numeral:</p>
<pre><code>[a-z-listing numbers="after" group-numbers="yes"]
</code></pre>
<p>To group the alphabet letters into a range:</p>
<pre><code>[a-z-listing 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, if you chose <code>3</code> then a Latin alphabet will group together <code>A</code>, <code>B</code>, and <code>C</code> into <code>A-C</code>. Likewise for <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>: allows you to override the alphabet that the plugin uses.
<ul>
<li>Default value: <code>unset</code>.</li>
<li>When this attribute is not defined, the plugin will either use the untranslated default, or if <a href="https://translate.wordpress.org/projects/wp-plugins/a-z-listing" rel="nofollow ugc">glotpress</a> includes a translation for your site’s language as set in <code>Admin -> Settings -> Site Language</code> it will use that translation.</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/symbol in each group is used as the group’s heading when displayed on your 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>** You should not need to touch these, as they are meant for internal use by the plugin only**</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( '[a-z-listing]' );</code> and save or <code>echo</code> the returned text. The parameter passed to <code>do_shortcode()</code> should be a complete A-Z Listing shortcode with parameters as above.</p>
<h4>Legacy method</h4>
<pre><code><?php
the_a_z_listing( $query ); // or
get_the_a_z_listing( $query );
?>
</code></pre>
<p>Where <code>$query</code> is one of the following:</p>
<ul>
<li>any valid <a href="https://codex.wordpress.org/Class_Reference/WP_Query" rel="nofollow ugc"><code>WP_Query</code></a> parameter array</li>
<li>a <code>WP_Query</code> object formed from <code>new WP_Query();</code></li>
<li>any valid <a href="https://codex.wordpress.org/Function_Reference/get_pages" rel="nofollow ugc"><code>get_pages()</code></a> parameter array. This array must include a <code>child_of</code> key or a <code>parent</code> key to tell the plugin that it is a <code>get_pages()</code> query</li>
<li>a single string containing a taxonomy which will switch the listing to display terms from that taxonomy instead of posts</li>
</ul>
<h4>Reference</h4>
<p>Full API documentation is available at <a href="https://a-z-listing.com/reference/" rel="nofollow ugc">A-Z-Listing Reference</a></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 A-Z Listing output.</p>
<p><em>NOTE: These functions have changed name and method of access in 1.0.0. We have dropped the <code>_a_z_</code> moniker in the function name and within the template file they are accessed via the <code>$a_z_listing</code> object.</em> The former function names are still accessible, but are largely deprecated.</p>
<p>To add a template to your theme, you need a file similar to the <code>templates/a-z-listing.php</code> file in the plugin folder. Your copy needs to be placed within your theme at the theme root directory and called <code>a-z-listing.php</code> or <code>a-z-listing-section.php</code> (where <code>-section</code> is 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 use in your template are as follows:</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 A-Z Listing’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 A-Z Listing’s Item Loop, the same way the normal WordPress Loop works. This needs to be <em>within</em> the Letter Loop.</li>
</ul>
<p>When you are within the Item Loop you may utilise all in-built WordPress Core post-related functions such as <code>the_content()</code>. Note that titles and permalinks have helper functions to cope with the A-Z Listing showing taxonomy terms (see the next section).</p>
<p>I advise that you start with a copy of the default template template when customizing your own version. The supplied templates show the usage of most of the functions this plugin provides.</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><em>NOTE: These functions have changed name and method of access in 1.0.0. We have dropped the </em><em>a_z</em> moniker in the function name and within the template file they are accessed via the <code>$a_z_listing</code> object. The previous function names are still accessible, but are largely deprecated.</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>
</ul>


A-Z Listing

Provides an A to Z index page and widget. The widget links to the index page at the appropriate letter.

Comment Archive vs A-Z Listing