Skip to main content

Hooks and Utilities

The Theme Rendering engine simplifies building responsive, state-driven, and interactive React themes by offering hooks and helper functions from fdk-core/utils. These utilities enable theme developers to interact with the Redux store, access client information, and handle URL conversions.

Below you'll find a list of hooks and utils:

  1. useFPI
  2. useGlobalStore
  3. useClientInfo
  4. getPageSlug
  5. convertActionToUrl
  6. convertUrlToAction

1. useFPI​

Access the FPI client instance on any page. Use this hook to fetch data, dispatch actions, and interact with the Redux store.

Example​

The example below shows that the Home component retrieves the FPI instance with useFPI() and can use it to perform tasks such as fetching page data or calling platform APIs. It simply renders a placeholder, but this is where you would use the fpi object for your application's logic.

import React from 'react';
import { useFPI } from 'fdk-core/utils';

function Home() {
  // Get the FPI instance using the useFPI hook
  const fpi = useFPI();
  // Add your component's logic here using the fpi instance
  return (
    <p>Home Component</p>
  );
}

2. useGlobalStore​

Subscribe to a specific slice of the Redux store. This hook extends React-Redux's useSelector and is compatible with all getters available in fpi.getters.

Example​

The example code shows how to access specific slices of the Redux store within your React component using the theme engine's hooks. By leveraging useFPI, you obtain an FPI instance that provides you access to defined getters for storing data. Then, with useGlobalStore, you can subscribe to particular data from the store (for example, the current page data) and have your component automatically re-render when this slice of the state changes. This approach allows you to build reactive, state-driven UI components that always show the most up-to-date information from the platform.
If your application's global page data changes due to navigation or an action, your component will receive the new data and update itself accordingly, without you having to manage listeners or subscriptions manually.

import { useGlobalStore, useFPI } from 'fdk-core/utils';

function Home() {
  // Get the FPI instance
  const fpi = useFPI();
  // Subscribe to PAGE data from the global store
  const page = useGlobalStore(fpi.getters.PAGE) || {};

  // You can use `page` to render dynamic content based on the current global state
  return (
    <p>Home Component</p>
  );
}

3. useClientInfo​

Access client-specific information (themeCookie and userAgent) throughout your React theme without prop drilling. Works seamlessly in both client-side and server-side rendering (SSR).

Return Values​

  • themeCookie: User's preferred theme stored in browser cookie (for example, light or dark)
  • userAgent: Browser, device, and OS information from request headers

Example​

Imagine a user who has chosen a dark theme preference and is browsing your site on a mobile device. With useClientInfo, your component can seamlessly detect these details and instantly reflect them in the UI—rendering with dark theme styling and dynamically showing the user's device information—all without the need for manual prop drilling or setting up additional React contexts.

In the following example, a functional React component leverages useClientInfo to extract both the user's theme preference and user agent. The appropriate theme class is applied ensuring consistent styling that matches the user's chosen theme.

import { useClientInfo } from "fdk-core/utils";

const MyComponent = () => {
  const { userAgent, themeCookie } = useClientInfo();
  const themeClass = themeCookie === "dark" ? "dark-theme" : "light-theme";
  return (
    <div className={themeClass}>
      <p>Welcome! Your user agent is: {userAgent}</p>
    </div>
  );
};

4. getPageSlug​

Extracts the page slug from the router object for the current route. Use this to fetch page-specific data from APIs or determine which page is being rendered.

Use Cases​

  • Fetch page data based on the current route in data resolvers
  • Conditionally load content based on page type
  • Track page views or analytics
  • Implement page-specific logic

Example​

The example below shows how to extract a unique identifier (called a "page slug") from the router object, which represents the current route or page being viewed. By comparing this value with what’s already stored in the theme’s Redux store, the app determines if a new page needs to be fetched from the backend. If the page slug has changed—meaning the user is requesting a new or different page—it triggers a call to the platform API to load the new page data for that route. In this way, the mechanism ensures that the application remains up-to-date, loading fresh data only when necessary, and avoids redundant fetches for the same page.

import { getPageSlug } from "fdk-core/utils";

export async function pageDataResolver({ fpi, router, themeId }) {
  const state = fpi.store.getState();
  const pageValue = getPageSlug(router);
  const APIs = [];
  const currentPageInStore = state?.theme?.page?.value ?? null;

  // Only fetch if page changed
  if (pageValue !== currentPageInStore) {
    APIs.push(
      fpi.theme.fetchPage({
        pageValue,
        themeId,
      })
    );
  }
  
  return Promise.all(APIs).catch(console.log);
}

5. convertActionToUrl(action)​

Converts an action object into a URL string. Useful for generating navigation links from action objects stored in CMS or configuration.

Example​

The code below shows how to use the convertActionToUrl utility function. This function transforms navigation action objects—such as those typically stored in content management systems or theme configuration—into actual URL strings for navigation in your application. It supports a variety of use cases: generating URLs for internal pages, handling query parameters, handling external URLs, and even producing localized URLs by including a locale prefix when needed.

import { convertActionToUrl } from "fdk-core/utils";

// Internal page URL
const action = {
    "type": "page",
    "page": {
        "type": "locate-us"
    }
};
convertActionToUrl(action); // "/locate-us"

// Internal page with query parameters
const action = {
    "type": "page",
    "page": {
        "type": "products",
        "query": {
            "department": ["men", "women"]
        }
    }
};
convertActionToUrl(action); // "/products/?department=men&department=women"

// External URL
const action = {
    "type": "page",
    "page": {
        "type": "external",
        "query": {
            "url": ["https://www.example.com/external-page"]
        }
    }
};
convertActionToUrl(action); // "/external/?url=https%3A%2F%2Fwww.example.com%2Fexternal-page"

// With locale (optional)
convertActionToUrl(action, "en"); // "/en/locate-us"

6. convertUrlToAction(url)​

Converts a URL string into an action object representing the page type and parameters. Automatically parses query parameters and extracts slugs from the URL path.

Example​

import { convertUrlToAction } from "fdk-core/utils";

// Internal page URL
const url = "/locate-us";
const action = convertUrlToAction(url);
console.log(action);
/* Output:
{
    "type": "page",
    "page": {
        "type": "locate-us"
    }
}
*/

// Internal page with query parameters
const url = "/products/?department=men&department=women";
const action = convertUrlToAction(url);
console.log(action);
/* Output:
{
    "type": "page",
    "page": {
        "type": "products",
        "query": {
            "department": ["men", "women"]
        }
    }
}
*/

// External URL
const url = "https://www.example.com/external-page";
const action = convertUrlToAction(url);
console.log(action);
/* Output:
{
    "type": "page",
    "page": {
        "type": "external",
        "query": {
            "url": ["https://www.example.com/external-page"]
        }
    }
}
*/