Povezivanje web-stranice s CMS API-jem

CMS API omogućuje vašoj web-stranici dohvat i prikaz objavljenog sadržaja iz Profound CMS-a. Možete ga koristiti za pogon stranica s dokumentacijom, marketinških stranica, blogova, centara za pomoć ili bilo kojeg drugog sadržajno vođenog iskustva.

Uobičajena integracija sastoji se od tri dijela:

1. Konfigurirajte svoju vezu s CMS-om
2. Dohvatite objavljeni sadržaj
3. Prikažite sadržaj u svojoj aplikaciji

Konfiguracija

Kako biste povezali svoju aplikaciju s CMS-om, navedite URL CMS API-ja, ID web-stranice i API ključ.

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

Koristite varijable okruženja za vrijednosti koje se mijenjaju između okruženja:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=vas-id-web-stranice
PROFOUND_API_KEY=vas-api-kljuc

Nemojte izlagati privatne API ključeve u kodu na strani klijenta. API ključeve koristite na poslužitelju, u procesu izgradnje ili u vašim pozadinskim rutama.

Dohvat sadržaja

Sadržaj u CMS-u organiziran je prema shemama. Na primjer, vaš projekt može imati sheme poput post, category, page ili section.

Upotrijebite naziv sheme za dohvat sadržaja:

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

Za dohvat pojedinačnog dokumenta putem ID-ja:

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

Za dohvat lokaliziranog sadržaja zatražite prevedenu verziju sheme:

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

Renderiranje ruta

Za web-stranice koje koriste stranice kojima upravlja CMS, sadržaj možete dohvatiti na temelju trenutačne putanje URL-a.

const route = await cms.route.getByPath({
  websiteId: 'vas-id-web-stranice',
  path: '/docs/prvi-koraci',
});

Odgovor rute identificira stranicu i blokove koje treba prikazati. Vaša aplikacija zatim može dohvatiti blokove i prikazati ih pomoću vlastitih komponenti.

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

Primjer: prikaz stranice dokumentacije

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,
  };
}

Vraćene blokove možete upotrijebiti za prikaz stranice koristeći sustav komponenti vaše aplikacije.

Predmemoriranje

Objavljeni CMS sadržaj sigurno je spremiti u predmemoriju. Za većinu web-stranica predmemorirajte odgovore API-ja na kratko razdoblje i ponovno ih provjerite kada se sadržaj promijeni.

Uobičajena postavka izgleda ovako:

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

Preporučeno ponašanje predmemorije:

• Predmemorirajte objavljene podatke.
• Koristite kraće vremenske okvire predmemorije za sadržaj koji se često ažurira.
• Koristite oznake predmemorije ako vaš okvir podržava poništavanje na zahtjev.
• Izbjegavajte predmemoriranje preglednog ili skiciranog sadržaja.

Način pregleda

Način pregleda omogućuje urednicima da vide neobjavljene promjene prije nego što budu objavljene.

Uobičajen obrazac je uporaba zasebne rute za pregled, na primjer:

/docs/prvi-koraci
/cms-preview/docs/prvi-koraci

Proizvodne stranice trebale bi dohvaćati samo objavljeni sadržaj. Stranice za pregled mogu prihvatiti parametre pregleda, poput:

?edit_mode=true

Rute za pregled obično bi trebale biti dinamičke i ne bi smjele biti statički predmemorirane.

Rukovanje pogreškama

CMS sadržaj može biti nedostupan tijekom izrade ili zahtjeva. Vaša aplikacija to treba obraditi na odgovarajući način.

Preporučeno ponašanje:

• Vratite 404 kada ruta ne postoji.
• Vratite prazan popis kada se opcionalni navigacijski sadržaj ne može učitati.
• Zabilježite pogreške dohvaćanja na strani poslužitelja.
• Izbjegavajte izlaganje internih API pogrešaka posjetiteljima.

Primjer:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Nije uspjelo dohvaćanje CMS objave', error);
    return null;
  }
}

Sigurnost

Držite API ključeve privatnima i koristite ih samo na poslužitelju. Ne uključujte privatne vjerodajnice u pakete preglednika ili javni JavaScript.

Javne varijable okruženja koristite samo za neosjetljive vrijednosti, kao što su:

• Javni URL CMS-a
• ID web-stranice
• Konfiguracija lokalizacije

Privatne varijable okruženja koristite za:

• API ključeve
• tokene za pregled
• administratorske vjerodajnice
• tajne za implementaciju

Sažetak

Koristite CMS API kada vaša web-stranica treba dohvaćati strukturirani sadržaj, prikazivati rute pod upravljanjem CMS-a ili podržavati procese pregleda za urednike.

Standardna integracija trebala bi:

• Konfigurirati CMS URL, ID web-stranice i API ključ.
• Dohvaćati dokumente prema shemi.
• Dohvaćati stranice prema putanji rute.
• Prikazivati CMS blokove vašim vlastitim komponentama.
• Predmemorirati objavljeni sadržaj.
• Održavati pregledni sadržaj dinamičnim.
• Čuvati privatne vjerodajnice na poslužitelju.