Nilambar Sharma

<p>Are you frustrated by the lack of customization options in default Category widget in WordPress? Then this plugin is for you. Works in similar fashion but with several customization options. Cheers !</p>


NS Category Widget

very nice plugin does what it says!

good job for dev!

Just what i needed

A plugin to add widget for listing Categories and Taxonomies. Extending Default WordPress Category Widget.

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.

NS Category Widget vs A-Z Listing