Forhåndsvis dine mal-filer i Storybook

På en nylig Meetup-presentasjon introduserte Tom Arild Jakobsen, seniorkonsulent fra Item Consulting, oss for Enonic XP-applikasjonen Storybook. Appen lar utviklere jobbe på Thymeleaf- eller Freemarker-maler med millisekunders tilbakemeldingssløyfer. Du vil se hvordan du setter opp en Storybook i ditt XP-prosjekt, og dykke ned i noen av de mer avanserte funksjonene.

Hva er Storybook?

Storybook er et verktøy for utviklere, spesielt designet for å kjøres med Node.js. I konteksten av Enonic lar Storybook utviklere utvikle komponenter i isolasjon og forhåndsvise dem med hot module-reloading. Dette betyr at når utviklere jobber på sine malfiler, CSS eller frontend-JavaScript, blir eventuelle endringer de gjør umiddelbart reflektert i nettleseren. Dette verktøyet er spesielt nyttig for å lage et komponentbibliotek eller dokumentasjon av designsystem, organisere og dokumentere komponenter effektivt.

Storybook tilbyr også forskjellige plugins for å bistå med å kjøre tester, inkludert frontend-tester og tilgjengelighetssjekker. I denne konteksten refererer en "story" til en instansiert komponent eller mal, som kan være en undermal eller del av en komponent. Dette innebærer typisk HTML, stiler og frontend-JavaScript, og ekskluderer enhver backend-logikk fra kontrolleren i Enonic. Storybook fokuserer kun på frontend-aspektene.

Verktøyet ble opprinnelig bygget for bruk med frontend-rammeverk som React, Vue eller Svelte. Imidlertid, i Enonic-økosystemet, er komponenter som sider, oppsett og deler godt egnet for integrering med Storybook for forhåndsvisninger og utvikling.

Nylig har støtte for Freemarker og Thymeleaf, vanlige backend-malspråk brukt med Enonic, blitt lagt til Storybook. Selv om Freemarker er mer grundig testet, strekker støtten seg til begge språkene. Utviklere kan installere Storybook fra Enonic-markedet kun for utviklingsformål, da det ikke er ment for produksjonsmiljøer på grunn av potensielle sikkerhetsrisikoer. Konfigurasjonssikringer er på plass for å forhindre utilsiktet installasjon i produksjon, men brukere bør være varsomme.

Se også: Hvorfor velge Enonics headless CMS når du bygger et Next.js-nettsted »

Samlet sett gir Storybook et robust miljø for frontend-utvikling i Enonic, som forbedrer arbeidsflyten med umiddelbar visuell tilbakemelding og omfattende dokumentasjonsmuligheter.

Hvorfor bruke Storybook med Enonic XP?

Å bruke Storybook med Enonic XP gir flere fordeler, primært sentrert rundt dens effektive tilbakemeldingssløyfe og dokumentasjonsmuligheter. 

1. Umiddelbar tilbakemelding med hot module-reloading

En av de viktigste fordelene er den raske tilbakemeldingssløyfen. Med hot module-reloading, så snart du trykker på lagre, oppdateres forhåndsvisningen din umiddelbart. Dette eliminerer behovet for å flytte markøren bort fra koden din, slik at du kan opprettholde fokus og arbeidsflyt uten avbrudd.

2. Effektiv kodegjennomgang

Storybook lar deg sette opp forhåndskonfigurerte dataobjekter eller modeller for å teste forskjellige konfigurasjoner av dine komponenter. Dette betyr at du ikke trenger å opprette innhold manuelt for å forhåndsvise komponentene dine. Selv om det er viktig å teste sluttproduktet i Enonic XP før du går videre til kodegjennomgang, gir Storybook en flott innledende oversikt, som hjelper deg med å identifisere og fikse feil raskt.

3. Dokumentasjon og demonstrasjon

Storybook er også et verdifullt verktøy for å dokumentere dine komponenter. Ved å organisere komponentbiblioteket ditt innen Storybook, skaper du en omfattende dokumentasjonsressurs. Dette er spesielt nyttig for å demonstrere dine komponenter, vise frem deres funksjonalitet og design.

4. Verktøybibliotek for enkel integrasjon

For å komme i gang med Storybook i ditt prosjekt, må du installere applikasjonen og integrere noen verktøybiblioteker. Disse bibliotekene inkluderer filer som heter `.stories.js` eller lignende, som inneholder dine komponenthistorier. Et verktøybibliotek er opprettet for å forenkle denne prosessen, og sørger for TypeScript-typer og andre nødvendige verktøy. Detaljert dokumentasjon er tilgjengelig for å veilede deg trinn for trinn gjennom oppsettsprosessen.

Alt i alt forbedrer Storybook utviklingsarbeidsflyten i Enonic XP ved å gi umiddelbar visuell tilbakemelding, strømlinjeforme kodegjennomganger, og tilby robuste dokumentasjons- og demonstrasjonsmuligheter.

Demo/Live-koding

Under live-kodingsdemoen demonstrerte Tom Arild bruken av Storybook for å administrere og forhåndsvise komponenter innenfor et prosjekt. Tom Arild startet med å kjøre Storybook ved å bruke kommandoen `npm run storybook`. I Tom Arilds prosjekt har han opprettet et bibliotek som inneholder forskjellige komponenter, som han refererer til som "blokker." Disse blokkene, konfigurert med titler og elementer, utgjør grunnlaget for en trekkspillkomponent. Trekkspillets struktur og renderingslogikk administreres gjennom en mal som itererer over elementene og genererer trekkspillets innhold.

Ved å åpne story-filen `blocksAccordion.stories.ts`, fremhevet Tom Arild konfigurasjonsoppsettet for storyene og story-objektet selv. Story-objektet spesifiserer klassene og elementtabellen som brukes i renderingen. Ved å oppdatere tittelen på det første trekkspillelementet og lagre filen, blir endringene umiddelbart reflektert i forhåndsvisningen, og demonstrerer live-reloadingskapasiteten til Storybook.

Deretter gikk Tom Arild videre til å lage en story for en ny komponent, "faktaboksen." Han la til en ny fil og eksporterte en standardkonfigurasjon for å forhindre feil. Etter å ha konfigurert tittelen til "blocks/factbox," dukket storyen opp, men trengte videre oppsett for korrekt forhåndsvisning. Ved å bruke serverversjonen av Storybook spesifiserte Tom Arild serverparametrene og stien til malfilen.

Han støtte på en feil på grunn av manglende data, som han løste ved å sende de nødvendige argumentene, som tittelen "Hei, Faktaboks." Ved å fikse en feil i malen (omdøping av en variabel fra "body" til "text") ble forhåndsvisningen vist korrekt. Han importerte deretter CSS for å style faktaboksen riktig.

I tillegg konfigurerte Tom Arild kontrollalternativer for komponentens inngangsparametere, ved å bruke TypeScript-typer for å sikre gyldige inndataverdier. Dette inkluderte å lage gjenbrukbare inngangskontrollere for temaer, som tillot brukere å bytte mellom forskjellige stiler ved å bruke radioknapper.

Til slutt demonstrerte Tom Arild muligheten til å bruke inline-maler innen Storybook for å teste delmaler. Denne tilnærmingen muliggjør inkludering av andre malfiler, og gir et kraftig verktøy for omfattende testing. Verktøykassen dekker alle typer maler brukt i Tom Arilds prosjekter, og letter utviklings- og dokumentasjonsprosessen. Storybook viser seg å være en rask og effektiv måte å forhåndsvise og dokumentere serverrendrerte komponenter på, spesielt for prosjekter som benytter tradisjonell serversiderendering.

Spørsmål og svar

Spørsmål: Hva er det som viser historien i Storybook selv, eller er det noen annen plugin involvert?

Svar: Det er hovedsakelig Storybook selv. Det Tom Arild har i tillegg er ekstra Webpack-loadere som kan importere FTL-filer for Freemarker eller HTML-filer for Thymeleaf og følge disse avhengighetsgrafene. Ved å gjøre den importen blir det en del av avhengighetsgrafen, noe som muliggjør hot module-reloading.

Spørsmål: Hvis Tom Arild endrer noe, plukker Storybook opp endringene?

Svar: Ja, Storybook plukker opp endringene. For eksempel er CSS importert direkte i filen. I Tom Arilds assets-mappe har han et høyere nivå av CSS som peker til alle andre filer og bygger en pakke. For Storybook foretrekker han mer presise importer. Vanlige stiler som vil bli brukt på alle historier er konfigurert i Storybook-mappen, og mer eksakte importer brukes i hver historie.

Spørsmål: Har Tom Arild laget sin egen styling, eller bruker han Storybooks?

Svar: Alt i midten er Tom Arilds egen styling. Sidemenyene og alt annet er Storybook, men iframe i midten viser kun stilene og frontend-JavaScript som Tom Arild legger til.

Spørsmål: Er det konfigurerbart å flytte story-filene et annet sted, kanskje et annet repository eller mappe?

Svar: Ja, det er konfigurerbart. Tom Arild liker å holde story-filene sammen med komponentene de tester, men du kan potensielt plassere dem i et eget repo eller en annen mappe. Storybook vil sjekke etter alle filer med stories.ts og bruke dem til å lage listen over storyer. Du kan imidlertid ikke ukritisk dele filer mellom XP-miljøet ditt og Storybook-miljøet ditt på grunn av potensielle avhengigheter og sti-problemer.

Spørsmål: Kan du utdype funksjonaliteten eksponert av XP-appen du laget?

Svar: XP-appen eksponerer en tjeneste som tar ID-en, som er stien til filen, og spørringsparametere for modellen, og rendrer deretter ut HTML og returnerer den. Den inkluderer funksjonalitet for å pakke ut eller serialisere JSON-objekter sendt som spørringsparametere, deserialisere datoinndata på serversiden, og konvertere dem til passende Java-objektformer for bruk i maler. Denne prosessen muliggjør integrasjon av Java datetime-objekter i malene.

Spørsmål: Hvordan håndterer denne integrasjonen datetime-objekter?

Svar: Malen bruker enten Thymeleaf- eller Freemarker-kode for å rendre ut strengen fra datetime-objekter. Det er funksjonalitet for å deserialisere datoinndata på serversiden i XP-applikasjonen for å matche Java-objektformer, noe som gjør det mulig å bruke Java-typer effektivt i malene.