Connect your website

Rozhranie CMS API umožňuje vašej webovej stránke načítať a vykresľovať publikovaný obsah z Profound CMS. Môžete ho použiť na pohon stránok s dokumentáciou, marketingových stránok, blogov, centier pomoci alebo akéhokoľvek iného zážitku založeného na obsahu.

Typická integrácia má tri časti:

1. Nakonfigurujte svoje pripojenie k CMS
2. Načítajte publikovaný obsah
3. Vykreslite obsah vo svojej aplikácii

Konfigurácia

Ak chcete svoju aplikáciu pripojiť k CMS, poskytnite URL adresu rozhrania API CMS, identifikátor webu a kľúč API.

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

Premenné prostredia používajte na hodnoty, ktoré sa líšia medzi prostrediami:

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

Nezverejňujte súkromné kľúče API v klientskej časti kódu. Kľúče API by sa mali používať na vašom serveri, v procese zostavovania alebo vo vašich backendových trasách.

Načítanie obsahu

Obsah v CMS je organizovaný podľa schém. Napríklad váš projekt môže obsahovať schémy ako post, category, page alebo section.

Na načítanie obsahu použite názov schémy:

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

Na načítanie jedného dokumentu podľa ID:

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

Ak chcete načítať lokalizovaný obsah, vyžiadajte si preloženú verziu schémy:

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

Vykresľovanie trás

Pre weby, ktoré používajú stránky spravované CMS, môžete načítať obsah na základe aktuálnej cesty URL.

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

Odpoveď trasy identifikuje stránku a bloky, ktoré treba vykresliť. Vaša aplikácia potom môže bloky načítať a vykresliť ich prostredníctvom vlastných komponentov.

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

Príklad: Vykreslenie stránky dokumentácie

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átené bloky môžete použiť na vykreslenie stránky pomocou komponentového systému vašej aplikácie.

Ukladanie do vyrovnávacej pamäte

Publikovaný obsah CMS je bezpečné ukladať do vyrovnávacej pamäte. Pre väčšinu webových stránok ukladajte odpovede API na krátky čas a revalidujte ich, keď sa obsah zmení.

Bežné nastavenie je:

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

Odporúčané správanie vyrovnávacej pamäte:

• Ukladajte do vyrovnávacej pamäte publikované čítania.
• Používajte kratšie intervaly vyrovnávacej pamäte pre často aktualizovaný obsah.
• Používajte značky vyrovnávacej pamäte, ak váš rámec podporuje invalidáciu na požiadanie.
• Vyhnite sa ukladaniu náhľadového alebo konceptného obsahu do vyrovnávacej pamäte.

Režim náhľadu

Režim náhľadu umožňuje editorom pozrieť si nepublikované zmeny ešte pred ich zverejnením.

Bežným vzorom je použitie samostatnej náhľadovej trasy, napríklad:

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

Produkčné stránky by mali načítavať iba publikovaný obsah. Stránky náhľadu môžu prijímať náhľadové parametre, napríklad:

?edit_mode=true

Trasy náhľadu by mali byť zvyčajne dynamické a nemali by sa staticky ukladať do vyrovnávacej pamäte.

Spracovanie chýb

Obsah CMS môže byť počas zostavovania alebo požiadavky nedostupný. Vaša aplikácia by to mala zvládnuť elegantne.

Odporúčané správanie:

• Vráťte 404, keď trasa neexistuje.
• Vráťte prázdny zoznam, keď sa nepodarí načítať voliteľný navigačný obsah.
• Zaznamenávajte chyby načítania na strane servera.
• Nezobrazujte návštevníkom interné chyby API.

Prí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čenie

Udržujte kľúče API v súkromí a používajte ich iba na serveri. Nezahrňujte súkromné poverenia do balíkov prehliadača ani do verejného JavaScriptu.

Verejné premenné prostredia používajte iba pre necitlivé hodnoty, ako napríklad:

• Verejná adresa URL CMS
• Identifikátor webu
• Konfigurácia lokalizácie

Súkromné premenné prostredia používajte pre:

• Kľúče API
• Náhľadové tokeny
• Administrátorské poverenia
• Nasadzovacie tajomstvá

Zhrnutie

Použite rozhranie CMS API, keď vaša webová stránka potrebuje načítať štruktúrovaný obsah, vykresľovať trasy spravované CMS alebo podporovať pracovné postupy náhľadov editorov.

Štandardná integrácia by mala:

• Nakonfigurovať adresu URL CMS, identifikátor webu a kľúč API.
• Načítavať dokumenty podľa schémy.
• Načítavať stránky podľa cesty trasy.
• Vykresľovať bloky CMS pomocou vlastných komponentov.
• Ukladať publikovaný obsah do vyrovnávacej pamäte.
• Ponechať náhľadový obsah dynamický.
• Ponechať súkromné poverenia na serveri.