Crumbs module - how it works.

Module page: http://drupal.org/project/crumbs

(text moved from the module page. will work on it.)

Building the Trail

The module takes the path of the current page, and computes a parent path from that.
The process is repeated with the parent path, until either
- no further parent can be found.
- the returned path is the frontpage.
- the path is its own parent path.
- there is an infinite loop consisting of more than one path. (B is the parent of A, C is the parent of B, A is the parent of C ..). Crumbs will skip all paths that are part of the loop, and go directly to the frontpage.

The result is a trail of paths, that will be used to build the breadcrumb (always starting with the frontpage).

Finding the parent for a given path.

Given a system path, the plugin engine will invoke the "findParent()" method hook, to determine the parent path for that specific item.

The findParent() method can return either a string (the path), or an array of parent path candidates. The plugin engine will sort these candidates by priority, with user-defined weights, that the plugin itself does not know about.

Plugins that return an array of candidates, have to declare the possible array keys in the define() method hook, so that the configuration page can make these keys available for sorting.

The findParent() method has two arguments:
- $path - the system path. (Yes, this is already cleaned up with drupal_get_system_path)
- $item - the item obtained with menu_get_item($path). For instance, on node pages, the node object is already available in $item['map'][1].

Example: Consider that a path is part of two different menus. The admin decides that only one of these menus will be used for breadcrumb building. The menu plugin (class _menu_CrumbsPlugin__hierarchy) returns an array of two parent path candidates, keyed by menu name. The plugin engine (or rather, the InvokeAction) will then pick one of these candidates, depending on the configuration.

The menu hierarchy plugin has to implement the define() method hook, and declare all the possible keys using the addRule() method. That is, all menu names (machine name). The rules will then be available in the configuration page as "menu.hierarchy.primary-links", or "menu.hierarchy.menu-media" etc.

Building the Breadcrumb

For each item in the trail, the plugin engine will invoke the "findTitle()" method hook to determine a title for that specific item. This works very similar to the findParent() method.

Again, the findTitle() method can return either a string (to be used as a title), or an array of title string candidates. And again, you need to implement the define() method to make these rules available on the configuration form.

If no title is found, the title from menu_get_item() will be used as a fallback.

Sorting the plugin rules

Modules can add their own rules to determine how the parent path is computed. The rules can be ordered or enabled/disabled in a drag-and-drop table in the configuration settings (/admin/structure/crumbs)

In addition, every rule object has a chance to set a different title for a breadcrumb item (default is obtained from core menu system), or to let the item be skipped in the trail.

Shipped with the module are rules for breadcrumbs based on taxonomy, custom menus etc, as listed above.

For special use cases I recommend to add new rules in a site-specific custom module. The shipped examples should be quite useful as a guide. The pitfall: As long as this is in unstable/alpha/beta state, it can happen that I will change the API, and you would have to adapt your custom modules. Ideally, you should tell me about your use cases, so I can consider them in future API design changes.