WebspaceWorks Resources

Fold Category List

The WordPress category list has a tendency to become unwieldy as the number of nested categories increases. The provided wp_list_cats template tag can display all top level categories, or only the categories within a parent, but does not allow for a collapsible categories list where only the currently active category is expanded to have its children displayed, all others are listed collapsed (folded) to their top-level parent. Fold Category List has been developed to meet that need, implementing the functionality of Fold Page List for WP categories.

Internals

Fold Category List is based upon wp_list_cats, and list_cats, modified and renamed for this plugin. This enables the existing functionality of wp_list_cats to be retained (in fact the available arguments are the same as for that tag), while extending it to support the folding of sub-categpry lists for all categories other than the selected category.

New in 2.0 (06 January, 2008 — updated to version 2.02 on 09 January, 2008)

The “biggie” here is that Fold Category List now supports for WP2.3+, while remaining compatible with previous versions of WP. This is achieved through an internal version switch. Version 2.0 also includes support for new arguments orderby, order and title_li for WP2.3+.

The subsequent point update to 2.02 adds new capabilities that should allow Fold Category List to be used from pages showing single posts. There remain problems since a post may be linked to multiple categories, in which case the plugin will select the first such linked category that is returned.

New in 1.0 (release) onwards (18 February, 2007 — updated to version 1.11 on 20 February, 2007)

Fold Category List now supports running (cumulative) counts and inclusion of empty parent categories with posts in sub-categories (version 1.0 onwards)
By convention wordpress excludes empty categories from its category list, which can cause problems where posts are linked against sub-categories, since without the parent category being visible, the sub-category can’t then be reached. The solution here is to set the hide_empty argument to be false (or zero), which will then force all empty categories to be listed, even if entire sub-hierarchies have no posts linked.

In addition to this, wordpress’ display of the number of posts in a category is just that, giving no indication of how many posts may be linked to any sub-categories. In a folded navigation seeing a category as having zero posts suggests there is nothing to be gained by following that link, when it is quite possible there could be posts set against sub-categories of the parent.

Version 1.0 (the first full release version of the plugin) addresses these two shortcomings by extending the use of two existing arguments, with the following effect:

  • hide_empty: Set to a value of ‘2’ causes empty categories to be included in the list, only if they contain child categories that have posts associated with them. In other words, if the cumulative (running) count for all posts under that category and all its child categories is 1 or more, then the category will be listed.
  • optioncount: Set to value of ‘2’ causes the running (cumulative) count for a category and all its descendent categories to be displayed in stead of the category specific count that is the wordpress standard.

New in 1.0b4 (28 January, 2006)

Fold Category List now supports the optional use of truncated category descriptions for the title attribute of the link. This needs to be used in conjunction with the (included) wswwpx_category_description to correctly handle output of category descriptions elsewhere in the site.

Installation

Simply place the expanded file fold_category_list.php in the path ‘/wp-content/plugins/’ in your WordPress installation, and activate it in the admin interface.

All function names include the initials ‘wswwpx’ in a prefix, so there should be no conflicts with any other functions.

WP2 compatibility: fold_category_list is compatible with WP v.2.0.x and 2.1 (stable).

Usage

Fold Category List would typically be used to replace the functionality provided by the wp_list_cats tag that is usually found in the sidebar.php file in your active theme, itself located in wp-content/themes folder of your installation. To use, simply replace the code fragment that looks like this
<?php wp_list_cats ($args); ?>
with this:
<?php wswwpx_fold_category_list ($args); ?>
You can even use the same arguments as in the original call.

$args is optional and conforms exactly to those supported by the wp_list_cats tag that comes with WordPress 1.5, and which is explained in the Wordpress Codex

It is recommended however that at least the “hide_empty=0” option be set since without this any categories that lie below an empty category will not be shown

Since Fold Category List is built on top of wp_list_cats, it should retain all functionality of that tag, but enhance it with these further capabilities.

  • Expand only the sub-hierarchy of the currently requested category to one layer down
  • Keep all other sub-hierarchies collapsed to their parent

Truncated category descriptions for tooltips

This capability has been introduced to provide more control over the text that is used in the title attribute on links. Natural wordpress uses either the category title (same as the link text), or the full description (often too long) for this attribute. Fold Category List now allows you to add a “preamble” to the category description, that can then be extracted for use as the title attribute on a link, or dropped when displaying the full description for the category.

To use this new feature there is one new argument for (wswwpx_fold_category_list), and one new function (wswwpx_category_description). The new argument is “cut_desc” and is used to specify the marker used in the description to identify where to cut it. Text before this marker is used as the short description, text after it is taken as the full description. This additional argument has to be used togther with the built-in “use_desc_for_title” set to true (default). For example, to use a ‘||’ (double pipe) as a cut marker, the call would be:
<?php wswwpx_fold_category_list("hide_empty=0&cut_desc=||" ); ?>

With a truncation matker embedded into the actual description field for a category, the category_description needs to be modified to drop any text before this marker. This is the purpose of the wswwpx_category_description template tag, now introduced. This takes three arguments:

<?php wswwpx_category_description ($cat, $marker, $show_part); ?>

These are:

  1. $cat: The category ID, or the category structure. Default: 0
  2. $marker: The marker that indicates the cut point. The cut will occur at the first instance of this marker in the description, which is broken into two parts. Default [empty string], duplicates behaviour of category_description
  3. $show_part: The part to output. Can take one of two possible values: 0 (before marker description) and 1 (after marker description). The default is 0.

Download

Current version (v2.02):
fold_category_list.php.zip [09 January, 2008].

History

  • 09 January, 2008: Current version (v2.02): New feature
    • Added case to capture category of single post… In situations where more than one category assignemnt will use first retrieved category.
    • Easier version switch (internal)
  • 07 January, 2008: (v2.01 - not released): Header correction
    • Corrected reporting of version number in plugin header.
  • 06 January, 2008: (v2.00): WP2.3 Compatibility release
    • Addressess underlying database changes introduced with WP2.3, while retaining compatibility with previous versions
    • Includes support for ‘orderby’ and ‘order’ arguments that replace the old ’sort_column’ and ’sort_order’ arguments, adopting new sorting defaults for WP2.3+
    • Retains the ability to custom truncate descriptions for use as link titles (tooltips) for WP 2.3+
  • 22 February, 2007: (v1.12): Bugfix
    • Applies patch from Fold Page List for better handling of array manipulation that may have caused warning messages to appear. No such thing was reported, so this is a preventive fix.
  • 20 February, 2007: (v1.11): Compatibility & bugfix
    • Fixes for further compatibility issues found under testing of v1.1. All known issues resolved.
  • 20 February, 2007: (v1.1 - not released): WP 2.1 compatibility
    • Initial fixes to address WP 2.1 compatibility issues emerging after v1.0 was released.
  • 18 February, 2007: (v1.0): Release version and feature upgrade
    • Added the ability to keep running counts of all posts within a category, summing across all child categories.
    • Extended the use of hide_empty and optioncount arguments to support running counts in a sensible manner.
  • 11 September, 2006: (v1.0b6): Bug fix
    • Fixed a bug preventing description truncation on sub-categories.
  • 11 September, 2006: (v1.0b5 - not released): Feature enhancement
    • Added current_cat_ancestor class to allow separate styling of ancestor categories for the currently selected category
    • Added link deadening for the currently selected category within the displayed category menu
  • 28 January, 2006: (v1.0b4): Feature enhancement
    • Added facility for short category descriptions to be used as link titles and a new wswwpx_category_description template tag to allow extraction of specific parts.
  • 5 January, 2006: (v1.0b3): Bugfix
    • Changes for WP2.0 compatibility, especially w.r.t. permalinks
    • Added new internal function to support getting name of a specific category, different from current category)
  • 8 November, 2005 (v1.0b2): Beta, bugfix
    • Fix for when ancestors array wasn’t being initialised.
  • 8 November, 2005: First Public Beta (v1.0b1), bugfix
    • Consolidates permalink support and implements progressive hierachical display, consistent behaviour with Fold Page List
    • Reorganisation of code, extra commenting.
  • 7 November, 2005: Private alpha (v0.9a4), bugfix
    • Initial support for permalinks using category names instead of ids (internal build)
  • 7 November, 2005: Public alpha (v0.9a3), bugfix
    • Re-implement based on ‘list_cats’ from wp 1.5.2. Fixes non-folding, non-sorting behaviour of previous alphas.
  • 28 September, 2005: (v0.9a2): Public Alpha: Security update.
    • Added a check for integer content of variable to internal functions to obstruct potential for SQL insertion attacks. Recommended for all users.
  • 05 June, 2005: (v0.9a1): Public Alpha.
    • Lacks some of the refinements of fold_page_list with regard to style classes on ‘current’ selection tree. Otherwise stable

Technorati Tags: , , , , ,


Webspace Works: Effective website design, development & search engine optimisation

Simply effective, web design that works!

W3Csites.com Web Standards Group: Promoting Accessibility and standards across the internet This page uses valid CSS
This page uses valid XHTML 1.0 Transitional This page works in all modern browsers Sitening perfect score Real Design Network Approved