Skip to content

Latest commit

 

History

History
172 lines (120 loc) · 3.68 KB

README.md

File metadata and controls

172 lines (120 loc) · 3.68 KB
Raw

WP Crumbs v1.0.2

Simple Wordpress Breadcrumbs

Installation

Install with Composer

Add the package to your projects composer.json file. Visit getcomposer.org more information.

{
    "require": {
        "jjgrainger/wp-crumbs": "dev-master"
    }
}

Install Manually

Download and include the class file into your themes functions.php:

include_once 'path/to/Crumbs.php';

Usage

Basic usage

Use the_crumbs to display the breadcrumbs in your template.

the_crumbs();

Options

An optional array of arguments can be passed to modify the breadcrumb output. The defaults for each option are display below.

Example
the_crumbs(array(
    'home' => 'Home',       // Title for the Home (front page) link
    'blog' => 'Blog',       // Title for the blog home page
    'seperator' => '/',     // Seperator to use between each crumb (string or false)
    'class' => 'crumbs',    // The class(es) applied to the wrapper element ('crumbs', 'nav crumbs')
    'element' => 'nav'      // The HTML element to use (div, nav, ol, ul)
));
Output
<nav class="crumbs">
    <a href="http://site.com/">Home</a>
    <span class="sep">/</span>
    <a href="http://site.com/blog/">Blog</a>
    <span class="sep">/</span>
    <span>Single Post Title</a>
</nav>

Advanced usage

get_crumbs()

Use get_crumbs() to retrieve an array of crumbs. Each crumb has a title and url.

Example
$breadcrumbs = get_crumbs();

print_r($breadcrumbs);
Output
Array(
    [0] => Array(
        [title] => "Home"
        [url] => "http://site.com/"
    )
    [1] => Array(
        [title] => "Blog"
        [url] => "http://site.com/blog/"
    )
    [2] => Array(
        [title] => "My First Post"
        [url] => false
    )
)

You can modify the returned array and/or create a function to create an output of your choosing.

get_crumbs accepts the same aguments as the_crumbs.

Filters

You can further modify the crumbs array using a filter on get_crumbs. This will also effect the output of the_crumbs.

Example
// Example: modify title for a custom post type
function modify_crumbs($crumbs) {

    // if on events archive change title to shows
    if(is_post_type_archive('event') || is_singular('event')) {
        for($i = 0; $i < count($crumbs); $i++) {
            if($crumbs[$i]['title'] === 'Events') {
                $crumbs[$i]['title'] = "Shows";
            }
        }
    }

    return $crumbs;
}

add_filter('get_crumbs', 'modify_crumbs');

array_insert()

array_insert() is a function that allows you to insert a new element into an array at a specific index. You can see a gist of it here.

when modifying the crumb trail you can add new crumbs at specific points.

Example
// Example: add post type archive on taxonomy archive page
function modify_crumbs($crumbs) {

    // if on the events category archive page
    if(is_tax('event-categories')) {

        // create a new crumb
        $crumb = array(
            'title' => "Shows",
            'url' => site_url('/shows')
        );

        // add the new crumb at the index of 1
        $crumbs = array_insert($crumbs, $crumb, 1);
    }

    return $crumbs;

}

add_filter('get_crumbs', 'modify_crumbs');

Notes

Author

Joe Grainger