Page Mapper

Page Mapper gives a page a slug that is independent of the page value. The slug is the route of the page on the storefront. One page value can then serve more than one route, and a merchant can change a route without a change to the page itself.

warning

Page Mapper activation is permanent. You cannot switch the feature off after activation. Read this page and test the theme in a sandbox before you enable it.

Prerequisites

The router change below is the only requirement to use slugs. A slug whose predicate matches every visitor resolves without any request context.

Request context becomes necessary only when a slug uses a predicate that depends on it. Forward the value that the predicate reads:

Predicate on the slug	Value the theme must forward
guest or registered user type	The login state of the user
user_group	The user groups
A platform, such as web, ios, or android	The user agent
A feature store	The store context
A schedule	Nothing. The platform evaluates the time.

If a slug uses only an all-user, all-platform predicate, none of these apply.

Read Request Context for how to forward each value. A predicate that cannot read its value does not fail the request. It stops matching, so the visitor receives the fallback page instead of the variant you expected.

What changes

Without Page Mapper, the router compares the route with the page value. With Page Mapper, the router must compare the route with the page slug. A theme that still compares the value does not detect a route change, and the page does not reload its data.

Helper function

Add this helper to the utilities of the theme. The helper returns the value that the router must compare.

export function getPageValue(page) {
  const typeOfPage = page?.type;
  switch (typeOfPage) {
    case "sections":
      return page?.slug?.includes("sections/")
        ? page?.slug?.split("/")[1]
        : "home";
    case "system":
      return page?.value;
    case "custom":
      return page?.value;
    default:
      return page?.value;
  }
}

A section page carries its slug in the form sections/<name>. The helper returns <name>. A page without that prefix is the home page.

Changes in lib.js

import { getPageValue } from "./utils"; // Adjust the import path
import { getPageSlug } from "fdk-core/utils";

export async function pageDataResolver(pageResolverData) {
  const { fpi, router, themeId, cookies, headers, query } = pageResolverData;

  const state = fpi.store.getState();
  const pageValue = getPageSlug(router);

  // Compare against the slug of the page in the store
  const currentPageInStore = getPageValue(fpi.getters.PAGE(state));

  const company = fpi.getters.THEME(state)?.company_id;
  const requestHeaders = {};

  if (pageValue && pageValue !== currentPageInStore) {
    const params = {
      pageValue,
      themeId,
      requestHeaders,
      company,
    };

    APIs.push(fpi.theme.getPage(params));
  }

  return await Promise.all(APIs).catch(console.log);
}

getPageSlug comes from fdk-core/utils. The function reads the slug from the router.

The name of the page method depends on the FDK Store version. Some versions name it getPage, and some versions name it fetchPage. Confirm the name for the version that your theme installs.

Verification

1. Give a page a slug that is different from its value.
2. Open the slug route. Confirm that the correct page renders.
3. Move between two routes that share one page value. Confirm that the data reloads.
4. Confirm that a system page and a custom page still render.