Descriere
Show your posts, pages, and terms alphabetically in a Rolodex-, catalogue-, or directory-style list with the A-Z Listing plugin!
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.
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.
short-code
The plugin supplies a short-code for the full A-Z listing allowing use without modifying your theme’s templates.
Basic usage is as follows:
[a-z-listing]
To specify a post-type to display instead of page
then use, e.g. post
:
[a-z-listing display="posts" post-type="post"]
To filter the posts by a term from a taxonomy:
[a-z-listing display="posts" taxonomy="category" terms="my-term-slug"]
To display pages that are direct children of the page with ID 24
:
[a-z-listing display="posts" post-type="page" parent-post="24"]
To display pages that are children of any depth below the page with ID 24
:
[a-z-listing display="posts" post-type="page" parent-post="24" get-all-children="yes"]
To show terms from a taxonomy instead of posts and pages, e.g. Terms from the Categories
taxonomy:
[a-z-listing display="terms" taxonomy="category"]
To show terms from the Categories
taxonomy that are direct children of the term with ID of 42
:
[a-z-listing display="terms" taxonomy="category" parent-term="42"]
To show terms from the Categories
taxonomy that are children of any depth in the tree below the term with ID of 42
:
[a-z-listing display="terms" taxonomy="category" parent-term="42" get-all-children="yes"]
To override the alphabet used by the plugin:
[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"]
To add numbers to the listing:
[a-z-listing display="posts" numbers="after"]
The numbers can also be shown before the alphabet:
[a-z-listing display="posts" numbers="before"]
You can group the numbers into a single collection for all posts beginning with a numeral:
[a-z-listing numbers="after" group-numbers="yes"]
To group the alphabet letters into a range:
[a-z-listing grouping="3"]
** The arguments are all optional **
Common options
display
: specifies whether to display posts or terms from a taxonomy.- Default value:
posts
. - May only contain one value.
- Must be set to either
posts
orterms
. - Any value other than
posts
orterms
will default to displaying posts.
- Default value:
numbers
: appends or prepends numerals to the alphabet.- Default value:
unset
. - May only contain one value.
- Must be set to either
before
orafter
. - Any value other than
before
orafter
will default to appending numerals to the alphabet.
- Default value:
grouping
: tells the plugin if and how to group the alphabet.- Default value:
unset
. - May only contain one value.
- Must be set to any positive number greater than
1
or the valuenumbers
. - Any value other than a positive number or the value
numbers
will default to disabling all grouping functionality. - When set to a number higher than
1
the listing will group letters together into ranges. - For example, if you chose
3
then a Latin alphabet will group togetherA
,B
, andC
intoA-C
. Likewise forD-F
,G-I
and so-on. - When using this setting, if numbers are also shown via the
numbers="before"
ornumbers="after"
attribute then they will be shown as a single separate group0-9
. - When set to the value
numbers
it will group numerals into a single group0-9
. - This requires the numbers to be displayed via the
numbers="before"
ornumbers="after"
attributes.
- Default value:
group-numbers
: tells the plugin to group all items beginning with a numeral into a single collection.- Default value:
false
. - May only contain one value.
- Must be set to
true
,yes
,on
, or1
to group items beginning with a numeral in a single collection. All other values will keep the default behaviour.
- Default value:
alphabet
: allows you to override the alphabet that the plugin uses.- Default value:
unset
. - When this attribute is not defined, the plugin will either use the untranslated default, or if glotpress includes a translation for your site’s language as set in
Admin -> Settings -> Site Language
it will use that translation. - The current untranslated default is:
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
. - Accepts a single line of letters/symbols, which need to be separated via the comma character
,
. - Including more than one letter/symbol in each group will display posts starting with any of those under the same section.
- The first letter/symbol in each group is used as the group’s heading when displayed on your site.
- Default value:
Opțiuni articole
post-type
: sets the listing to show a specific post-type.- Default value:
page
. - Multiple post-types may be specified by separating with commas (
,
) e.g.post-type="page,post"
. - Must be the
slug
of the post-type(s).
- Default value:
parent-post
: sets the parent post that all displayed posts must be descended from.- Default value:
unset
. - May only contain one value.
- Must be the
ID
of the parent post. - Add
get-all-children="yes"
to also include all descendants of any depth below the parent post.
- Default value:
exclude-posts
: remove these posts from the list.- Default value:
unset
. - Multiple posts may be specified by separating by commas:
,
. - Must be the
ID
of the post(s).
- Default value:
taxonomy
: sets the taxonomy containing the terms specified in theterms=""
option.- Default value:
unset
. - May only contain one value.
- Must be the
slug
of the taxonomy.
- Default value:
terms
: sets the taxonomy terms for filtering posts.- Default value:
unset
. - The taxonomy must also be specified in
taxonomy
. - Multiple terms may be specified by separating with commas:
,
. - Must be the
slug
of the term(s).
- Default value:
Opțiuni termeni
taxonomy
: sets the taxonomy to display terms from in the listing.- Default value:
unset
. - Multiple taxonomies may be specified by separating with commas:
,
. - Must be the
slug
of the taxonomy.
- Default value:
terms
: sets the taxonomy terms to include in the listing.- Default value:
unset
. - The taxonomy must also be specified in
taxonomy
. - Multiple terms may be specified by separating with commas:
,
. - Must be the
ID
of the term(s). - Cannot be used with
exclude-terms=""
.
- Default value:
exclude-terms
: sets the terms to exclude from display.- Default value:
unset
. - The taxonomy must also be specified in
taxonomy
. - Multiple terms may be specified by separating with commas:
,
. - Must be the
ID
of the term(s). - Cannot be used with
terms=""
.
- Default value:
parent-term
: set the parent that all displayed terms must be descended from.- Default value:
unset
. - May only contain one value.
- Must be the
slug
of the parent term. - Add
get-all-children="yes"
to also include all descendants of any depth below the parent term.
- Default value:
get-all-children
: when a parent term is chosen this option is used to show all children of any depth or only direct children.- Default value:
false
. - May only contain one value.
- Must be set to
true
,yes
,on
, or1
to include all children of any depth. Any value other will use the default behaviour of only showing direct children.
- Default value:
hide-empty-terms
: hide terms that have no posts associated.- Default value:
false
. - May only contain one value.
- Must be set to
true
,yes
,on
, or1
to hide the empty terms. Any other value will use the default behaviour of showing all terms.
- Default value:
Internal-use options for completeness
** You should not need to touch these, as they are meant for internal use by the plugin only**
target
: the default target for a listing that doesn’t show any items.- Default value:
unset
. - May only contain one value.
- Must be set to a URL which will be used as the target for the letters’ hyperlinks.
- Default value:
return
: what type of listing to show, eitherlisting
orletters
.- Default value:
listing
. - May only contain one value.
- Must be set to either
listing
to display the default view, orletters
to show only the letters without any items (posts or terms).
- Default value:
PHP
Synopsis
<?php
the_a_z_listing( $query ); // or
get_the_a_z_listing( $query );
?>
Where $query
is one of the following:
- any valid
WP_Query
parameter array - a
WP_Query
object formed fromnew WP_Query();
- any valid
get_pages()
parameter array. This array must include achild_of
key or aparent
key to tell the plugin that it is aget_pages()
query - a single string containing a taxonomy which will switch the listing to display terms from that taxonomy instead of posts
Reference
Full API documentation is available at A-Z-Listing Reference
Multiple Column Output
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.
Templates and Theming
The plugin allows the site owner, developer, or themer to provide custom templates for the A-Z Listing output.
NOTE: These functions have changed name and method of access in 1.0.0. We have dropped the _a_z_
moniker in the function name and within the template file they are accessed via the $a_z_listing
object. The former function names are still accessible, but are largely deprecated.
To add a template to your theme, you need a file similar to the templates/a-z-listing.php
file in the plugin folder. Your copy needs to be placed within your theme at the theme root directory and called a-z-listing.php
or a-z-listing-section.php
(where -section
is an optional top-level page slug for the section-targeting feature).
The Loop
The theme system this plugin implements is very similar to the standard WordPress loop, with a few added bits.
Important functions to use in your template are as follows:
$a_z_query->the_letters()
prints the full alphabet, and links the letters that have posts to their section within the index page.$a_z_query->have_letters()
returns true or false depending on whether there are any letters left to loop-through. This is part of the Letter Loop.$a_z_query->have_items()
behaves very similarly to Core’shave_posts()
function. It is part of the Item Loop.$a_z_query->the_letter()
similar to Core’sthe_post()
, this will set-up the next iteration of the A-Z Listing’s Letter Loop. This needs to wrap-around the Item Loop.$a_z_query->the_item()
similar to Core’sthe_post()
, 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 within the Letter Loop.
When you are within the Item Loop you may utilise all in-built WordPress Core post-related functions such as the_content()
. Note that titles and permalinks have helper functions to cope with the A-Z Listing showing taxonomy terms (see the next section).
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.
Funcții ajutătoare
The plugin supports displaying taxonomy terms as though each term were a post. This means that the WordPress functions related to posts such as the_title()
and the_permalink()
are unreliable. We have therefore added helper functions which will return or print the correct output for the item.
NOTE: These functions have changed name and method of access in 1.0.0. We have dropped the a_z moniker in the function name and within the template file they are accessed via the $a_z_listing
object. The previous function names are still accessible, but are largely deprecated.
These helper functions cope with the dual usage of the plugin supporting both WP_Query
-based (returning WP_Post
objects) and Taxonomy Terms (returning WP_Term
objects) listings. These are:
$a_z_query->the_title()
– prints the current item’s Title$a_z_query->get_the_title()
returns the current item’s Title but does not print it directly$a_z_query->the_permalink()
prints the current item’s Permalink$a_z_query->get_the_permalink()
returns the current item’s Permalink but does not print it directly
Instalare
Această secțiune descrie cum să instalezi modulul și să-l faci să funcționeze.
Cerințe
- PHP 5.6 is the minimum version you should be using. Preferably use the most-recent version of PHP your host offers; PHP 7.2 is ideal. Older versions of PHP than 5.6 are unsupported.
- The plugin requires
mbstring
turned-on in your PHP installation. Without this feature the plugin might behave oddly or fail.
Instrucțiuni
- Upload the a-z-listing folder to the
/wp-content/plugins/
directory. - Activează modulul în meniul „Module” din WordPress.
- Use the
[a-z-listing]
short-code on the page or post that you want to show the listing. - Add the A-Z Site Map widget to a sidebar.
Întrebări frecvente
-
Why is the list layout completely broken?
-
If you are using a page-builder such as WPBakery or Elementor you need to ensure that you put the short-code into a normal text area. Placing the short-code into a preformatted text area will add
<pre>
tags around the listing output. These extra tags break the layout considerably. -
Why is my list in a single column?
-
The list of items under each letter heading needs to have at least 11 items for a second column to be created. Once you hit the magic 11 items, the list will break into two columns with 6 items in the first column and 5 items in the second. When you get to 21 items a third column will be added if there is room on your page; and so-on up to a maximum of 15 columns if there is enough space, though it is unexpected that any web-page be wide enough for more than a few columns to fit. The columns will fill-up evenly once you have more than one column on the page.
-
How do I show posts of a different post-type (not pages) or multiple post-types (e.g. posts AND pages)?
-
This can be achieved using the short-code or PHP. In these examples the generic phrase
post-type-slug
is used to describe the concept. The default post types provided by WordPress are called „Posts” and „Pages”. Their slugs arepost
andpage
respectively. You need to use these names in place of the examples (i.e.your-post-type-slug
,type1-slug
, andtype1-slug
).short-code method
Single post-type
[a-z-listing post-type="your-post-type-slug"]
Multiple post-types
For multiple post-types just separate them with a comma.
[a-z-listing post-type="type1-slug,type2-slug"]
PHP method
PHP code needs to be added to your theme files, and cannot be used as post or page content in the way that a short-code can.
Single post-type
<?php the_a_z_listing( array( 'post_type' => 'your-post-type-slug' ) ); ?>
Multiple post-types
<?php the_a_z_listing( array( 'post_type' => array( 'type1-slug', 'type2-slug' ) ) ); ?>
The argument to
the_a_z_listing()
is an array and takes the same parameters as WP_QueryThe code above needs to be within a php block which is denoted by the
<?php
and?>
pair. Depending on your theme, you might not need the opening and closing php tags shown in the above snippet; if that is the case, you are free to omit them in your code. -
How do I show posts from a specific category only?
-
This can be achieved using the short-code or PHP. In these examples the generic phrase
taxonomy
andterm
are used to describe the concept. The default taxonomies provided by WordPress are called „Categories” and „Tags”. Their slugs arecategory
andpost_tag
respectively. Each Category and Tag are then known as „terms”. You need to use the slug for each individual category or tag in place of the example slugs (i.e.term-slug
,term1-slug
, andterm1-slug
).short-code method
Single term
[a-z-listing taxonomy="taxonomy-slug" terms="term-slug"]
Multiple terms
For multiple terms just separate them with a comma.
[a-z-listing taxonomy="taxonomy-slug" terms="term1-slug,term2-slug"]
PHP method
PHP code needs to be added to your theme files, and cannot be used as post or page content in the way that a short-code can.
<?php the_a_z_listing( array( 'tax_query' => array( 'taxonomy' => 'your-taxonomy-slug', 'field' => 'slug', 'terms' => array( 'term1-slug', 'term2-slug' ) ) ) ); ?>
Any number of terms may be added to the
terms
array, including one or none.The argument to
the_a_z_listing()
is an array and takes the same parameters as WP_QueryThe code above needs to be within a php block which is denoted by the
<?php
and?>
pair. Depending on your theme, you might not need the opening and closing php tags shown in the above snippet; if that is the case, you are free to omit them in your code. -
How do I show terms from a taxonomy instead of posts?
-
This can be achieved using the short-code or PHP. In these examples the generic phrase
taxonomy
andterm
are used to describe the concept. The default taxonomies provided by WordPress are called „Categories” and „Tags”. Their slugs arecategory
andpost_tag
respectively. You need to use the slug for the taxonomy in place of the example slugs (i.e.taxonomy-slug
).short-code method
[a-z-listing taxonomy="taxonomy-slug" display="terms"]
The taxonomy parameter takes a single taxonomy’s slug, e.g.
category
orpost_tag
.The
display="terms"
attribute is required to display taxonomy terms instead of posts.PHP method
PHP code needs to be added to your theme files, and cannot be used as post or page content in the way that a short-code can.
<?php the_a_z_listing( 'taxonomy-slug' ); ?>
The argument to
the_a_z_listing()
is a string and contains the slug of a single taxonomy, e.g.category
orpost_tag
.The code above needs to be within a php block which is denoted by the
<?php
and?>
pair. Depending on your theme, you might not need the opening and closing php tags shown in the above snippet; if that is the case, you are free to omit them in your code. -
How do I remove section targeting or limit which sections are available?
-
In your theme’s
functions.php
file add the following code:<?php add_filter( 'a-z-listing-sections', '__return_empty_array' ); ?>
This filter may also be used, by removing entries which are standard $post variables, to limit which top-level pages are used as section identifiers.
If there is code already in your functions.php then add just the lines between
<?php
and?>
on the line directly after the very first instance of<?php
. -
I am not using the short-code so the styles are not working, can I still use the in-built styles without the short-code?
-
Yes you can. This needs the following code added to your theme’s
functions.php
file. We purposely only display the stylesheet on pages where the short-code is active.<?php add_action( 'init', 'a_z_listing_force_enable_styles', 99 ); ?>
If there is code already in your theme’s
functions.php
file then add just the lines between<?php
and?>
on the line directly after the very first instance of<?php
.The sidebar widget styling also works in a similar manner, and will also respond to the same code above to forcibly enable it.
You can add code which detects the page which the user is browsing and only enable the override on that page so that network requests are kept to a minimum (this is the same reason we detect usage of the short-code).
<?php add_action( 'init', 'your_override_wrapper_function', 99 ); function your_override_wrapper_function() { if ( ! is_page( 'your-a-z-listing-page-slug-or-ID' ) ) { // ID is numeric, slug is a string. return; // we don't want to run for anything except the page we're interested in. } a_z_listing_force_enable_styles(); // this is the page we want, so run the function to enqueue the styles. } ?>
If there is code already in your theme’s
functions.php
file then add just the lines between<?php
and?>
on the line directly after the very first instance of<?php
. -
How do I disable the in-built styling?
-
In your theme’s functions.php add the following code:
<?php add_filter( 'a-z-listing-add-styling', '__return_false' ); ?>
If there is code already in your functions.php then add just the lines between
<?php
and?>
on the line directly after the very first instance of<?php
. -
How do I display the listing as a tabbed panel?
-
In your theme’s functions.php add the following code:
<?php add_filter( 'a-z-listing-tabify', '__return_true' ); ?>
If there is code already in your functions.php then add just the lines between
<?php
and?>
on the line directly after the very first instance of<?php
.
Verificări
Contributori și dezvoltatori
„A-Z Listing” este un software open-source. La acest modul au contribuit următoarele persoane.
Contributori„A-Z Listing” a fost tradus în 7 locale. Mulțumim traducătorilor pentru contribuția lor.
Tradu „A-Z Listing” în limba ta.
Te interesează dezvoltarea?
Răsfoiește codul, vezi depozitarul SVN, sau abonează-te la jurnalul de dezvoltare prin RSS.
Istoric modificări
3.1.2
- Ensure extra composer dependencies aren’t included in distribution. Otherwise identical to 3.1.1.
NEW EXTENSIONS
Check out the two new extensions at A-Z-Listing.com. These extensions provide convinience functionality. Purchasing one or both will help towards the cost of maintaining the A-Z Listing plugin.
3.1.1
- Bugfix to squash a PHP deprecation warning when running PHP-7.4+
3.1.0
- Ensure paths are correct when loading PHP files.
- Add hook to customise sorting of items within each letter.
- Fix broken permalinks on hierarchical post-types, e.g. page.
3.0.2
- Fix for causing „This site is experiencing difficulties” errors on some sites.
3.0.1
- Fix broken permalinks in 3.0.0
3.0.0
This is a major version change, which means that it might break your site when you upgrade. Please check in a test site first!
- Add
get_the_item_id
andthe_item_id
template tags. - Add
get_the_item_type
template tag. - Add support for extensions.
- Complete refactor to use more modern PHP features.
- Minor refactoring of
get_the_item_object
,get_item_meta
, andget_the_item_count
template tags. - Miscellaneous documentation Fixes.
2.3.0
- Add multiple taxonomy support to taxonomy terms listing.
- Add site health-check feature compatibility.
- Fix
hide-empty-terms
in a taxonomy terms listing. Previously completely broken. - Fix hard-coded
admin-ajax.php
URL in widget configuration javascript. - Improve documentation in the readme.txt file, which is shown on the plugin page at WordPress.org.
2.2.0
- Add
get_the_item_post_count
andthe_item_post_count
template methods to get or display the number of posts associated with a term. - Add support for
get-all-children
when specifying aparent-term
. - Add extra filename for template matching:
a-z-listing-$slug.php
where$slug
is the slug of the post containing the short-code. - Deprecate PHP 5.3-5.5. Please ensure you are running at least PHP 5.6. The plugin may work on older PHP versions, but compatibility is not guaranteed.
- Bugfix for incorrect behaviour of
exclude-terms
in the short-code. Thanks go to Chris Skrzypchak for finding this.
BREAKING CHANGES in 2.0.0+
Multi column example
- If you have copied the multi-column example in previous releases to your theme folder then you will need to perform some manual steps.
- If you have not edited the file, just delete it and the new template from the plugin will take control and perform the same functionality.
- If you have modified the example template then you will need to compare with the file in the plugin at
templates/a-z-listing.php
and merge any changes into your template.
Template customisations
- If you have customised the in-built templates or written your own then you may experience breakage due to the post object not being loaded automatically.
- If you require the template to access more than the post title and URL then you will need to add an additional call after
the_item()
to load the fullWP_Post
object into memory. - To load the post object you need to call
$a_z_query->get_the_item_object( 'I understand the issues!' );
.
The argument must read exactly as written here to confirm that you understand that this might cause slowness or memory usage problems.
This step is purposely omitted to save memory and try to improve performance.
Previous
See the file called changelog.md
for the full release history.