Crumbs API - build your own crumbs plugins.

Module page: http://drupal.org/project/crumbs
Conceptual background: How it works.
Example module: crumbs_example, shipped with Crumbs.

Crumbs plugins are reponsible for two things. Ok, three things.

• Finding the parent path of a given path.
• Finding the breadcrumb title for a breadcrumb item.
• Altering the breadcrumb, once it's been created.
  (but you don't really need this, most of the time)

Plugin registration

All Crumbs plugins are registered with hook_crumbs_plugins().
In your custom module:

/**
 * Implements hook_crumbs_plugins()
 *
 * @param crumbs_InjectedAPI_hookCrumbsPlugins $api
 */
function MYMODULE_crumbs_plugins($api) {
  $plugin = new \Drupal\MYMODULE\MyCrumbsPlugin();
  $api->monoPlugin('myPlugin', $plugin);
}

This hook has no return value. Instead, you register everything directly into the $api object. The $api object's class is crumbs_InjectedAPI_hookCrumbsPlugins, and it has a number of methods to register specific types of plugins.

findTitle() and findParent()

Most of the plugins implement either a findTitle() or a findParent() method.
findParent() returns candidates for parent-finding. findTitle() returns candidates for title-finding. Usually every candidate is a string - more details below.

We say "candidates", because only one of them will finally be used for the parent or title, depending on the plugin weights. The other candidates will be discarded.

There are dedicated interfaces for plugins that can find a parent, and those that can find a title. We will go into more detail further below.

MonoPlugin vs MultiPlugin

As said, the job of a findTitle() or findParent() method is to return possible candidates for the parent path or the title of a breadcrumb item.

The findTitle() or findParent() method of a MonoPlugin returns only ONE candidate, or NULL to let other plugins decide, or FALSE to terminate the title- or parent-finding with no result.

The findTitle() or findParent() method of a MultiPlugin returns an associative array of candidates, where each candidate can be a string or FALSE.
The keys of this array of candidates become part of the candidate keys.
We will discuss MultiPlugin on a separate doc page.

namespace Drupal\MYMODULE;
class MyCrumbsPlugin implements crumbs_MonoPlugin_FindTitleInterface {
  function findTitle($path, $item) {
    // Hardcoding node ids is a bad idea, but ok for this example.
    if ($path === 'node/7') {
      // Breadcrumb title for 'node/7'.
      return t('Cucumber');
    }
    // Return NULL otherwise. IDEs like to complain if this is not done explicitly.
    return NULL;
  }
}

Plugin keys and candidate keys (MonoPlugin)

Each plugin is identified by a plugin key. The plugin key is built from the module name and the key that was used to register the plugin.

E.g. in the above example, the plugin key will be "MYMODULE.myPlugin".

Each candidate returned by a plugin also gets a key, the "candidate key", which is then used to assign a priority / weight to the candidate.
The candidate key for a MonoPlugin candidate is the same as the plugin key.
(The candidate key for a MultiPlugin candidate is discussed on the next page.)

So, in the above example, the candidate key for "Cucumber" is just "MYMODULE.myPlugin".

The describe() method (MonoPlugin)

The describe() method is quite important for MultiPlugin plugins, as we will see on the next page.

For MonoPlugin plugins, the method is quite boring. It only serves to add some information on the admin/structure/crumbs/weights form.

The describe() method of a MonoPlugin can either return a label (string), or register a label into the $api argument.

namespace Drupal\MYMODULE;
class MyCrumbsPlugin implements crumbs_MonoPlugin_FindTitleInterface {
  function findTitle($path, $item) {
    ..
  }
  function describe($api) {
    $api->titleWithLabel(t("Sets 'Cucumber' as a title for node/7."), t('Label'));
  }
}

Plugins need to be serializable!

As of 7.x-2.x, plugins need to be serializable so they can be cached between requests. Usually that should not be worrying you, but it should be kept in mind.

(PHP objects are serializable by default, except when they are not..)

findParent($path, $item) (MonoPlugin)

The findParent() method takes a path and a (spiced-up) router item, and returns
- on mono plugins, a candidate for the parent of the given path.
- on multi plugins, an array of those.

The $item array is what you know from menu_get_item(), with an additional $item['route'] for the router path (actually this is identical with $item['path'], but 'route' is more meaningful to read), $item['alias'] and $item['link_path'] (the system path).

The returned path can be a system path or an alias. For multi plugins, the return value is expected to be an array. The keys of this array should correspond with the rules declared in the describe() method.

findTitle($path, $item) (MonoPlugin)

The findTitle() method takes a path and a (spiced-up) router item, and returns a candidate for the title of the breadcrumb item, or FALSE, to skip this breadcrumb item.

Usually you want to use this method if the default title of the breadcrumb is too long or too awkward, or if the default plugins do not return a title at all.

Important: If the title for a breadcrumb item is FALSE, this item will be skipped!!

One default implementation can be found in the menu.link_title plugin, that uses the title stored in menu_links as the link title.

Plugins for specific routes

Plugins can be registered for specific routes, such as node/% or taxonomy/term/%.

To do this, simply use the $api->routeMonoPlugin() or $api->routeMultiPlugin() methods, which take the route as the first argument.

/**
 * Implements hook_crumbs_plugins()
 *
 * @param crumbs_InjectedAPI_hookCrumbsPlugins $api
 */
function hook_crumbs_plugins($api) {
  $plugin = new \Drupal\MYMODULE\MyCrumbsPlugin();
  $api->routeMonoPlugin('node/%', 'myPlugin', $plugin);
}

Closures (anonymous functions) instead of plugin classes

Closures, introduced in PHP 5.3, provide a very convenient alternative to plugin classes.
They reduce the clutter of having the plugin class separate from the hook implementation.

/**
 * Implements hook_crumbs_plugins()
 *
 * @param crumbs_InjectedAPI_hookCrumbsPlugins $api
 */
function hook_crumbs_plugins($api) {
  $plugin = new \Drupal\MYMODULE\MyCrumbsPlugin();
  $api->routeTitleCallback(
    'node/%',
    'cucumberCallback',
    function($path, $item) {
      if ($path === 'node/7') {
        // Breadcrumb title for 'node/7'.
        return t('Cucumber');
      }
      return NULL;
    });
}

Entity plugins

Entity plugins are plugins that find a parent for entity paths, and that are agnostic to the entity type.

E.g. the plugin for taxonomy term reference parent-finding plugin is available for any entity type, be it a node, a commerce product, etc.

Entity plugins should be documented on a separate page, which does not exist atm.
For the time being, look at existing examples in the Crumbs code base.