1. Wat is een headless wordpress website
  2. Waarom een headless wordpress website bouwen
  3. Setup backend voort een headless wp installatie
  4. WordPress thema maken
  5. Werken met de WP REST API
  6. SEO voor headless wordpress
  7. Custom hooks
  8. Werken met contact formulieren

Wat is een headless WordPress website?

Een headless WordPress website is WordPress site waarbij we alleen de backend van WordPress gebruiken voor content management maar geen WordPress thema gebruiken voor het front-end gedeelte. In plaats daarvan bouwen we apart van de WordPress omgeving de front-end in bijvoorbeeld javascript framework en halen die content op via de WP REST API.

Als je niet weet hoe je met deze technologieën om moet gaan is het verstandig een front-end web developer in te huren of een normale WordPress website te bouwen.

Waarom een headless wordpress website bouwen?

Front-end JS frameworks zoals ReactJS, VueJS en Angular zijn geweldige stukken software om custom build websites en webapplicaties in te bouwen zonder de restricties die met WordPress komen. Echter als je een backend wilt hebben voor content management moet je die zelf bouwen wat een hoop tijd kost. Waarom het wiel 2x uitvinden als er een geweldig blog systeem bestaat wat je kosteloos kunt gebruiken.

Vaak is het zo dat een webapplicatie hebt waaraan je een blog functionaliteit aan wilt toevoegen. Nu kun je een paar dingen doen:

  1. Geheel zelf bouwen inclusief heb backend gedeelte
  2. Een aparte website op een subdomein installeren
  3. Een blog in het front-end maken en de data via een API van een extern systeem ophalen

De headless WordPress site doet natuurlijk het laatste. Waarbij we op een subdomein de WP installatie maken die niet openbaar toegankelijk is en hier nieuwe content maken, afbeeldingen beheren en het beheren van reacties onder de artikelen terwijl de voorkant van de website de bestaande webapplicatie is of de custom build website is.

Setup van een headless WP website

We moeten hier twee dingen doen:

  • De backend installeren
  • Het front-end installeren

Voor het front-end gebruik je hiervoor je favoriete framework of library. Als je een JS framework gebruikt is het voor SEO echter belangrijk eraan te denken dat je dit met Server Side Rendering opzet of met static site generation. Ik zal hier verder niet op ingaan maar je kunt het beste met NextJS of NuxtJS werken ipv React of Vue.

Voor de backend installeer je een gewone WordPress installatie zoals je anders ook zou doen. Installeer deze op een subdomein. Bijvoorbeeld wp.jedomeinnaam.nl. We zullen nog steeds een thema moeten gebruiken en voor nu is het standaard thema goed. We gaan zo meteen een nieuw thema maken.

We willen uiteindelijk niet dat Google de backend gaat indexeren. Zet in ieder geval de gehele website op noindex.

SSL Issue

Wat hebben nu een keus wat te doen als nieuwsgierige mensen je subdomein intypen waar de WP omgeving opstaat. Ik wil dat mensen dan het liefste geredirect worden naar de homepage van mijn hoofdwebsite. We kunnen echter ook een blanco pagina tonen. In het eerste geval gaan we mogelijk tegen SSL issues aanlopen bij het vernieuwen van het certificaat.

Als de site geïnstalleerd is op een subdomein kunnen we dit oplossen door op de hoofdwebsite een wildcard ssl certificaat te installeren. Een ander alternatief is een blanco pagina tonen die in ieder geval als noindex is ingesteld.

WP Thema maken

Omdat WordPress een thema nodig heeft en we niet het standaard thema willen gebruiken maken we er zelf een. Hier gaan we heel weinig inzetten. Dit bestaat uit een blanco index.php. Een style.css waar geen css in staat maar alleen de registratie van het thema en een functions.php bestand. Hierin kunnen we eventuele custom functies zetten die je ook in een normaal thema vindt zoals registratie van menu’s, widgets e.d. Maar ook custom code zoals custom hooks.

Download hier een standaard thema voor een headless wp installatie

In het bijgevoegde thema heb ik een 301 redirect geplaatst in het index.php bestand. Maar ik vond het zo wel makkelijker zonder workarounds. Dit zou ook kunnen met een htaccess bestand. Hou dan wel rekening dat /wp-admin wel bereikbaar blijft.

Werken met de WP REST API

Voor het werken met de rest api en de juiste endpoints verwijs ik naar de officiële WordPress REST API documentatie en RTFM

In je front-end applicatie wil je deze url als constante opslaan: https://wp.jedomeinnaam.nl/wp-json/wp/v2/ Voor de rest gebruik je de endpoints uit de documentatie.

Je komt er waarschijnlijk snel achter dat er wat zaken die je wellicht wel wilt hebben niet standaard in de api zitten. Denk hierbij aan auteursinformatie bij een post, gedetailleerde info van uitgelichte afbeeldingen en informatie van categorieën. Standaard zie je alleen een ID en zul je een apart request moeten doen om die op te halen wat je site traag maakt.

Gelukkig zijn er plugins die veel van deze dingen standaard in de REST API kunnen toevoegen. In andere gevallen zul je zelf een custom hook moeten schrijven.

  • Better REST API Featured Images
  • REST API Helper
  • Nog diverse andere

Belangrijke beperkingen van de WP REST API

WordPress heeft een aantal belangrijke beperkingen die je normaal ook in de website hebt i.v.m. performance. De belangrijkste wil ik hier even uitlichten en dat is het maximale aantal results in een request. Dit is altijd maximaal 100 per pagina. Ook als wil je er graag 1000 hebben. Er wordt uitgegaan dat er met pagination wordt gewerkt en standaard krijg je wel variabele voor het totale aantal posts en op welke pagina van de paginatie je bent.

Meer informatie hoe WP omgaat met paginatie in de REST API vind je hier: https://developer.wordpress.org/rest-api/using-the-rest-api/pagination/

Relevante plugins voor een headless WP website

Naast plugins die de API manipuleren zijn een aantal standaard plugins ook best noodzakelijk. Denk aan SEO optimalisatie, afbeeldingen, Sercurity, API Caching, custom posts en eventueel het verwijderen van die vreselijke Gutenberg editor.

Kijk vooral ook naar deze plugins:

  • ACF + ACF REST API integration
  • Classic Editor
  • WP REST Cache

SEO voor headless WordPress websites

Het probleem bij headless wordress websites is dat die veelal in JS frameworks zijn gebouwd. Hier zit een groot SEO probleem in en dat is client site rendering. Standaard parsed de Google bot geen JS en ziet die een blanco site. Dat is niet goed voor indexering. Ik zal hier verder niet al te diep op ingaan maar je wilt zorgen voor server side redering. Bijvoorbeeld met gebruik van NextJS of NuxtJS. Voor SEO optimalisatie kun je een plugin als Yoast gebruiken om teksten te optimaliseren, maar je zult nog wel alle meta tags uit de API moeten halen en op de pagina tonen.

Custom hooks

Voor sommige zaken is het nodig om je eigen functies te schrijven. Denk bijvoorbeeld aan het samenvoegen van meerdere API requests in een groot request zodat je met een request alle informatie hebt of het verzenden van data naar de API waarnaar je er server side iets mee wilt doen.

Hiervoor maken we custom endpoints. Praktisch gezien is dit een API endpoint die een functie aanroept. We maken hiervoor een POST Request met bijvoorbeeld een aantal parameters die in de callback functie beschikbaar zullen zijn.

Ik zal hieronder een voorbeeld geven hoe dit te doen voor contactformulieren. Hetzelfde geldt bijvoorbeeld ook voor de reacties onder een artikel

Hoe werken met contactformulieren?

Voor dit artikel zal ik hier niet in detail op ingaan. Maar om emails te sturen moet je een custom endpoint maken die een functie aanroept waarin de wp_mail() functie wordt aangeroepen.

We maken ten eerste een custom endpoint:

function register_custom_rest_endpoint() { 
  register_rest_route('custom/v1', '/send-email', array( 'methods' => 'POST', 'callback' => 'send_email_callback', )); 
} 

add_action('rest_api_init', 'register_custom_rest_endpoint');

Dit luistert naar POST requests op /send-mail en roept een callback functie aan. In de callback functie roepen we de ingebouwde email functie aan.
Lees hier meer over de wp_mail() functie:

function send_email_callback($request) { 
  // Haal de gegevens op uit het verzoek 
  $to = $request->get_param('to'); 
  $subject = $request->get_param('subject'); 
  $message = $request->get_param('message'); 

  // Verzend de e-mail 
  $sent = wp_mail($to, $subject, $message); 
  if ($sent) { 
    return array('message' => 'E-mail verzonden'); 
  } else { 
    return array('message' => 'Er is een fout opgetreden bij het verzenden van de e-mail'); 
  } 
}

Vervolgens kunnen we deze functie in de front-end aanroepen met bijvoorbeeld axios.

const data = { 
  to: 'ontvanger@email.com', 
  subject: 'Onderwerp', 
  message: 'Dit is de inhoud van de e-mail', 
}; 

// Voer een POST-verzoek uit met Axios 
axios.post(apiUrl, data) 
 .then(response => { 
    console.log('E-mail verzonden:', response.data.message); 
  }) 
  .catch(error => { 
    console.error('Fout bij het verzenden van de e-mail:', error); 
  }
);