Hierarchical Pages Widget Plugin

Two widgets are provided, for displaying a vastly condensed
hierarchial list either of pages, or of categories and custom
taxonomies. Designed for large sites with hundreds of pages, or when
using custom post types or custom hierarchical taxonomies.

With Pages: Always displays the current page, the pages above it back
to the home page, and the current page’s children. Detects nested
categories and custom taxonomies, and likewise displays the categories
or taxonomies above and below the currently displayed one.

The behavior of the widget is all configurable through its
configuration screen, as follows:

• The Categories widget will also display custom taxonomies.
  The admin screen includes a list of the defined ones;
  leave the field blank to use the built-in post categories.
• The title is optional (blank will emit no heading); with
  a blank heading and top-level entries (pages/categories/
  taxonomies) disabled, you can have the widget only display
  when the user is “currently inside” a page/post that matches
  what the widget is set to display.
• Pages may be sorted in Menu Order or alphabetically.
  To sort pages in menu order, with pages of the same order
  alphabetical, set the Sort Field parameter to:
  menu_order,post_title … some sites have reported issues
  and seem to require that only menu_order be specified.
• Categories and custom taxonomies may be sorted by name,
  slug, or other fields displayed on the admin form.
• Sort order can be ASC or DESC
• Siblings to the current page, if enabled, means that child
  pages of the current page’s parent will be displayed.
  Disabling this makes for shorter page lists but the user
  might not be able to move “sideways” in the site.
• If there are many top-level pages (pages with no Parent set),
  you can disable their listing.
• If your site has an Introduction or splash page, as a static home
  page, you might want to disable showing it (presumably it is
  accessible through an icon link). However, if the homepage has
  children, it will always be displayed (otherwise you could never
  navigate to those pages).
• For Pages, you may optionally specify a meta-key and value
  which must be matched for pages to be listed in the widget.
• Also for Pages, you may select posts that match a given
  Author or post status. Leave these blank for “all authors”
  and “publish” status.
• Empty categories/taxonomies may be hidden.
• Both plugins permit specifying either an include list or
  an exclude list. These are comma-delimited lists of
  ID numbers. You may specify either include or exclude, not both.

Spanish translation provided courtesy Andrew Kurtis of WebHostingHub.com
Thanks, Andrew!

This section describes how to install the plugin and get it working.

e.g.

1. Upload plugin-name.php to the /wp-content/plugins/ directory
2. Activate the plugin through the administration menus in WordPress
3. Add the widget to one of your sidebars.

1. 

   Home page of example site. Only the top-level pages are shown.

2. 

   After clicking "Architectural Uses" the children of that page are visible, along with all the top-level pages.

3. 

   After further clicking "Retention Walls" the third-level pages under that section show.

4. 

   The widget options screen.

5. 

Can I change the format of the display?

Only to the extent that the built-in function wp_list_pages() permits.
The plugin works by retrieving a full list of pages, selecting only those
pages that are desired according to the widget settings, and then passing
those as an ‘include’ list to wp_list_pages.

You can change the way the current page is displayed, by modifying the
current_page_item entry in your stylesheet. The documentation of
wp_list_pages() at https://codex.wordpress.org/Template_Tags/wp_list_pages
explains:

All list items (li) generated by wp_list_pages() are marked with the class page_item. When wp_list_pages() is called while displaying a Page, the list item for that Page is given the additional class current_page_item. 

Similarly, the style current-cat is provided for the current category.

Why are no pages listed?

This can happen if you are viewing a Post, rather than a Page, and you
have “Always show top-level pages?” un-checked. (The plugin does not
find a path from the home page to your current location, so it has
nothing to display.) If your site has a static home page without
children, you should check either the top-level option, or the “Show
the static home page?” option.

Are there more versatile ways to exclude pages from the list?

If the exclude list parameter is insufficient, you might try the
Exclude Pages plugin, which is compatible with this one:

https://wordpress.org/extend/plugins/exclude-pages

How can I rearrange my posts and pages?

Try the Pagemash plugin which lets you move pages up, down, in, out,
and around your hierarchy with the mouse. It automatically changes
the pages’ parents and menu order.

https://wordpress.org/extend/plugins/pagemash/ 

If it’s posts you wish to rearrange, try this:

https://wordpress.org/extend/plugins/postmash/ 

Can I call the widgets in a shortcode, or from my theme?

Yes. Try this code, for example, in your theme’s functions.php:

function my_category_shortcode($attr) { HierCatWidget::hiercat_list_cats($attr); } add_shortcode('categories','my_category_shortcode'); 

That will create a shortcode: [categories] which you can invoke
with these arguments, which match the parameters in the widget
configuration screen:

• title — Title to print, if any.
• show_siblings — Show siblings to the current category? 0 or 1
• include — Include list. Comma-delimited list of category IDs, or
  blank for all
• exclude — Exclude these IDs
• orderby — Sort field. Enter one of: name, count, term_group, slug
  or a custom value. Default: name
• order — Sort direction. ASC (default) or DESC
• child_of — Optional: Only display Categories below this ID
• hide_empty — Hide empty categories?
• show_count — Show count of category entries?
• taxonomy — Custom taxonomy. Enter one of: category, post_tag,
  nav_menu, link_category, post_format. Omit for post categories.

Likewise you could define a shortcode which calls
HierPageWidget::hierpages_list_pages to list pages, with parameters
similarly taken from the definition of that function.

Your functions.php file or any part of your theme could also call
either of those two list functions directly.

1.0

• Initial version on wordpress.org

1.0.2

• Permit blank title
• Better handle cases where pages have no children

1.0.3

• Add exclude parameter

1.0.4

• Resolve warning message when viewing excluded pages

1.0.5

• Suppress output when no pages selected

1.1

• Categories: Add include, order, orderby, child_of parameters
• Add taxonomy parameter to support link and other categories
• Support selecting pages by meta key/value pairs, and by author

1.2

• Correct typos in argument handling for Pages

1.3

• Do not redefine existing class

1.4

• When fourth-level or higher levels of page nesting are used,
  do not omit the siblings of second and intermediate level pages.
  (Previously, some page levels would “disappear” as you
  navigated further into a deeply nested site.)

1.5

• Support use of custom post types. Thanks to G.Breant.

1.6

• Handle case of no categories being returned.

1.6.1

• Add isset() calls to suppress error chatter about undefined array entries
• Completes the internationalization interface
• If only the current page were to be listed, the output of the widget is
  entirely suppressed.
• Spanish translation provided courtesy Andrew Kurtis of WebHostingHub.com