Crumbs API Redesign - 2.x branch

Note: This issue is more a "note to self".
To anyone else: I do not expect anyone to make sense of my writing in this post. That said, if you are the lucky one who does, and you have an opinion, then please let me know!

---------------------

Major changes to the 1.x approach.

Clear distinction of $trail vs $breadcrumb.

• $trail means an array of menu_get_item() items, keyed by system path.
• $breadcrumb means an array of breadcrumb items containing the link_path and link_title.
• crumbs_get_trail() will only get the trail, not the breadcrumb.
• breadcrumb might get a "lazy" implementation, so it is only built when needed in the page.tpl.php.
• The trail is built by TrailFinder, the breadcrumb is built by BreadcrumbBuilder. We could name the TrailFinder a TrailBuilder instead.

Plugin objects and keys

• What was previously called $object is now called $plugin.
• During one invokeAll(), each plugin object is invoked only once.
• If one plugin has more than one rule, its methods will have to return associative arrays.
• The define() method replaces the getRuleTitles() method.

hook_crumbs_plugins() instead of fancy class naming patterns.

• In 2.x it doesn't matter anymore how plugin classes are named. You implement the hook_crumbs_plugins(), and let it return one or an array of plugin objects. A factory hook, if you want.
  The reason: Many modules need more than one plugin object, so in 1.x we ended up with a lot of static factory methods. Static methods are no better than floating functions, and classes should not be abused as namespaces. Thus, back to the good old Drupal hook.

findParent() and findTitle(), instead of decorateItem().

• findTitle() becomes a method hook with a return value. The good thing about methods with a return value is that we know when we are finished.
• Each thing to find (parent and title) has a dedicated method. We have no more general-purpose decorateItem() method. Again, this way it's easier to know when we are finished, and it's easier to sort the results.
• skipInBreadcrumb() is no longer needed. Instead, just return a title = FALSE.
• decorateBreadcrumb() to alter the titles and other things. Such as, abbreviate some of the titles. Note that findTitle() is invoked per breadcrumb item, while decorateBreadcrumb() is invoked for the entire array of items, after findTitle() has been invoked for each.

One-shot method hooks: decorateBreadcrumb() and preprocessPage().

• Both of these method hooks can be interesting for custom and site-specific modules, but none of them is used in any of the plugins shipped natively with crumbs. I have personally used what is now becoming decorateBreadcrumb() in a project-specific module, for hand-crafted title abbreviation tricks. preprocessPage() is used in the crumbdown module.
• The invokeAll() method will invoke each plugin object once, as mentioned above. However, the decorateBreadcrumb() and preprocessPage() methods don't have return values, and thus nothing can be sorted by weights beyond the order of the plugin objects themselves. Thus, these two method hooks will not work with multi-rule plugin objects.

Plugins: Multi-rule vs One-rule.
I will comment on this later ..

Goodbye to ItemWrapper.

• This idea turned out to be more in the way than it helps. In 2.x, router items will be passed to the plugin methods as arrays, instead of being wrapped in objects with fancy ArrayAccess and magic __get(). The arrays will not be passed by reference, so there is no chance to edit them directly.

get module_load_include() out of global scope.

• In the 2.x branch, include files will only be loaded when needed, from the respective function.

Open questions / Unsolved problems

Default status for new crumbs plugins and rules?
When new modules are enabled, or menus or taxonomies created, that produce new crumbs plugins or rules, crumbs should do something useful, without the admin having to visit the crumbs configuration page each time.
For some plugins it will be reasonable to have them automatically enabled, as soon as they appear. Example: Forum, Organic Groups. For others we don't want that. Example: Node Reference - not every nodereference expresses a parent-child relationship.
We need a possibility in the define() method to express that a module should be disabled by default.

Link title (tooltip) ?
I don't think we will get tooltips ... Most of the core breadcrumbs don't have them either.

Won't fix issues.

"change the path of a breadcrumb item".
(was requested in another issue)
This would be like changing the nid of a node. You just don't do that.
Whatever one wants to achieve with changing the path can be done in a different way.

support drupal_set_breadcrumb()
The problem: At the time that we want to build a crumbs trail, the breadcrumb set with drupal_set_breadcrumb() might not yet exist. This is especially true if some module calls crumbs_get_trail() in hook_init() for theme switching or other things. Thus, each module that calls drupal_set_breadcrumb() will need a crumbs plugin that replicates the behavior.
Sorry.

"needs review" = "probably fixed in 2.x"

Most of this is done in 2.x-dev.

Reopen if you miss anything.