Prijunkite svetainę prie CMS API

CMS API leidžia jūsų svetainei gauti ir atvaizduoti publikuotą turinį iš „Profound CMS“. Ją galite naudoti dokumentacijos puslapiams, rinkodaros puslapiams, tinklaraščiams, pagalbos centrams ar bet kokiai kitai turiniu pagrįstai patirčiai.

Tipinė integracija turi tris dalis:

1. Sukonfigūruokite savo CMS ryšį
2. Gaukite publikuotą turinį
3. Atvaizduokite turinį savo programoje

Konfigūracija

Norėdami prijungti savo programą prie CMS, pateikite savo CMS API URL, svetainės ID ir API raktą.

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

Naudokite aplinkos kintamuosius reikšmėms, kurios skiriasi tarp aplinkų:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=jusu-svetaines-id
PROFOUND_API_KEY=jusu-api-raktas

Neleiskite, kad privatūs API raktai būtų matomi kliento pusės kode. API raktus naudokite savo serveryje, komponavimo procese arba galiniuose maršrutuose.

Turinio gavimas

CMS turinys organizuojamas pagal schemas. Pavyzdžiui, jūsų projekte gali būti tokios schemos kaip post, category, page ar section.

Naudokite schemos pavadinimą turiniui gauti:

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

Norėdami gauti vieną dokumentą pagal ID:

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

Norėdami gauti lokalizuotą turinį, užklauskite išverstos schemos versijos:

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

Maršrutų atvaizdavimas

Svetainėms, kurios naudoja CMS valdomus puslapius, galite gauti turinį pagal esamą URL kelią.

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

Maršruto atsakymas identifikuoja puslapį ir blokus, kuriuos reikia atvaizduoti. Tuomet jūsų programa gali gauti blokus ir atvaizduoti juos naudodama jūsų komponentus.

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

Pavyzdys: atvaizduokite dokumentacijos puslapį

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

Galite naudoti grąžintus blokus puslapiui atvaizduoti naudodami savo programos komponentų sistemą.

Podėliavimas

Publikuotą CMS turinį saugu talpinti podėlyje. Daugumai svetainių talpinkite API atsakymus trumpam laikui ir pervaliduokite juos, kai turinys pasikeičia.

Įprasta sąranka:

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

Rekomenduojamas podėlio elgesys:

• Talpinkite publikuotus nuskaitymus.
• Dažnai atnaujinamam turiniui naudokite trumpesnius podėlio langus.
• Naudokite podėlio žymas, jei jūsų karkasas palaiko užsakytą invalidaciją.
• Venkite talpinti peržiūros ar juodraštinį turinį.

Peržiūros režimas

Peržiūros režimas leidžia redaktoriams matyti nepublikuotus pakeitimus prieš juos publikuojant.

Įprasta schema – naudoti atskirą peržiūros maršrutą, pavyzdžiui:

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

Produkciniai puslapiai turėtų gauti tik publikuotą turinį. Peržiūros puslapiai gali priimti peržiūros parametrus, tokius kaip:

?edit_mode=true

Peržiūros maršrutai paprastai turėtų būti dinamiški ir neturėtų būti statiniu būdu talpinami podėlyje.

Klaidos tvarkymas

CMS turinys gali būti nepasiekiamas komponavimo ar užklausos metu. Jūsų programa turėtų tai tvarkyti grakščiai.

Rekomenduojama:

• Grąžinti 404, kai maršrutas neegzistuoja.
• Grąžinti tuščią sąrašą, kai pasirenkamo navigacijos turinio nepavyksta įkelti.
• Registruoti serverio pusės gavimo klaidas žurnale.
• Vengti lankytojams rodyti vidines API klaidas.

Pavyzdys:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Nepavyko gauti CMS įrašo', error);
    return null;
  }
}

Saugumas

Laikykite API raktus privačius ir naudokite juos tik serveryje. Neįtraukite privačių kredencialų į naršyklės paketus ar viešą „JavaScript“.

Viešus aplinkos kintamuosius naudokite tik nejautrioms reikšmėms, tokioms kaip:

• Viešas CMS URL
• Svetainės ID
• Lokalės konfigūracija

Privačius aplinkos kintamuosius naudokite:

• API raktams
• peržiūros žetonams
• administratoriaus kredencialams
• diegimo paslaptims

Santrauka

Naudokite CMS API, kai jūsų svetainei reikia gauti struktūruotą turinį, atvaizduoti CMS valdomus maršrutus ar palaikyti redaktorių peržiūros darbo sekas.

Standartinė integracija turėtų:

• Sukonfigūruoti CMS URL, svetainės ID ir API raktą.
• Gauti dokumentus pagal schemą.
• Gauti puslapius pagal maršruto kelią.
• Atvaizduoti CMS blokus naudojant savo komponentus.
• Talpinti publikuotą turinį podėlyje.
• Laikyti peržiūros turinį dinamišką.
• Laikyti privačius kredencialus serveryje.