Een quiz vormgeven met eigen code

Met de instellingen van een thema kies je kleuren, lettertypen en knoppen. Wil je dat de quiz er helemaal uitziet als je eigen ontwerp, geef het thema dan eigen code: één stylesheet voor de hele quiz en eigen HTML-templates voor de startpagina, de vragen, het laadscherm, de pagina voor het resultaat en de productcheckpagina. bluebarry blijft alles doen wat de quiz doet. Jouw code bepaalt alleen waar alles staat en hoe het eruitziet.

Custom code openen

1. Ga naar Quizzes, klik op Edit bij je quiz en open het tabblad Design in het linkerpaneel.
2. Klik op Edit bij het thema dat deze quiz gebruikt. Custom code gaat alleen open voor dat thema, omdat de editor een preview van deze quiz laat zien.
3. Scrol helemaal naar beneden in de thema-instellingen en klik op Custom code.

De editor heeft zes tabbladen: CSS, Start page, Question, Loading, Pre-result en Product check. Ernaast staat een live preview van de quiz, die je wisselt tussen desktop en mobiel. De regel bovenin noemt de quizzen die dit thema gebruiken. Is het het standaardthema van je webshop, dan gebruiken quizzen zonder eigen thema het ook.

• Een leeg tabblad houdt het standaardscherm. Klik op Start from an example voor werkende code die je kunt aanpassen.
• Je code wordt vanzelf opgeslagen kort nadat je stopt met typen. Zit er een fout in, dan laat de editor onder het veld zien wat je moet oplossen en slaat hij niets op. Zo krijgt een live quiz nooit een kapot ontwerp.
• Kies op het tabblad Product check een product naast Run the preview on a product page. De preview laat de pagina dan zien zoals klanten hem op dat product zien.

CSS

Eén stylesheet bepaalt de stijl van elk scherm van de quiz, ook de resultaatpagina, de productcheckpagina en de foutpagina. Het geldt alleen binnen de quiz en wint zonder !important van de kleuren van het thema. Eigenschappen voor beweging en positie, zoals transform, opacity, transition en position, houden hun normale gewicht, zodat de animaties van de quiz blijven werken. Een eigen resultaatpagina (bèta) heeft eigen markup en CSS, dus de classes van de resultaatpagina hieronder gelden daar niet.

.bb-q-answer {
  border: 1px solid var(--bb-color-title);
  border-radius: var(--bb-radius, 8px);
}
.bb-q-answer[data-selected] {
  background: var(--bb-color-button);
  color: var(--bb-color-button-text);
}
@media (max-width: 480px) {
  .bb-q-answers { grid-template-columns: 1fr; }
}

• Een @media-query op breedte volgt de breedte van de quiz, niet die van het browservenster. Hij werkt dus ook in een pop-up, een zijpaneel en de mobiele preview.
• Classes die met bb-q- beginnen blijven stabiel, behalve de bb-q-i--classes: die zijn intern en kunnen altijd veranderen. Geef classes die je zelf toevoegt een naam zonder het voorvoegsel bb-.
• De instellingen van het thema zijn beschikbaar als variabelen: --bb-color-button, --bb-color-button-text, --bb-color-background, --bb-color-title, --bb-color-accent, --bb-color-answer, --bb-color-answer-text, --bb-font-body, --bb-font-title en --bb-radius. Laat het thema een instelling leeg, dan ontbreekt de variabele. Geef dus een terugvalwaarde op.
• Opmaak per toestand geef je met [data-selected] op een gekozen antwoord, aria-pressed bij meerkeuze, :disabled op knoppen die nog niet bruikbaar zijn, aria-invalid op een invoerveld met een fout en data-state op een winkelwagenknop.
• Antwoorden worden standaard donkerder als je eroverheen beweegt. Voor een eigen hover-stijl zet je dat uit met .bb-q-answer:hover { filter: none; }.

Het vraagscherm heeft ook data-bb-display-type, zoals standard, picture of dropdown, zodat je één vraagtype apart kunt opmaken. De productcheckpagina gebruikt voor haar kaarten de classes van de resultaatkaarten, met de bb-q-check-classes erbovenop, bijvoorbeeld:

.bb-q-check[data-state="no-match"] .bb-q-check-product { opacity: .6; }
.bb-q-check-label[data-active] { text-transform: uppercase; }

Zo werken templates

• Templates zijn Handlebars: {{title}} toont een waarde, en je kunt {{#if}}, {{#each}} en de helpers eq, ne, or, and, inc en lookup gebruiken. Elke waarde wordt ge-escaped.
• Met een data-bb--attribuut, zoals data-bb-start of data-bb-answer, vertel je bluebarry wat een element doet. bluebarry koppelt het gedrag dan aan jouw element.
• Je markup heeft geen opmaak tot je CSS die geeft. De enige uitzondering zijn de startknop en de knop Volgende: die beginnen in de knopkleuren, de afronding en het lettertype van het thema, en elke regel van jou gaat voor.
• Zet alle CSS in het tabblad CSS. Een <style>-element in een template is niet toegestaan.

Startpagina

Je kunt title, description, buttonText, imageUrl, logoUrl, questionCount en language gebruiken. De template heeft een knop of link met data-bb-start nodig, die de quiz start.

<div class="hero">
  {{#if imageUrl}}<img src="{{imageUrl}}" alt="">{{/if}}
  <h1>{{title}}</h1>
  <p>{{description}}</p>
  <button type="button" data-bb-start>{{buttonText}}</button>
</div>

Vraag

De vraagtemplate geldt voor elke vraag, van welk type ook. Pagina's die je tussen vragen toevoegt houden hun eigen lay-out. Je kunt title, description, imageUrl, displayType, isMultipleChoice, step (het nummer van de vraag in het pad van de klant), progress (0 tot 100), nextText, skipText, logoUrl en language gebruiken, plus de lijsten hieronder.

De template heeft één leeg element met data-bb-answers nodig. Alles wat je template niet zelf toont, zet bluebarry daar: de antwoorden, de dropdown, de invoervelden, de toestemming en foutmeldingen. Met een leeg element met data-bb-actions bepaal je waar de knoppen Volgende en Overslaan komen.

Eigen antwoorden

Loop door answers en toon elk antwoord als knop met data-bb-answer. Elk antwoord heeft answerId, text, description, imageUrl en index. Toon alle antwoorden of geen, en houd links, invoervelden en andere knoppen uit de antwoordknop.

{{#each answers}}
  <button type="button" class="choice" data-bb-answer="{{answerId}}">
    {{#if imageUrl}}<img src="{{imageUrl}}" alt="">{{/if}}
    <span>{{text}}</span>
  </button>
{{/each}}
<div data-bb-answers></div>

bluebarry geeft je knoppen de class bb-q-answer, zet data-selected op een gekozen antwoord en regelt enkele keuze en meerkeuze. Bij een dropdownvraag staan de opties in options. Zonder eigen knoppen blijft de standaard dropdown met zoekveld.

Invoervelden en toestemming

Tekst-, e-mail-, telefoon-, getal-, schuif- en naamvragen hebben hun invoer in fields, elk met answerId, kind, label, placeholder en required. Zet data-bb-field voor elk veld op een <input>. bluebarry stelt het type in, controleert de waarde en schrijft een melding in een leeg element met data-bb-field-error.

Heeft een e-mail- of telefoonvraag een toestemmingsregel, voeg dan een checkbox met data-bb-consent toe en een leeg element met data-bb-consent-text. bluebarry zet je toestemmingstekst daarin, zodat klanten altijd precies lezen waar ze mee instemmen.

{{#each fields}}
  <label>{{label}} <input data-bb-field="{{answerId}}" placeholder="{{placeholder}}"></label>
  <span class="hint" data-bb-field-error="{{answerId}}"></span>
{{/each}}
{{#if hasConsent}}
  <label><input type="checkbox" data-bb-consent> <span data-bb-consent-text></span></label>
{{/if}}
<div data-bb-answers></div>

Volgende, Overslaan en Terug

• <button data-bb-next>{{nextText}}</button> en <button data-bb-skip>{{skipText}}</button> werken als de standaardknoppen. bluebarry houdt Volgende uitgeschakeld tot het antwoord geldig is en verbergt een knop als de vraag die niet heeft. De onderbalk toont dan alleen de knoppen die je template niet zelf toont.
• Met data-bb-back, data-bb-restart of data-bb-close gaat je eigen knop terug, start hij de quiz opnieuw of sluit hij de quiz.
• Heeft een vraagtemplate een data-bb-back-knop, dan neemt de template de bovenbalk over. De quiz verbergt op vraagschermen dan zijn voortgangsbalk, Terug, Opnieuw en het logo, alleen de sluitknop blijft. Je eigen voortgang maak je met {{progress}} of {{step}}.

Laden en voor het resultaat

De laadtemplate verschijnt terwijl de resultaten laden, terwijl een klant verdergaat met een quiz die hij eerder begon en terwijl de code van een scherm laadt. Houd de tekst dus algemeen. Je kunt label, logoUrl en language gebruiken. label is altijd Engels, dus kies zichtbare tekst op basis van language of houd het scherm puur decoratief. De template voor het resultaat verschijnt terwijl de resultaten worden voorbereid, met de title, description en imageUrl van de pagina voor het resultaat uit je quiz. Beide schermen gaan vanzelf verder en nemen dus geen data-bb--attributen aan.

<div class="spinner" aria-hidden="true"></div>
{{#if logoUrl}}<img src="{{logoUrl}}" alt="">{{/if}}

Productcheckpagina

Start een quiz vanaf een productpagina, dan is het resultaat de productcheck: past dit product? De template op het tabblad Product check vervangt die pagina. Hij werkt als een eigen resultaatpagina (bèta), met dezelfde productvelden, helpers en knoppen. Daarnaast krijg je product (het gecheckte product), products (de alternatieven), match, title en description, plus labelOne en labelTwo voor de labels boven het gecheckte product en boven de alternatieven. Die twee zijn geen losse tekst: toon {{labelOne.text}} en kijk met labelOne.active welk label is uitgelicht. De teksten komen uit de productcheckinstellingen van de quiz.

<h2>{{title}}</h2>
{{#with product}}
  <h3>{{name}}</h3>
  {{#if addsToCart}}<button type="button" data-bb-add="{{variantId}}">{{cta}}</button>
  {{else}}<a href="{{url}}" data-bb-product-link="{{url}}">{{cta}}</a>{{/if}}
{{/with}}

De template heeft minstens één knop of link met data-bb-add of data-bb-product-link nodig, zodat klanten altijd kunnen kopen. De pagina heeft geen volgende stap, dus data-bb-next, data-bb-add-all en data-bb-ask-chat zijn niet toegestaan. De CSS van een eigen resultaatpagina geldt hier niet: geef de pagina opmaak in het tabblad CSS.

De sluitknop

Op de startpagina, op een vraag waarvan de template de bovenbalk overneemt en op een eigen resultaatpagina zweeft de sluitknop rechtsboven over je template. Houd die hoek vrij, bijvoorbeeld met padding-right: 56px op je eigen bovenbalk.

Wil je de knop in je eigen lay-out plaatsen, voeg dan één leeg element met data-bb-close-slot toe aan de startpagina of de vraagtemplate. De knop neemt daar de tekstkleur van het element over. Geef het dus een kleur die opvalt, en geef de knop opmaak met [data-bb-close-slot] .bb-q-close. Een ingesloten quiz heeft geen sluitknop, dus daar blijft het element leeg.

<header class="topbar">
  <button type="button" data-bb-back>Terug</button>
  <span data-bb-close-slot></span>
</header>

Schermovergangen

Wil je schermwissels met je eigen CSS animeren, open dan Animations in het tabblad Design van de quiz en kies Custom voor desktop, mobiel of allebei. Tijdens een wissel staan beide schermen op de pagina:

• Het scherm dat vertrekt krijgt data-bb-transition="leave", het nieuwe data-bb-transition="enter". Allebei krijgen ze data-bb-direction: forward, of back na Terug.
• Elk scherm heeft data-bb-screen (start, question, loading, pre-result, result, product-check en meer), zodat één scherm anders kan bewegen.
• De quiz wacht tot je animaties klaar zijn, hooguit 1,2 seconden. Gebruik @keyframes in plaats van transition en blijf onder een halve seconde.
• Hebben klanten minder beweging aangezet, dan wisselen schermen meteen. Zonder CSS voor deze attributen wisselen ze ook meteen.

@keyframes brand-in { from { opacity: 0; transform: translateY(24px); } }
@keyframes brand-out { to { opacity: 0; transform: translateY(-12px); } }
[data-bb-transition="enter"] { animation: brand-in .35s ease-out both; }
[data-bb-transition="leave"] { animation: brand-out .2s ease-in both; }
@keyframes brand-in-back { from { opacity: 0; transform: translateY(-24px); } }
[data-bb-transition="enter"][data-bb-direction="back"] { animation-name: brand-in-back; }

Scripts

Elke template kan een inline <script> bevatten. Het draait in de live quiz en in de preview van Custom code. Gebruik de data-bb--attributen voor alles wat ze afdekken, en schrijf alleen een script voor wat markup niet kan, zoals een live samenvatting van de keuzes. Scripts met src of type="module" zijn niet toegestaan.

bluebarryQuiz(document.currentScript) geeft je script het huidige scherm:

• getState() geeft het scherm, de vraag, de antwoorden en wat er gekozen is, de waarden van de velden, de toestemming en of de klant verder, overslaan of terug kan.
• Acties doen precies wat de bijbehorende klik doet: select(id), deselect(id), toggle(id), setField(id, value), setConsent(checked), next(), skip(), back(), restart(), close() en start(). Ze geven false terug als de quiz ze niet uitvoert, bijvoorbeeld next() zolang het antwoord niet geldig is.
• on(type, listener) luistert naar de gebeurtenissen van het scherm: screen, select, answer, change, validation en, met de animatie Custom, transition. Lees de toestand in een change-listener, want die verandert pas als het scherm opnieuw is getekend. Een script in de laadtemplate draait wel, maar krijgt geen gebeurtenissen.

{{#each answers}}<button type="button" data-bb-answer="{{answerId}}">{{text}}</button>{{/each}}
<p class="summary" aria-live="polite"></p>
<div data-bb-answers></div>
<script>
  const quiz = bluebarryQuiz(document.currentScript);
  const summary = document.currentScript.closest('.bb-q-template').querySelector('.summary');
  const show = (state) => {
    const picked = state.answers.filter((a) => a.selected).map((a) => a.text);
    summary.textContent = picked.length ? 'Jouw keuze: ' + picked.join(', ') : '';
  };
  show(quiz.getState());
  quiz.on('change', (detail) => show(detail.state));
</script>

Elk scherm krijgt zijn eigen handle, die stopt zodra het scherm verdwijnt. Luister via on of op de template in plaats van op document, anders stapelen je listeners zich op van vraag tot vraag.

Als een scherm terugvalt

De editor weigert een template waarin een verplicht onderdeel ontbreekt, zoals een startpagina zonder data-bb-start of een vraagtemplate zonder precies één leeg data-bb-answers. Sommige problemen blijken pas bij een bepaalde vraag, bijvoorbeeld als de plek voor de antwoorden in een {{#if}} staat, als je antwoordknoppen niet één op één bij de antwoorden van de vraag passen of als een template een toestemmingsvakje toont bij een vraag zonder toestemmingsregel. Dat scherm toont dan de standaard lay-out en de browserconsole krijgt een waarschuwing. Zo kan de klant de quiz altijd afmaken.

Teksten op eigen schermen bewerken

Waar Studio een quiz in zijn eigen ontwerp op een canvas toont, zoals op Home, kun je de tekst van een scherm uit je template niet aanklikken om die te bewerken. Je template bepaalt waar elke tekst staat, en kan een tekst herhalen, weglaten of met een script aanpassen. Studio kan daardoor niet weten bij welke instelling van de quiz het aangeklikte stuk hoort. Teksten pas je aan in de quizeditor, de lay-out in Custom code. Het canvas in de quizeditor houdt de standaard lay-out, dus daar blijven de teksten bewerkbaar. Je ontwerp zie je in de preview van Custom code of via Preview.

Regels en limieten

• De CSS mag tot 40.000 tekens lang zijn en elke template tot 60.000.
• CSS die een onderdeel dat klanten nodig hebben, zoals de antwoorden, de knop Volgende of de sluitknop, verbergt met display: none of visibility: hidden, wordt geweigerd.
• @keyframes-namen die de quiz zelf gebruikt, zoals spin, pulse of namen die met advisor- beginnen, worden geweigerd. Kies een eigen naam, zoals brand-fade.
• @import wordt verwijderd als het thema wordt opgeslagen.

Goed om te weten

• De code hoort bij het thema en verandert dus elke quiz die het thema gebruikt. Hij zit niet in een quizversie, dus je hoeft hem niet te publiceren. De preview laat wijzigingen direct zien, live quizzen nemen ze binnen ongeveer een uur over. Wil je iets op één quiz uitproberen, kopieer het thema dan eerst. Zie Het thema en de lay-out van je quiz aanpassen.
• Zodra een thema eigen code heeft, wordt de kopbalk boven de quiz transparant, zodat je achtergrond tot bovenaan doorloopt. Geef .bb-q-header-bar een achtergrond voor een volle balk.
• Bij de eerste keer laden toont een startpagina of vraag met een template even de achtergrond van het thema, tot de code van de template geladen is.
• Custom code werkt hetzelfde op Shopify, WooCommerce, Magento en CCV Shop, omdat de quiz op elk platform in een eigen frame draait.