Week 4

Itereren op de preview oplossing, formulieren afhandelen met serverless functions en een beetje documentatie schrijven voor contributors

Deze week heb ik een betere oplossing proberen te vinden voor de preview omgeving. Hoewel het hijacken van de pagina met JavaScript tot nu toe een prima oplossing was bleek het dat het lastig is om dit te blijven onderhouden als je een tal van componenten hebt.

Daarnaast ben ik gaan kijken hoe we formulieren kunnen afhandelen d.m.v. het gebruiken van serverless functions. Normaliter zou je dit dus op de server afhandelen, maar ja, statische website enzo.

Ook heb ik, in samenwerking met Deanna alvast wat documentatie geschreven voor nieuwe mensen die gaan werken aan de opzet. Ik heb een stuk geschreven dat moet beschrijven hoe je een nieuw component kan toevoegen aan het CMS.

Een betere oplossing vinden voor de preview omgeving

Hoewel het hijacken met JavaScript een betere oplossing is voor de uiteindelijke eindgebruiker van het CMS was dit het zeker niet voor een andere groep stakeholders, namelijk de studenten van CMD die aan de website verder gaan ontwikkelen. Zij zouden dan ook nog eens de kennis moeten hebben om het component wat ze zelf hebben gemaakt ook nog eens in JavaScript te maken... niet bepaald ideaal dus.

Daarom heb ik ervoor gekozen om de preview omgeving iets anders op te zetten, namelijk door er werkelijk een aparte omgeving van te maken door het een eigen branch te geven, die kunnen we dan natuurlijk eenvoudig deployen via Vercel.

Het voordeel daarvan is, is dat we geen rare dingen hoeven te doen op de live omgeving om de juiste content op te halen en dat we alleen op de preview omgeving dat extra Storyblok script wat we moeten gebruiken voor de preview omgeving alleen op die preview omgeving wordt ingeladen.

We snappen dat dit niet de ideale oplossing is voor een eindgebruiker van het CMS. Voor nu werkt dit echter goed genoeg, wel hebben we gemerkt dat het bouwen van een dedicated preview omgeving echt heel lastig is bij een statisch-gegenereerde website.

Formulieren afhandelen met een serverless function

Ook was deze week aan mij de taak om te kijken hoe we formulieren af kunnen handelen met een serverless function. Normaliter heb je hier dus een server voor om formulieren (met name progressive enhanced) af te handelen. Echter, aangezien we een statisch gegenereerde website aan het bouwen zijn hebben we dus geen 'echte' server. Voor server-side functionaliteit kunnen we daarom leunen op serverless functions.

Idealiter één serverless function gebruiken

Idealiter wilden we dit afhandelen met één enkele serverless function zodat niet iedereen die een formulier implementeert zijn eigen serverless function weer hoeft te schrijven. Ik heb daarom een simpele opzet gebouwd die 'gewoon' het formulier verwerkt en nog even niets doet met de input vanuit de velden. Dit zodat we in ieder geval aan de opdrachtgever konden laten zien van "kijk, vanaf hier kunnen we alles doen met die formulieren wat we willen".

Een serverless function is niets meer dan een route

In weze zijn serverless functions niets meer dan een JavaScript dat uitgevoerd wordt zodra je op een bepaalde route terecht komt (in ons geval vaak /api/serverless-function-name). Daarnaast zijn het altijd Node bestanden en kan je dus alles doen wat je normaliter op een Node server zou doen. Toen dit beide tot me doordrong werd het redelijk eenvoudig om de serverless function op te zetten.

Allereerst, zoals ik altijd doe, ben ik gaan valideren of het aanspreken van een serverless functie überhaupt werkt door iets simpels terug te geven in de functie:

// /api/handle-form-submit.js
module.exports = (request, response) => {
    response.send('hello from the function')
}

Door vervolgens op elk formulier een action neer te zetten naar /api/handle-form-submit werd die specifieke serverless functie uitgevoerd als iemand het formulier indiende en zag je in de browser 'Hello from the function' staan. Het aanroepen van zo'n functie werkte dus. Het eerste wat ik me bedacht is dat het voor een eindgebruiker toch best sketchy kan zijn als deze in de URL balk iets als 'cmd-amsterdam.nl/api/handle-form-submit' ziet...

Gelukkig konden we dit eenvoudig fixen door een zogenaamde rewrite toe te voegen in een configuratie bestand voor onze deployment omgeving, iets wat ik eerder had gezien in het project van een oud-collega van me:

// /now.json
{
  "rewrites": [
    { "source": "/submit", "destination": "/api/handle-form-submit" },
  ]
}

Door dit te doen wordt elk verzoek naar /submit als het ware herschreven naar /api/handle-form-submit. Echter, /submit blijft hierdoor in de URL balk staan, zo kunnen we onze serverless functie dus op een mooiere URL uitvoeren en hebben we geen sketchyness meer.

Het eerste wat nu moest gebeuren is het toevoegen van /submit aan de action van elk formulier. Hierdoor werd weer de juiste serverless function uitgevoerd wanneer je het formulier verstuurde:

<form
    class="app-form"
    action="/submit"
    method="POST"
>
    <!-- ... -->
</form>

HTML terugsturen vanuit een serverless function?

Natuurlijk wil je een gebruiker feedback geven wanneer hij of zij een formulier indient. Als we een serverless functie alleen maar JSON laten terugsturen zouden we hier alleen wat aan hebben als we JavaScript gebruiken. Echter, we zijn CMD, we willen dit progressively enhanced oplossen.

Toen dacht ik van: "Als het simpelweg een Node route is, kan ik dan niet gewoon HTML over de lijn terugsturen?" en dat bleek zeker mogelijk. Ik kon zelfs Nunjucks gebruiken om bepaalde templates te renderen. Ik besloot daarom een render functie te maken zoals ik het ongeveer kende uit Progressive Web Apps:

// /lib/render.js
const readFile = require('fs').promises.readFile
const nunjucks = require('nunjucks')

module.exports = async (name, data) => {
  const filePath = `${__dirname}/../src/site/views/${name}.html`
  const template = await readFile(filePath, { encoding: 'utf8' })

  return nunjucks.renderString(template, data)
}

Die render functie kon ik vervolgens gebruiken in de serverless functie om een success of error template terug te sturen:

const render = require('../lib/render')

module.exports = async (request, response) => {
    // Er wordt een POST request gestuurd, dus
    // alle info is beschikbaar in request.body
    const { email } = request.body
    
    if (!email) {
        const html = await render('error', { message: 'Alles kapot' })
        
        response.status(500)
        response.send(html)
        
        return
    }
    
    const html = await render('success', { message: `Geregistreerd met email ${email}` })

    response.status(200)
    response.send(html)
}

Door de bovenstaande serverless functie te gebruiken op /submit werd er naar de gebruiker dus altijd feedback gegeven of ze het formulier goed hebben ingevuld (weliswaar nog op een karige manier, maar toch). Het mooie hieraan is dat dit ook altijd werkt zonder JavaScript.

Een guide schrijven voor nieuwe developers

Om het eenvoudig te maken voor nieuwe developers om aan dit project te werken hebben we besloten om een guide te schrijven. Ik nam het deze week op mij om een stuk te schrijven over hoe je een component aan moet maken in Storyblok.

Ook heb ik een stuk geschreven over het project en wat headless is aangezien dat best belangrijke dingen zijn waar je als developer even van gehoord moet hebben voordat je het kan snappen.

Onderstaand een voorbeeld van de pagina's. De pagina over het project kan je hier vinden. Het stuk over hoe je een component bouwt in Storyblok kan je hier vinden.

PreviousWeek 3 NextWeek 5

Last updated 4 years ago

// /lib/render.js const readFile = require('fs').promises.readFile const nunjucks = require('nunjucks') module.exports = async (name, data) => { const filePath = `${__dirname}/../src/site/views/${name}.html` const template = await readFile(filePath, { encoding: 'utf8' }) return nunjucks.renderString(template, data) }

const render = require('../lib/render') module.exports = async (request, response) => { // Er wordt een POST request gestuurd, dus // alle info is beschikbaar in request.body const { email } = request.body if (!email) { const html = await render('error', { message: 'Alles kapot' }) response.status(500) response.send(html) return } const html = await render('success', { message: `Geregistreerd met email ${email}` }) response.status(200) response.send(html) }