Wordpress Folding Category List (FoCaL)

Folding Category List is a Wordpress sidebar widget that will show a category list that expands as you click into each sub-level.

As your blog gets more and more posts you will inevitably create more categories to keep them organised. Eventually, your categories will take up more room on your screen and scroll across many pages. I work on one blog which has over 350 categories and with this number, the standard WordPress category list is the height of three or four screens - any content below this is lost!

Key Features

• jQuery Animation: Use Suckerfish or Superfish to animate drop down menus! -- js included in plugin, just activate from control panel!
• jQuery Animation: Use Simple jQuery Accordion to animate vertical menus! -- js included in plugin, just activate from control panel!
• SEO friendly: Add nofollow and descriptions to links.
• Multi-widget: Have as many lists as you need.
• Multi-category: If posts are in multiple categories, you can still control which one to expand, or expand all of them.
• International: Plugin is compatible with translation plugins (qTranslate).
• Control: Change order by category name, id, description, post count or use My Category Order plugin for total control.
• Pages: Expand category list on pages using custom fields.
• Style: There are lots of different options for CSS tags allowing designers to create unique menus.

Latest Version & Download

The latest version of FoCaL is 2.0.6 (02/02/2013)

You can download the plugin from the WordPress plugin repository.

Upgrading to 2.0.x

Since multi-widget administration has been overhauled, it may be necessary to reconfigure settings definitions should the plugin not be able to automatically do this for you. In most cases all you have to do is "save" the widget in the widgets screen and this will be enough to update the database.

If you have used the PHP code to add the widget to your page, you will have to make a slight amendment. The parameter "number" in the $instance array has been renamed to "definition". Please refer to the advanced usage guide for details on PHP usage.

The change was required as the old system was a bit backward, having to select/create a "setting definition" from the widget and configure it in the admin page. This has been reversed so that now you create and configure from the admin screen and just select the appropriate one from the widget.

Sorry for the inconvenience this may cause, but it'll be better in the long run and a requirement for some things I have in the pipeline for this plugin.

Changes since previous version:

• Redeveloped multi-widget administration
• Suckerfish and Superfish support with jQuery
• Accordion style menus with jQuery
• Add custom html before and after menu
• Override category title and/or URL
• Bug Fixed:
  • Showing before and after title when title empty
  • Showing of empty categories with private entries

Installation and Configuration

Download and extract the zip file to your WordPress plugin folder and activate in the control centre. You then should have a widget listed under Appearance > Widgets which you can add to your sidebar. All configuration is now done through the Settings > FoCaL menu option (see below). Alternatively, you can install the widget directly from the plugin's screen.

Once the plugin is activated, head over to the FoCaL configuration screen and set up a settings definition.

Settings Definitions

A settings definition is a configuration that is used by a widget (or widgets). Each widget must link to a definition. Definitions are configured through the Settings > FoCaL menu option. The options are self-explanatory and have in-line help. Once a definition has been created you can add a widget to a sidebar and select the definition from the options dialogue.

Using the Priority List

To set up a prioritised list, simply enter a comma-separated list of category ID's in the order you wish to expand. If the post is not a member of the first category in the list it will check the second and third etc... If none is found it will expand the first category of the post with the lowest ID.

This plugin will look at the category hierarchy, so you can specify a parent category to expand if a post is a member of any of its child categories.

Custom Fields

You can also expand and highlight an item on the list when viewing a page. Simply create a custom field for the page called "category" and give it a value equal to the numerical ID of the category to expand. This works for posts as well - you can force a single post to expand any category you like, just create a custom field called category and insert the numerical id of the category to expand.

Creating Child Categories

To create a child category in WordPress, either create a new category or edit an existing one, and change the "category parent" to the category that is to be the parent. Your category will now be shown indented by the parent.

No Widget Support?

If you do not have widgets enabled on your sidebar, or if you choose to include the FoCaL in a non-widget area (header or footer for example) you can use this code to include the folding category list manually:

$focal = new FoldingCategoryList();
$focal->widget($args, $instance);

PHP variable $args contains an array of sidebar arguments, such as before_title and after_title. Please refer to the WordPress codex on these arguments.

PHP variable $instance should contain information about the instance of the widget you are trying to show. I know it's a bit awkward at the moment, I'll try and tidy this up a bit, but you need to create an array of two elements: the first the title of the widget and the second the setting definition name.

Example

$focal = new FoldingCategoryList();
$args = array(
    'before_widget' => '<li>',
    'after_widget'  => '</li>',
    'before_title'  => '<h2 class="widgettitle">',
    'after_title'   => '</h2>'
);

$instance = array(
    'title' => 'Navigation Menu',
    'definition' => 'default' // name of the setting definition
);

$focal->widget($args, $instance);

Un-install

Should you choose to uninstall this widget you can simply use the uninstall option from the settings page and then disable or delete the plugin. This will delete the cache and settings records for this widget from the WordPress database. To uninstall a previous version (<=0.7.2) you will need to manually delete three records from the wp_options table where option_name is widget_lwfcl, widget_lwfcl-cache and widget_lwfcl-parental.

CSS

Each type of node on the tree has its own CSS class to allow great flexibility in the way the focal tree is displayed. Below is a quick list of the CSS classes and the elements.

• ul.FoldingCategoryList - The root list class for the list
• ul.nodeLevel0 - The root node level
• ul.nodeLevel1 - The first level of child categories
• ul.nodeLevel2 - The second level of child categories (you get the idea...)
• li#cat-XX - You can enable each li to have an id containing the unique category id (cat-1, cat-45, cat-321 etc)
• li.selected - The item that is selected (*)
• a.focalLinkSelected - The link item that is selected
• li.haschildren - This category has child categories (*)
• li.nochildren - This category does not have any children (*)
• li.selectedparent - This item is a parent or grandparent of the selected item (*)
• (*) - These items can be set to show on the 'li' tag, the 'a' tag or a 'span' tag.

Examples

Please note: The exact CSS required will depend on the theme you are using. These examples may need to be modified to work with your theme.

I am going to assume that all ul, ol and li CSS selectors have been reset:

ul, ol, li {margin:0;padding:0;list-style:none}

You should now be able to apply the following CSS for these effects:

/* Makes selected category highlighted */
.focalLinkSelected {color:black;font-weight:bold}
 
/* Add a · (·) before sub category items. Replace B7 with ascii code for any symbol */
.FoldingCategoryList li ul li:before {content:"B7 20";}
 
/* Indent Child Category */
.FoldingCategoryList li ul {margin-left:6px} /* nodeLevel1 */
.FoldingCategoryList li ul li ul {margin-left:6px} /* nodeLevel2 */
/* or */
.nodeLevel1 {margin-left:6px}
.nodeLevel2 {margin-left:6px}
 
/* Change colour of indent items */
.nodeLevel1 a {color:red}
.nodeLevel2 a {color:white}
.nodeLevel3 a {color:blue}
 
/* Add a picture icon to child categories */
.nodeLevel1 li {background-image: url('image.png'); background-repeat:no-repeat; padding-left:12px; background-position:top left}

The only limit to the CSS effects you can apply is that of your imagination.

Advanced Usage

The widget supports several WordPress filters and actions so that you can control the style and layout of items. You can even override category titles and URLs if you wish, or add items to the menu (as seen on the horizontal menu at the top of this page).

Adding HTML Items

You can add a simple link before or after the menu using the Additional Links section of the admin panel, however, you can add more complex links (or any HTML) using PHP and hooking into the plugin. Like the example on this page, you can add a search bar to the list and have it styled the same as the list.

There are two functions that you can use, addMenuItemBeforeCategory and addMenuItemAfterCategory. Both take the same parameters:

addMenuItemBeforeCategory($html_content, $sequence)

$html_content can be any valid HTML which the plugin will be contained within <li></li> tags. $sequence is an integer value which you can use to order the items.

Example

$focal = new FoldingCategoryList();
$args = array(
'before_widget' => '',
'after_widget'  => '',
'before_title'  => '',
'after_title'   => ''
);

$instance = array(
'title' => '',
'definition' => 'timtrott'
);

$focal->addMenuItemBeforeCategory('<a href="/">Home</a>', 10);
$focal->addMenuItemBeforeCategory('<a href="/about/">About</a>', 20);

$focal->addMenuItemAfterCategory('<a href="/portfolio/">Portfolio</a>', 10);
$focal->addMenuItemAfterCategory('<form method="get" id="searchform" action="">
<div><input type="text" class="text" size="18" value="'.wp_specialchars($s, 1).'" name="s" id="s" />
<input type="submit" id="searchsubmit" value="Search" />
</div>
</form>', 20);

$focal->widget($args, $instance);

Override Category Title and/or URL

Two filters have been added so that you may override the category title and/or the URL the link goes to. There could be many reasons for wanting to do this, and in the main horizontal menu on this page, I have used both - the Tutorials menu item links to a page rather than the category list, while the sub-items link to the sub-category listings.

Examples

This code would go into your theme functions.php

function redirect_category($url) 
{
if ($url == 'https://timtrott.co.uk/wordpress-folding-category-list/')
  $url = 'https://timtrott.co.uk/category/internet/web/wordpress/';
else if ($url == 'https://timtrott.co.uk/category/internet/web/wordpress/')
  $url = 'https://timtrott.co.uk/wordpress-folding-category-list/';

return $url;
}
add_filter('focal_cat_link_url', 'redirect_category', 0);

A similar function exists for changing the category title - you may have a very long category title that needs to be shorter on the menu.

function rename_category($title) 
{
if ($title == 'Your  Very Long Category Title')
  $title = 'Short Title';

return $title;
}
add_filter('focal_cattitle', 'rename_category', 0);

Any Questions?

If you have any questions, problems, queries or suggestions, please use the form below and I'll do my best to get back to you as soon as I can. You can also leave feedback on the WordPress Forums, although I do not check there very regularly.