Připojení webu k API CMS

Rozhraní CMS API umožňuje vašemu webu načítat a vykreslovat publikovaný obsah z Profound CMS. Můžete jej využít pro dokumentační stránky, marketingové stránky, blogy, centra nápovědy nebo jakýkoli jiný obsahově řízený zážitek.

Typické napojení se skládá ze tří částí:

1. Nakonfigurujte připojení k CMS
2. Načtěte publikovaný obsah
3. Vykreslete obsah ve své aplikaci

Konfigurace

Chcete-li svou aplikaci připojit k CMS, zadejte URL adresu CMS API, ID webu a klíč API.

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

Pro hodnoty, které se liší mezi prostředími, použijte proměnné prostředí:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

Nezveřejňujte soukromé klíče API v kódu na straně klienta. Klíče API by měly být používány na vašem serveru, v procesu sestavení nebo v backendových routách.

Načítání obsahu

Obsah v CMS je organizován podle schémat. Například váš projekt může mít schémata jako post, category, page nebo section.

K načtení obsahu použijte název schématu:

const posts = await cms.schema('post').fetchAll();

Chcete-li načíst jeden dokument podle ID:

const post = await cms.schema('post').fetchSingleById('document-id');

Chcete-li načíst lokalizovaný obsah, vyžádejte si přeloženou verzi schématu:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

Vykreslování rout

U webů, které používají stránky spravované CMS, můžete načítat obsah na základě aktuální cesty URL.

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

Odpověď routy určí stránku a bloky k vykreslení. Vaše aplikace pak může bloky načíst a vykreslit je pomocí vlastních komponent.

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

Příklad: Vykreslení dokumentační stránky

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

Vrácené bloky můžete použít k vykreslení stránky pomocí komponentového systému vaší aplikace.

Ukládání do mezipaměti

Publikovaný obsah CMS je bezpečné ukládat do mezipaměti. U většiny webů ukládejte odpovědi API na krátkou dobu a znovu je validujte, když se obsah změní.

Běžné nastavení je:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

Doporučené chování mezipaměti:

• Ukládejte publikovaná čtení do mezipaměti.
• Pro často aktualizovaný obsah používejte kratší dobu mezipaměti.
• Používejte značky mezipaměti, pokud váš framework podporuje invalidaci na vyžádání.
• Vyhněte se ukládání náhledů nebo konceptů do mezipaměti.

Režim náhledu

Režim náhledu umožňuje editorům zobrazit si nepublikované změny ještě před jejich zveřejněním.

Častým vzorem je použití samostatné náhledové routy, například:

/docs/getting-started
/cms-preview/docs/getting-started

Produkční stránky by měly načítat pouze publikovaný obsah. Náhledové stránky mohou přijímat náhledové parametry, například:

?edit_mode=true

Náhledové routy by obvykle měly být dynamické a neměly by se staticky ukládat do mezipaměti.

Zpracování chyb

Obsah CMS může být během sestavení nebo požadavku nedostupný. Vaše aplikace by s tím měla umět pracovat elegantně.

Doporučené chování:

• Vracejte 404, pokud daná routa neexistuje.
• Vraťte prázdný seznam, když se nepodaří načíst volitelný navigační obsah.
• Logujte chyby při načítání na straně serveru.
• Neukazujte návštěvníkům interní chyby API.

Příklad:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Failed to fetch CMS post', error);
    return null;
  }
}

Zabezpečení

Udržujte klíče API v soukromí a používejte je pouze na serveru. Nezahrnujte soukromé přihlašovací údaje do balíčků prohlížeče ani do veřejného JavaScriptu.

Veřejné proměnné prostředí používejte pouze pro necitlivé hodnoty, například:

• Veřejná URL adresa CMS
• ID webu
• Nastavení lokalizací

Soukromé proměnné prostředí používejte pro:

• Klíče API
• tokeny pro náhled
• přihlašovací údaje administrátorů
• tajné údaje k nasazení

Shrnutí

Rozhraní CMS API použijte, když váš web potřebuje načítat strukturovaný obsah, vykreslovat routy spravované CMS nebo podporovat pracovní postupy náhledu pro editory.

Standardní integrace by měla:

• Nakonfigurovat URL CMS, ID webu a klíč API.
• Načítat dokumenty podle schématu.
• Načítat stránky podle cesty routy.
• Vykreslovat bloky CMS pomocí vlastních komponent.
• Ukládat publikovaný obsah do mezipaměti.
• Zachovat náhledový obsah dynamický.
• Uchovávat soukromé přihlašovací údaje na serveru.