Connect your website

De CMS-API laat je website gepubliceerde content ophalen en renderen vanuit Profound CMS. Je kunt deze gebruiken om documentatiepagina's, marketingpagina's, blogs, helpcentra of elke andere contentgerichte ervaring aan te sturen.

De typische integratie bestaat uit drie onderdelen:

1. Configureer je CMS-verbinding
2. Haal gepubliceerde content op
3. Render de content in je applicatie

Configuratie

Om je applicatie met het CMS te verbinden, geef je de URL van je CMS-API, de website-ID en de API-sleutel op.

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

Gebruik omgevingsvariabelen voor waarden die tussen omgevingen verschillen:

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

Stel privé-API-sleutels niet bloot in client-side code. API-sleutels moeten worden gebruikt op je server, in je buildproces of in je backend-routes.

Content ophalen

Content in het CMS is georganiseerd per schema. Je project kan bijvoorbeeld schema's hebben zoals post, category, page of section.

Gebruik de schemanaam om content op te halen:

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

Om een enkel document op ID op te halen:

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

Om gelokaliseerde content op te halen, vraag je de vertaalde versie van het schema op:

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

Routes renderen

Voor websites die CMS-beheerde pagina's gebruiken, kun je content ophalen op basis van het huidige URL-pad.

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

Het routeantwoord identificeert de pagina en de blokken die moeten worden gerenderd. Je applicatie kan vervolgens de blokken ophalen en ze renderen met je eigen componenten.

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

Voorbeeld: een documentatiepagina renderen

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

Je kunt de geretourneerde blokken gebruiken om de pagina te renderen met het componentensysteem van je applicatie.

Caching

Gepubliceerde CMS-content kan veilig worden gecachet. Voor de meeste websites cache je API-responses voor een korte periode en valideer je ze opnieuw wanneer content verandert.

Een gebruikelijke setup is:

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

Aanbevolen cachegedrag:

• Cache gepubliceerde leesacties.
• Gebruik kortere cachevensters voor content die vaak wordt bijgewerkt.
• Gebruik cache-tags als je framework on-demand invalidatie ondersteunt.
• Vermijd het cachen van preview- of conceptcontent.

Preview-modus

Met preview-modus kunnen redacteuren ongepubliceerde wijzigingen bekijken voordat ze worden gepubliceerd.

Een veelgebruikt patroon is om een aparte preview-route te gebruiken, bijvoorbeeld:

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

Productiepagina's moeten alleen gepubliceerde content ophalen. Previewpagina's kunnen preview-parameters accepteren, zoals:

?edit_mode=true

Preview-routes moeten meestal dynamisch zijn en niet statisch worden gecachet.

Foutafhandeling

CMS-content kan tijdens een build of request niet beschikbaar zijn. Je applicatie moet hier op een nette manier mee omgaan.

Aanbevolen gedrag:

• Retourneer 404 wanneer een route niet bestaat.
• Retourneer een lege lijst wanneer optionele navigatiecontent niet kan worden geladen.
• Log fetchfouten aan de serverzijde.
• Voorkom dat interne API-fouten aan bezoekers worden blootgesteld.

Voorbeeld:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Ophalen van CMS-bericht mislukt', error);
    return null;
  }
}

Beveiliging

Houd API-sleutels privé en gebruik ze alleen op de server. Neem geen privé-credentials op in browserbundels of publieke JavaScript.

Gebruik openbare omgevingsvariabelen alleen voor niet-gevoelige waarden zoals:

• Openbare CMS-URL
• Website-ID
• Configuratie van de landinstelling

Gebruik privé-omgevingsvariabelen voor:

• API-sleutels
• previewtokens
• beheerdersgegevens
• implementatiegeheimen

Samenvatting

Gebruik de CMS-API wanneer je website gestructureerde content moet ophalen, CMS-beheerde routes moet renderen of preview-workflows voor redacteuren moet ondersteunen.

Een standaardintegratie moet:

• De CMS-URL, website-ID en API-sleutel configureren.
• Documenten per schema ophalen.
• Pagina's ophalen op basis van het routepad.
• CMS-blokken renderen met je eigen componenten.
• Gepubliceerde content cachen.
• Previewcontent dynamisch houden.
• Privé-credentials op de server houden.