Disclaimer: This website requires Please enable JavaScript in your browser settings for the best experience.

Dev GuideAPI ReferenceUser Guide
HomeDev GuideRecipesAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
GitHubNuGetDev CommunityOptimizely AcademySubmit a ticket
Start typing to search…

GraphClient utility functions

Learn about GraphClient functions for retrieving page hierarchies and child pages to build navigation menus and breadcrumbs.

The Optimizely JavaScript SDK provides utility functions to let you build navigation menus, breadcrumbs, and understand page hierarchies. You can access these functions through the GraphClient instance.

getPath()

The getPath() method returns the ancestor pages of a given page, ordered from the root to the current page. Use this method to build breadcrumb navigation.

Signature

async getPath(path: string, options?: GraphGetLinksOptions): Promise<Array<PageMetadata> | null>

Parameters

  • path – The URL path of the page (for example, /en/about/team).
  • (Optional) options
    • host – The host URL for filtering.
    • locales – Array of locale codes to filter by.

Returns

An array of page metadata objects ordered from the root to the current page. Returns null if the page does not exist.

Example: Build breadcrumbs

import { GraphClient } from '@optimizely/cms-sdk';

const client = new GraphClient(process.env.OPTIMIZELY_GRAPH_SINGLE_KEY!);

export default async function Page() {
  const currentPath = '/en/about/our-team';

  // Get all ancestor pages
  const ancestors = (await client.getPath(currentPath)) || [];

  // Filter out the start page (first item) and create breadcrumbs
  const breadcrumbs = ancestors.slice(1).map((ancestor: any) => ({
    key: ancestor._metadata.key,
    label: ancestor._metadata.displayName,
    href: ancestor._metadata.url.hierarchical,
  }));

  return (
    <nav aria-label="Breadcrumb">
      <ol>
        {breadcrumbs.map((crumb) => (
          <li key={crumb.key}>
            <a href={crumb.href}>{crumb.label}</a>
          </li>
        ))}
      </ol>
    </nav>
  );
}

getItems()

The getItems() method returns the direct child pages of a given page. Use this method to build navigation menus and site maps.

Signature

async getItems(path: string, options?: GraphGetLinksOptions): Promise<Array<PageMetadata> | null>

Parameters

  • path – The URL path of the parent page (for example, /en/).
  • (Optional) options*
    • host – The host URL for filtering.
    • locales – Array of locale codes to filter by.

Returns

An array of child page metadata objects. Returns null if the parent page does not exist.

Example: Build navigation

Use getPath() and getItems() together to build breadcrumbs and a primary navigation menu.

import { GraphClient } from '@optimizely/cms-sdk';

const client = new GraphClient(process.env.OPTIMIZELY_GRAPH_SINGLE_KEY!);

export default async function Navigation() {
  // Get all direct children of the start page
  const navLinks = (await client.getItems('/en/')) ?? [];

  // Create navigation from child pages
  const navigations = navLinks.map((item: any) => ({
    key: item._metadata.key,
    label: item._metadata.displayName,
    href: item._metadata.url.hierarchical,
  }));

  return (
    <nav>
      <ul>
        {navigations.map((nav) => (
          <li key={nav.key}>
            <a href={nav.href}>{nav.label}</a>
          </li>
        ))}
      </ul>
    </nav>
  );
}

Combined example: Full navigation

The following is a complete example that uses both functions to build breadcrumbs and primary navigation:

import { GraphClient } from '@optimizely/cms-sdk';

const client = new GraphClient(process.env.OPTIMIZELY_GRAPH_SINGLE_KEY!);

export default async function Layout({ currentPath }: { currentPath: string }) {
  // Get ancestors for breadcrumbs
  const ancestors = (await client.getPath(currentPath)) || [];
  const breadcrumbs = ancestors.slice(1).map((ancestor: any) => ({
    key: ancestor._metadata.key,
    label: ancestor._metadata.displayName,
    href: ancestor._metadata.url.hierarchical,
  }));

  // Get main navigation items
  const navLinks = (await client.getItems('/en/')) ?? [];
  const navigations = navLinks.map((item: any) => ({
    key: item._metadata.key,
    label: item._metadata.displayName,
    href: item._metadata.url.hierarchical,
  }));

  return (
    <div>
      {/* Primary Navigation */}
      <nav aria-label="Main Navigation">
        <ul>
          {navigations.map((nav) => (
            <li key={nav.key}>
              <a href={nav.href}>{nav.label}</a>
            </li>
          ))}
        </ul>
      </nav>

      {/* Breadcrumbs */}
      <nav aria-label="Breadcrumb">
        <ol>
          {breadcrumbs.map((crumb) => (
            <li key={crumb.key}>
              <a href={crumb.href}>{crumb.label}</a>
            </li>
          ))}
        </ol>
      </nav>
    </div>
  );
}

Filtering by locale

Both functions support filtering by locale, which is useful for multi-language sites:

// Get navigation items only in English and French
const navLinks = await client.getItems('/en/', {
  locales: ['en', 'fr'],
});

// Get breadcrumbs filtered by locale
const ancestors = await client.getPath('/en/about/team', {
  locales: ['en'],
});

Error handling

Both functions return null if the requested page doesn't exist:

const ancestors = await client.getPath('/non-existent-page');

if (ancestors === null) {
  // Page doesn't exist, handle accordingly
  return <div>Page not found</div>;
}

// Safe to use ancestors
const breadcrumbs = ancestors.map(/* ... */);

Updated 1 day ago