WordPress Plugin - Generates and displays breadcrumbs
PHP
Switch branches/tags
Latest commit ab33dc1 Feb 24, 2017 @jhned jhned Misc. fixes
Permalink
Failed to load latest commit information.
hansel-gretel
.gitignore
README.md

README.md

Hansel & Gretel

A WordPress Breadcrumb Generator Plugin

Where The Heck Am I?

Let's face it: breadcrumbs are an integral part of websites these days. They give an immediate sense of hierarchy to your visitors and allow users to backtrack through your site to (hopefully) find more content. WordPress simplifies structuring sites how ever it seems reasonable, but it takes a bit more effort to generate breadcrumbs for all the different types of posts, and pages, and taxonomies, and archives, and ... you get the idea.

But there are already plugins for that, aren't there?

Sure! And a lot of them work really well for simple sites with simple hierarchies, but many of them fall short in one way or the other:

Want to use the new semantic <nav> element?
Nope sorry, all they have are <p>'s or <ul>'s.

Need to control the classes or IDs of the crumbs?
Yep, nope; their wrapper has a fixed class of breadcrumbs though...I hope that's all you need.

Uh...okay what about custom taxonomies?
You already know the answer to this question...

And custom post types?
Better hope they're hierarchical!

Should I even bother mentioning rich snippets/microdata?
Haven't found one yet.

Okay fine, but what makes you think yours is any better?

It might be obvious (considering the previous section) that this plugin seeks to address all the customizability problems with the existing breadcrumb plugin environment while still keeping it as easy to use as possible (read: HAG_Breadcrumbs();, done!). It's as simple as that. Hopefully it can live up to your expectations!

Features

The following features are currently available unless otherwise specifed.

  • Simple Installation
    Upload the plugin, activate via the WordPress admin, and drop the function where you want the breadcrumbs to appear in your template. Done! Read on for the juicy details.

  • Fine-Tuned Control
    H&G works right out of the box, but oftentimes we want custom control. Nearly every aspect of the breadcrumbs rendering can be changed a'la the myriad of options available, either at the function call or via the provided admin menu (coming soon).

  • Microdata Integration
    H&G by default includes the microdata format for a WebPage's breadcrumbs, a format that is jointly supported by Bing, Google, Yahoo! and Yandex.

  • Full Markup Control
    Choose any element to wrap your breadcrumbs, including optional class(es) or id attributes. Likewise, you can include prefix and suffix content right inside the wrapper element tags for further control.

  • Template Hierarchy Based Rendering
    H&G utilizes the WordPress Template Hierarchy to determine which crumbs to show, including that elusive Comments Popup Window everybody (read: nobody) uses! This means, regardless of your theme, Hansel & Gretel will follow WP's lead about the content on the page.

  • Custom Post Types & Taxonomies
    Never worry about how breadcrumbs behave across your fancy new post types and taxonomies. H&G accounts for hierarchical and non-hierarchical types, whether or not they have an archive page, and also provides options to override breadcrumb display for individual post types if desired.

  • Home & Last Crumbs
    H&G allows full control in showing home breadcrumbs and even allows for customized Front Page versus Blog Home Page templates. Likewise, the last, current page crumb has equal control depending on the needs of your theme.

  • Made for Theme Developers
    Hansel and Gretel was made by theme developers for theme developers. The default options and degree of customizability were all considered by our team of experienced WP developers to make sense right out of the box, with as little further customization as possible. Give it a try and let us know what you think. We all want H&G to be the simplest and smartest breadcrumb plugin you'll ever use!

Installation

Installing Hansel & Gretel is easy-peasy, but of course there's a bit of administrative work on the front end you'll need to take care of.

Requirements & Compatibility

Minimum (theoretical) Wordpress Version Required: 3.1.0
Actually Tested Versions 3.3.2, 3.4.X, 3.5

If you find it non-operational on your particular flavor of WP, please let us know.

Instructions

  1. Make sure WordPress 3.1.0 or better is running on your site. It will not work with older versions.

  2. Get the plugin onto your site, in one of many ways:

    • Use the Plugin Manager via the WordPress admin to install the plugin (via Add New). Search for "Hansel & Gretel" and click install on this plugin.
    • Download the stable zip archive from the WordPress Plugin Repository and extract the contents.
    • Download the bleeding-edge zip archive from GitHub and extract the contents.
    • Clone the GitHub Repository to your local machine (or even your remote server on some hosting providers!) and always have an up-to-date version available to you.
  3. If you didn't use the Plugin Manager to install H&G, upload the hansel-gretel folder to your plugins directory (/wp-content/plugins/hansel-gretel/).

  4. Activate the plugin through the Plugins page on the WordPress admin.

  5. Add the following snippet to your theme file(s) outside The Loop where you want the breadcrumbs to appear:

  <?php if (function_exists('HAG_Breadcrumbs')) { HAG_Breadcrumbs(); } ?>
  1. Profit!

Options

Wow there are a lot...I thought you said this was simple?!

It is! Even though there are 30+ options that you can set on H&G, you don't need to set a single one to make it work out of the box. These options are available to fine-tune how you wish the breadcrumbs to appear and are completely...well, optional.

How are options prioritized?

There are many ways to set the options for this plugin, so knowing how the options are prioritized is important if you're wondering why the changes you just made aren't showing up. Below is the list of options from lowest to highest priority; higher priority options override matching lower priority ones.

  1. Plugin Defaults
    These are the out-of-the-box default options set by the plugin. They provide the base for the behavior of the H&G.

  2. Admin-Set Defaults (coming soon)
    These are the options set for the plugin from the settings page in the WordPress Admin. These are a subset of the available options, but include the most widely used ones.

  3. Admin-Set Post Type Defaults (coming soon)
    These are post-type specific overrides to the global defaults set in the admin (#2). Want your Gizmo post-type breadcrumbs to show up differently? This is where you'd want to set it.

  4. Function-Set Options
    When calling HAG_Breadcrumbs(); in your template file, providing an array of options and their desired values will override all admin defaults. All options can be set from this method. See below for the format.

  5. Function-Set Post Type Options
    Like the admin-set equivalent, these post-type specific options will override the global function-set ones (#4).

Using The Function-Set Options

Theme developers will be familiar with this pattern of providing settings to a function in WordPress. Below is an example of setting some common options, and providing some post-type specific overrides:

<?php if (function_exists('HAG_Breadcrumbs')) { HAG_Breadcrumbs(array(
  'prefix'     => 'You are here: ',
  'last_link'  => true,
  'separator'  => '|',
  'excluded_taxonomies' => array(
  	'post_format'
  ),
  'taxonomy_excluded_terms' => array(
  	'category' => array('uncategorized')
  ),
  'post_types' => array(
    'gizmo' => array(
      'last_show'          => false,
      'taxonomy_preferred' => 'category'
    ),
    'whatzit' => array(
      'separator' => '&raquo;'
    )
  )
)); } ?>

The above example sets the prefix for the breadcrumbs to You are here:, adds the link to the last crumb, and changes the separator to the pipe (|). Also, the theme-generated post_format taxonomy is excluded from the breadcrumbs, and the term uncategorized (Uncategorized) is never displayed on a post page. When on a gizmo post-type page, the last crumb is set not to show and the taxonomy crumbs will be categories. Likewise, on a whatzit post-type page, the separator has been overriden to show &raquo; (») instead.

Debug Options

debug_show (bool | Default: false)

Whether or not debug information for the plugin should be printed to the output.

debug_comment (bool | Default: true)

Whether or not the debug information should be printed in an HTML comment. Otherwise, the debug information will be output in a <pre> element.

Wrapper Options

wrapper_element (string | Default: 'p')

The HTML element that wraps the entire breadcrumbs list. Any valid element name will be accepted; so use whatever makes semantic sense for your theme!

wrapper_class (string | Default: '')

The class(es) applied to the wrapper element. May be left blank for no class(es) to be added.

wrapper_id (string | Default: 'breadcrumbs')

The ID applied to the wrapper element. May be left blank for no ID to be added.

microdata (bool | Default: true)

Whether or not to include microdata on the breadcrumbs. Adds itemprop="breadcrumb" to the wrapper element per Schema.org.

prefix (string | Default: '')

The content and/or markup to be added immediately after the opening of the breadcrumbs wrapper. May be left blank for no content to be added.

suffix (string | Default: '')

The content and/or markup to be added immediately before the closing of the breadcrumbs wrapper. May be left blank for no content to be added.

Crumb Options

separator (string | Default: '&raquo;')

The content and/or markup to be added between crumbs. The separator is padded on both sides by a single space before rendering. May be left blank for no separator to be added.

crumb_element (string | Default: '')

The HTML element that wraps each breadcrumb. May be left blank for no element to be applied.

crumb_class (string | Default: '')

The class(es) applied to the crumb element or crumb link if it exists. May be left blank for no class(es) to be added.

crumb_link (bool | Default: true)

Whether or not the crumbs should link to their associated pages in the hierarchy.

link_class (string | Default: '')

The class(es) applied to the crumb link if it exists. May be left blank for no class(es) to be added.

The Home Crumb Options

home_show (bool | Default: true)

Whether or not a root crumb for the site home page should be shown.

home_link (bool | Default: true)

Whether or not the root crumb should be linked ot the site home page.

home_label (string | Default: 'Home')

The label for the root crumb if it is included.

home_class (string | Default: '')

The class(es) applied to the root crumb if it is included. May be left blank for no class(es) to be added.

home_id (string | Default: '')

The ID applied to the root crumb if it is included. May be left blank for no ID to be added.

Taxonomy Options

taxonomy_show (bool | Default: true | Version: 0.0.4+)

Whether or not taxonomy breadcrumbs should be included for the current location. This is only applicable on singular, non-archive pages for non-hierarchical post types (e.g., posts).

taxonomy_ancestors_show (bool | Default: true)

Whether or not to show the ancestors of a hierarchical term in a taxonomic archive. For a singular post page, whether or not to include taxonomic crumbs in the breadcrumbs.

taxonomy_preferred (string | Default: '')

By default, the breadcrumbs will choose the most popular taxonomy associated with the post if multiple are assigned. Choosing a preferred taxonomy will attempt to choose the assigned taxonomy before falling back to the default method. Will only be applicable on posts that have assigned taxonomies.

excluded_taxonomies (array | Default: array() | Version: 0.0.4+)

An array of taxonomies (names/slugs) that should be excluded from the breadcrumbs. Will only be applicable on singular, non-archive pages for non-hierarchical post types.

taxonomy_excluded_terms (array | Default: array() | Version: 0.0.4+)

An associative array of '{taxonomy-name}' => array(...) including the term slugs of that taxonomy that should not be included in the breadcrumbs. This is only applicable on singular, non-archive pages for non-hierarchical post types. See the above example for usage.

The Last Crumb Options

last_show (bool | Default: true)

Whether or not to show the last crumb (the current page) in the breadcrumbs.

last_link (bool | Default: false)

Whether or not the last crumb (the current page) is linked.

last_class (string | Default: 'current')

The class(es) applied to the last crumb if it is shown. May be left blank for no class(es) to be added.

last_id (string | Default: '')

The ID applied to the last crumb if it is shown. May be left blank for no ID to be added.

The Other Crumb Options

404_label (string | Default: 'Page Not Found')

The label for the 404 crumb if last_show is true.

search_label (string | Default: 'Search Results')

The label for search results pages if last_show is true and search_query is false.

search_query (bool | Default: false)

Whether or not to include the search term as a crumb if last_show is true. The query string is escaped prior to output via WordPress's get_search_query().

Post Type Options

post_type_show (bool | Default: true)

Whether or not a crumb should be included for the post type of the current page. Will only be applicable on post types where an archive exists.

post_types (array | Default: array())

An associative array of '{post-type}' => array(...) including the same options as above, overriding for the keyed post type. These post-type-specific settings override any predefined defaults for the breadcrumbs. See the above example for usage.

Development

Release History

  • X.X.X The Bleeding Edge...

  • 0.0.5 January 4, 2013, Updates for WP 3.5 and some minor fixes:

    • Errors related to 'attachment' post type objects & the get_object_taxonomies() corrected
    • Excluded custom blog home page crumb for search results and 404 pages
    • Addition of WordPress Repository Plugin files for posterity/convenience
  • 0.0.4 October 1, 2012, Ability to control and limit which (if any) taxonomies are shown for non-hierarchical post types.

    • Ability to show or hide taxonomy terms on singular non-hierarchical post pages
    • Ability to exclude certain taxonomies from the breadcrumbs
    • Ability to exclude specific terms from the breadcrumbs
    • Can now hide parent terms for taxonomy crumbs on singular post pages
    • Other small bug/formatting fixes...
  • 0.0.3 August 2, 2012, First stable version release.

  • 0.0.2 July 31, 2012, Refactored to split out Crumb and Wrapper logic into separate classes.

  • 0.0.1 July 27, 2012, Finished basic breadcrumb generation.

Upcoming Features

  • Admin Menu for end-user friendly customization
  • WP Hook/Filter integration for intercepting the various steps of the breadcrumb generation, for the truly masochistic.
  • Globalization support.

Want to Help?

We'd love to see anything you've got that will improve Hansel & Gretel. Remember, the goal is to make it work for most cases right out of the box! Please be consistent with the project's coding style with your additions.

Many Thanks!

Plugin Development & Testing: Chris Roche
Plugin Development & Testing: Glenn Welser
Preliminary Development & Review: Taylor Gorman
SEO Consultation: Seth Wilson

License

Copyright 2012-2013  Clark Nikdel Powell  (email : wordpress@clarknikdelpowell.com)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as 
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA