Reference

The Hierarchy API provides components that can be used to access the hierarchy of a given page, which is then used to display, e.g., the breadcrumb on top of all Cristal pages.

Existing implementations

• XWiki @xwiki/platform-hierarchy-xwiki
• File System @xwiki/cristal-hierarchy-filesystem
• GitHub @xwiki/cristal-hierarchy-github
• Nextcloud @xwiki/cristal-hierarchy-nextcloud

Details

A PageHierarchyResolver is a component that offers a single method:

/**
 * Returns the page hierarchy for a given page.
 *
 * @param pageData the page for which to compute the hierarchy
 * @returns the page hierarchy
 **/
getPageHierarchy(pageData: PageData): Promise<Array<PageHierarchyItem>>;

A PageHierarchyItem is a simple data structure that maps a label with an URL to reach the hierarchy component:

/**
 * Description of a hierarchy item for a given page.
 **/
type PageHierarchyItem = {
  label: string;
  pageId: string;
  url: string;
};

Even though there is a default implementation in DefaultPageHierarchyResolver, it is expected that any backend should implement their own PageHierarchyProvider with logic specific to the backend. *E.g.,*

/**
 * Implementation of PageHierarchyResolver for the XWiki backend.
 **/
@injectable()
class XWikiPageHierarchyResolver implements PageHierarchyResolver {
  // XWiki specific implementation.
}

Each backend-specific implementation should be registered with the name of the backend that they support, and will then be available through DefaultPageHierarchyResolverProvider.get() whenever the backend is in use.