usePage

This hook fetches and returns CMS page data for a given set of options. It is built on top of Archibald's useFetch hook, which provides caching, server-side rendering hydration, and request state management.

Usage

import { usePage } from '@archibald/cms';

const { data, isLoading, isError } = usePage({ pageLabelOrId: 'homepage' });

Parameters

• cmsOptions (object): The primary way to request a page.
  • pageLabelOrId (string): The label or ID of the page.
  • pageType (string): The type of the page.
  • code (string): The code for a specific version of a page (e.g., a specific product ID for a product page).
  • fields (string): Defines the response fields (e.g., 'DEFAULT', 'FULL').
  • resolveNested (boolean): Whether the provider should resolve nested CMS data.
• key (string, optional): Overwrites the internal useFetch key. A key is automatically generated from pageLabelOrId, pageType, and code if not provided.
• fetchOptions (object, optional): Options for the underlying useFetch hook. See useFetch's options for more details.

Return Value

An object containing standard useFetch properties:

• data: The CMS page data.
• isLoading, isError, isSuccess, isStale, etc. (standard useFetch state).
• mutate: A function to manually trigger a refetch of the data.

---

Deep Dive

Description: usePage is the primary hook for fetching all CMS content required to render a page. It uniquely identifies a page request based on its options and leverages Archibald's useFetch hook to provide robust data fetching and caching capabilities.

• How To: Combine different cmsOptions to fetch the exact page you need. For example, to get a specific Product Detail Page (PDP), you would use the pageType and the product code.

  // Correct: Fetching a specific product page.
  import { usePage } from '@archibald/cms';
  
  function ProductPage({ productCode }) {
      const { data: pageData, isLoading } = usePage({
          pageType: 'ProductPage',
          code: productCode
      });
  
      // ... render page with pageData
  }

• Best Practice: Ensure the cache key for usePage (which is derived from cmsOptions or explicitly passed) remains stable between renders. If the key is constantly changing, useFetch will treat it as a new query and initiate a fetch on every render.

  // Avoid: Passing a dynamically generated key that changes on every render.
  function MyPage() {
      // This key changes on every render, causing `usePage` to re-fetch constantly.
      const unstableKey = `page-data-${Math.random()}`;
      
      const { data } = usePage(
          { pageLabelOrId: 'some-page' },
          unstableKey // Don't do this!
      );
      // ...
  }

  // Correct: Ensure the key is stable.
  import { useParams } from 'react-router-dom'; // Example for dynamic routing
  
  function ProductPage() {
      const { productId } = useParams();
      
      // The key is stable because productId is stable.
      const stableKey = `product-page-${productId}`; 
      
      const { data } = usePage(
          { pageType: 'ProductPage', code: productId },
          stableKey // This is fine.
      );
      // ...
  }