Breadcrumbs API

[cjbrooks12]

This would add a way to generate dynamic breadcrumbs for every page. Breadcrumbs should in some way reflect that pages position in the navigational hierarchy of the site, and doesn't necessarily correspond one-to-one with its URL structure.

The API will come in the form of a new method getBreadcrumbs() on the OrchidPage object. Internally, the Page maintains a Prioritized list of Breadcrumbs objects, which are an iterable container of Breadcrumb objects. The page/plugin can define its own Breadcrumb structure (such as the wiki or static page structure), other plugins may dynamically attach additional breadcrumbs (such as with the Taxonomies plugin), or you may ignore it to let Orchid try and work out the structure. This structure will come from adding a parent field to the OrchidPage class, and use the target page's hierarchy of parent pages to build the breadcrumb structure.

When displaying breadcrumbs, the normal method will either return the most highly prioritized breadcrumbs container, or internally set a String option to pick a named breadscrumbs container. An alternative method, getBreadcrumbs(String key) would allow one to manually specify which breadcrumb they want, and getAllBreadCrumbs() would return all attached breadcrumbs.

This should be implemented as a BreadcrumbHolder interface with a delegate in the OrchidPage class, similar to the existing AssetHolder.

To-Do

• [x] Make BreadcrumbHolder class with the following methods:
  • [x] Breadcrumbs getBreadCrumbs()
  • [x] Breadcrumbs getBreadCrumbs(String key)
  • [x] List<Breadcrumbs> getAllBreadCrumbs()
  • [x] void addBreadcrumbs(Breadcrumbs breadcrumbs)
• [x] Make BreadCrumbs class as an iterable wrapper around List<BreadCrumb>
• [x] Make BreadCrumb class as container for a Breadcrumb link, which has the following properties
  • [x] String link - A link to a page
  • [x] String title - The text to display in the link
  • [x] boolean active - Whether this link represents the current page
• [x] Changes to OrchidPage
  • [x] Implement BreadcrumbHolder interface with a delegate
  • [x] Add OrchidPage parent field
• [ ] Implement default breadcrumbs for the following plugins:
  • [x] Wiki: wiki / [wiki section] / wiki page
  • [x] Pages: Add PageRelations to StaticPages so the user can specify next/previous/parent pages. The user-defined parent page can then be used as the actual parent page. If this if not defined, use the next page up in the hierarchy to be the parent page.
  • [ ] Taxonomies: Add non-default breadcrumbs for the hierarchies created by the Taxonomies generator
• [ ] Write unit tests for Breadcrumbs classes
• [ ] Document Breadcrumbs usage

[altavir]

I would like to propose and alternative mechanism of generating default breadcrumbs. Each page could have an optional parent field, which point to the page id. The parent page, when resolved could also have its own parent (if parent not defined, then the element is root). Then we have a chain of ancestry and can create breadcrumb bar from it. In this case, you do not need to redefine the whole path for each new page and move pages in the hierarchy without bothering with descendants.

Also I think that breadcrumbs should be defined in component and not be the part of page definition. This way one can for example define two different breadcrumbs bars in one page. Sometimes it is useful.

[cjbrooks12]

Yeah, I definitely like that idea better for the default breadcrumbs, it actually makes the default still meaningful and also intelligently-built for each plugin's real domain model.

As for where breadcrumbs should be held, I think being on the Page object directly is still a good idea, because breadcrumbs seem more of a concern of the Theme than of the page content or the page components. This makes it easy/expected for a theme to customize the markup for breadcrumbs to fully match the entire site.

But the setup described above expects that a page might have multiple types of breadcrumbs that it wants to show, and so there should definitely be a Component to show these breadcrumbs to show multiple types, or in the case that a theme doesn't support them by default.