Ein Quiz mit eigenem Code gestalten

Mit den Theme-Einstellungen legst du Farben, Schriften und Buttons fest. Soll das Quiz ganz nach deinem eigenen Design aussehen, gibst du dem Theme eigenen Code: ein Stylesheet für das ganze Quiz und eigene HTML-Vorlagen für die Startseite, die Fragen, den Ladebildschirm, die Seite vor dem Ergebnis und die Produkt-Check-Seite. bluebarry kümmert sich weiter um alles, was das Quiz tut. Dein Code bestimmt nur, wo was steht und wie es aussieht.

Custom code öffnen

1. Gehe zu Quizzes, klicke bei deinem Quiz auf Edit und öffne im linken Bereich den Tab Design.
2. Klicke beim Theme, das dieses Quiz nutzt, auf Edit. Custom code lässt sich nur für dieses Theme öffnen, weil der Editor genau dieses Quiz in der Vorschau zeigt.
3. Scrolle in den Theme-Einstellungen ganz nach unten und klicke auf Custom code.

Der Editor hat sechs Tabs: CSS, Start page, Question, Loading, Pre-result und Product check. Daneben siehst du eine Live-Vorschau des Quiz, die du zwischen Desktop und Handy umschaltest. Die Zeile oben nennt die Quizze, die dieses Theme nutzen. Ist es das Standard-Theme deines Shops, nutzen es auch Quizze ohne eigenes Theme.

• Ein leerer Tab behält den Standardbildschirm. Mit Start from an example bekommst du funktionierenden Code, den du anpassen kannst.
• Dein Code speichert sich kurz nach dem Tippen von selbst. Enthält er einen Fehler, zeigt der Editor unter dem Feld, was du korrigieren musst, und speichert nicht. So bekommt ein live geschaltetes Quiz nie ein kaputtes Design.
• Im Tab Product check wählst du neben Run the preview on a product page ein Produkt aus. Die Vorschau zeigt die Seite dann so, wie Kunden sie auf diesem Produkt sehen.

CSS

Ein Stylesheet gestaltet jeden Bildschirm des Quiz, auch die Ergebnisseite, die Produkt-Check-Seite und die Fehlerseite. Es gilt nur innerhalb des Quiz und setzt sich ohne !important gegen die Farben des Themes durch. Eigenschaften für Bewegung und Position wie transform, opacity, transition und position behalten ihr normales Gewicht, damit die Animationen des Quiz weiter funktionieren. Eine eigene Ergebnisseite (Beta) hat ihr eigenes Markup und CSS, die Klassen der Ergebnisseite unten gelten dort also nicht.

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

• Eine @media-Abfrage auf die Breite richtet sich nach der Breite des Quiz, nicht nach dem Browserfenster. Sie funktioniert also auch im Pop-up, im Seitenpanel und in der Handy-Vorschau.
• Klassen, die mit bb-q- beginnen, bleiben stabil, außer den bb-q-i--Klassen: Die sind intern und können sich jederzeit ändern. Gib Klassen, die du selbst hinzufügst, einen Namen ohne das Präfix bb-.
• Die Einstellungen des Themes stehen dir als Variablen zur Verfügung: --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 und --bb-radius. Lässt das Theme eine Einstellung leer, fehlt die Variable. Gib deshalb einen Ersatzwert an.
• Zustände gestaltest du mit [data-selected] auf einer gewählten Antwort, aria-pressed bei Mehrfachauswahl, :disabled auf Buttons, die noch nicht nutzbar sind, aria-invalid auf einem Eingabefeld mit Fehler und data-state auf einem Warenkorb-Button.
• Antworten werden beim Hovern standardmäßig dunkler. Für einen eigenen Hover-Effekt schaltest du das mit .bb-q-answer:hover { filter: none; } ab.

Der Fragebildschirm hat außerdem data-bb-display-type, zum Beispiel standard, picture oder dropdown, damit du einen Fragetyp gezielt gestalten kannst. Die Produkt-Check-Seite nutzt für ihre Karten die Klassen der Ergebniskarten und zusätzlich die bb-q-check-Klassen, zum Beispiel:

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

So funktionieren Vorlagen

• Vorlagen sind Handlebars: {{title}} gibt einen Wert aus, und du kannst {{#if}}, {{#each}} und die Helfer eq, ne, or, and, inc und lookup verwenden. Jeder Wert wird maskiert.
• Mit einem data-bb--Attribut wie data-bb-start oder data-bb-answer sagst du bluebarry, was ein Element tut. bluebarry hängt das Verhalten dann an dein Element.
• Dein Markup ist ungestaltet, bis dein CSS es gestaltet. Einzige Ausnahme sind der Start-Button und der Weiter-Button: Sie starten in den Button-Farben, dem Radius und der Schrift des Themes, und jede Regel von dir hat Vorrang.
• Schreib dein gesamtes CSS in den Tab CSS. Ein <style>-Element in einer Vorlage ist nicht erlaubt.

Startseite

Du kannst title, description, buttonText, imageUrl, logoUrl, questionCount und language verwenden. Die Vorlage braucht einen Button oder Link mit data-bb-start, der das Quiz startet.

<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>

Frage

Die Fragevorlage gilt für jede Frage, egal welchen Typs. Seiten, die du zwischen Fragen einfügst, behalten ihr eigenes Layout. Du kannst title, description, imageUrl, displayType, isMultipleChoice, step (die Nummer der Frage im Weg des Kunden), progress (0 bis 100), nextText, skipText, logoUrl und language verwenden, dazu die Listen weiter unten.

Die Vorlage braucht ein leeres Element mit data-bb-answers. Alles, was deine Vorlage nicht selbst darstellt, setzt bluebarry dort ein: die Antworten, das Dropdown, die Eingabefelder, die Einwilligung und Fehlermeldungen. Mit einem leeren Element mit data-bb-actions legst du fest, wo die Buttons Weiter und Überspringen stehen.

Eigene Antworten

Durchlaufe answers mit {{#each}} und stelle jede Antwort als Button mit data-bb-answer dar. Jede Antwort hat answerId, text, description, imageUrl und index. Stelle alle Antworten dar oder keine, und lass Links, Eingabefelder und weitere Buttons aus dem Antwort-Button heraus.

{{#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 gibt deinen Buttons die Klasse bb-q-answer, setzt data-selected auf eine gewählte Antwort und kümmert sich um Einfach- und Mehrfachauswahl. Bei einer Dropdown-Frage stehen die Optionen stattdessen in options. Ohne eigene Buttons bleibt das Standard-Dropdown mit seiner Suche.

Eingabefelder und Einwilligung

Text-, E-Mail-, Telefon-, Zahlen-, Schieberegler- und Namensfragen haben ihre Eingaben in fields, jeweils mit answerId, kind, label, placeholder und required. Setze data-bb-field für jedes Feld auf ein <input>. bluebarry setzt den Feldtyp, prüft den Wert und schreibt eine Meldung in ein leeres Element mit data-bb-field-error.

Hat eine E-Mail- oder Telefonfrage eine Einwilligung, füge eine Checkbox mit data-bb-consent und ein leeres Element mit data-bb-consent-text hinzu. bluebarry schreibt deinen Einwilligungstext hinein, damit Kunden immer genau den Wortlaut lesen, dem sie zustimmen.

{{#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>

Weiter, Überspringen und Zurück

• <button data-bb-next>{{nextText}}</button> und <button data-bb-skip>{{skipText}}</button> funktionieren wie die Standard-Buttons. bluebarry lässt Weiter deaktiviert, bis die Antwort gültig ist, und blendet einen Button aus, wenn die Frage ihn nicht hat. Die Fußleiste zeigt dann nur noch die Buttons, die deine Vorlage nicht selbst darstellt.
• Mit data-bb-back, data-bb-restart oder data-bb-close geht dein eigener Button zurück, startet das Quiz neu oder schließt es.
• Hat eine Fragevorlage einen data-bb-back-Button, gehört ihr die obere Leiste. Das Quiz blendet auf Fragebildschirmen dann seinen Fortschrittsbalken, Zurück, Neustart und das Logo aus, nur der Schließen-Button bleibt. Deinen eigenen Fortschritt baust du mit {{progress}} oder {{step}}.

Laden und vor dem Ergebnis

Die Ladevorlage erscheint, während die Ergebnisse laden, während ein Kunde ein angefangenes Quiz fortsetzt und während der Code eines Bildschirms lädt. Halte ihren Text deshalb allgemein. Du kannst label, logoUrl und language verwenden. label ist immer Englisch. Wähle sichtbaren Text deshalb anhand von language oder halte den Bildschirm rein dekorativ. Die Vorlage vor dem Ergebnis erscheint, während die Ergebnisse vorbereitet werden, mit title, description und imageUrl der Seite vor dem Ergebnis aus deinem Quiz. Beide Bildschirme gehen von selbst weiter und nehmen deshalb keine data-bb--Attribute an.

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

Produkt-Check-Seite

Läuft ein Quiz von einer Produktseite aus, ist sein Ergebnis die Produkt-Check-Seite: Passt dieses Produkt? Die Vorlage im Tab Product check ersetzt diese Seite. Sie funktioniert wie eine eigene Ergebnisseite (Beta), mit denselben Produktfeldern, Helfern und Buttons. Dazu bekommst du product (das geprüfte Produkt), products (die Alternativen), match, title und description, dazu labelOne und labelTwo für die Labels über dem geprüften Produkt und über den Alternativen. Diese beiden sind kein reiner Text: Gib {{labelOne.text}} aus und prüfe mit labelOne.active, welches hervorgehoben ist. Die Texte stammen aus den Produkt-Check-Einstellungen des 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}}

Die Vorlage braucht mindestens einen Button oder Link mit data-bb-add oder data-bb-product-link, damit Kunden immer kaufen können. Die Seite hat keinen nächsten Schritt, deshalb sind data-bb-next, data-bb-add-all und data-bb-ask-chat nicht erlaubt. Das CSS einer eigenen Ergebnisseite erreicht sie nicht: Gestalte sie im Tab CSS.

Der Schließen-Button

Auf der Startseite, auf einer Frage, der die obere Leiste gehört, und auf einer eigenen Ergebnisseite schwebt der Schließen-Button oben rechts über deiner Vorlage. Halte diese Ecke frei, zum Beispiel mit padding-right: 56px auf deiner eigenen Leiste.

Soll der Button in deinem eigenen Layout stehen, füge der Startseite oder der Fragevorlage ein leeres Element mit data-bb-close-slot hinzu. Der Button übernimmt dort die Textfarbe des Elements. Gib ihm also eine Farbe, die sich gut abhebt, und gestalte ihn mit [data-bb-close-slot] .bb-q-close. Ein eingebettetes Quiz hat keinen Schließen-Button, dort bleibt der Platz leer.

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

Bildschirmwechsel animieren

Willst du Bildschirmwechsel mit deinem eigenen CSS animieren, öffne Animations im Tab Design des Quiz und wähle Custom für Desktop, Handy oder beide. Während eines Wechsels sind beide Bildschirme auf der Seite:

• Der Bildschirm, der geht, bekommt data-bb-transition="leave", der neue data-bb-transition="enter". Beide bekommen data-bb-direction: forward oder, nach Zurück, back.
• Jeder Bildschirm hat data-bb-screen (start, question, loading, pre-result, result, product-check und weitere), damit sich ein Bildschirm anders bewegen kann.
• Das Quiz wartet, bis deine Animationen fertig sind, höchstens 1,2 Sekunden. Nutze @keyframes statt transition und bleib unter einer halben Sekunde.
• Haben Kunden reduzierte Bewegung eingeschaltet, wechseln die Bildschirme sofort. Ohne CSS für diese Attribute wechseln sie ebenfalls sofort.

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

Skripte

Jede Vorlage kann ein Inline-<script> enthalten. Es läuft im Live-Quiz und in der Vorschau von Custom code. Nutze die data-bb--Attribute für alles, was sie abdecken, und schreib Skripte nur für das, was Markup nicht kann, etwa eine laufende Zusammenfassung der Auswahl. Skripte mit src oder type="module" sind nicht erlaubt.

bluebarryQuiz(document.currentScript) gibt deinem Skript den aktuellen Bildschirm:

• getState() liefert den Bildschirm, die Frage, ihre Antworten und die Auswahl, die Werte der Felder, die Einwilligung und ob der Kunde weiter, überspringen oder zurück kann.
• Aktionen tun genau das, was der passende Klick tut: select(id), deselect(id), toggle(id), setField(id, value), setConsent(checked), next(), skip(), back(), restart(), close() und start(). Sie geben false zurück, wenn das Quiz sie nicht annimmt, zum Beispiel next(), solange die Antwort nicht gültig ist.
• on(type, listener) hört auf die Ereignisse des Bildschirms: screen, select, answer, change, validation und, mit der Animation Custom, transition. Lies den Zustand in einem change-Listener, denn er ändert sich erst, wenn der Bildschirm neu dargestellt ist. Ein Skript in der Ladevorlage läuft, bekommt aber keine Ereignisse.

{{#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 ? 'Deine Auswahl: ' + picked.join(', ') : '';
  };
  show(quiz.getState());
  quiz.on('change', (detail) => show(detail.state));
</script>

Jeder Bildschirm bekommt sein eigenes Handle, das endet, sobald der Bildschirm verschwindet. Registriere Listener über on oder auf der Vorlage statt auf document, sonst sammeln sie sich von Frage zu Frage an.

Wenn ein Bildschirm zurückfällt

Der Editor lehnt eine Vorlage ab, der ein Pflichtteil fehlt, etwa eine Startseite ohne data-bb-start oder eine Fragevorlage ohne genau ein leeres data-bb-answers. Manche Probleme zeigen sich erst bei einer bestimmten Frage, zum Beispiel wenn der Platz für die Antworten in einem {{#if}} steht, wenn deine Antwort-Buttons nicht eins zu eins zu den Antworten der Frage passen oder wenn eine Vorlage eine Einwilligung auf einer Frage ohne Einwilligung zeigt. Dieser Bildschirm zeigt dann das Standardlayout, und die Browserkonsole bekommt eine Warnung. Kunden können das Quiz so immer abschließen.

Texte auf eigenen Bildschirmen bearbeiten

Wo Studio ein Quiz in seinem eigenen Design auf einer Fläche zeigt, zum Beispiel auf Home, kannst du die Texte eines Bildschirms aus deiner Vorlage nicht per Klick bearbeiten. Deine Vorlage bestimmt, wo jeder Text steht, und kann einen Text wiederholen, weglassen oder per Skript ändern. Studio kann deshalb nicht zuordnen, zu welcher Einstellung des Quiz das Angeklickte gehört. Texte änderst du im Quiz-Editor, das Layout in Custom code. Die Quizfläche im Quiz-Editor zeigt weiter das Standardlayout, dort bleiben die Texte bearbeitbar. Dein Design siehst du in der Vorschau von Custom code oder über Preview.

Regeln und Grenzen

• Das CSS darf bis zu 40.000 Zeichen lang sein, jede Vorlage bis zu 60.000.
• CSS, das ein Bedienelement, das Kunden brauchen, mit display: none oder visibility: hidden versteckt, etwa die Antworten, den Weiter-Button oder den Schließen-Button, wird abgelehnt.
• @keyframes-Namen, die das Quiz selbst nutzt, etwa spin, pulse oder Namen, die mit advisor- beginnen, werden abgelehnt. Wähle einen eigenen Namen wie brand-fade.
• @import wird beim Speichern des Themes entfernt.

Gut zu wissen

• Der Code gehört zum Theme und ändert damit jedes Quiz, das dieses Theme nutzt. Er ist nicht Teil einer Quiz-Version, du musst ihn also nicht veröffentlichen. Die Vorschau zeigt Änderungen sofort, live geschaltete Quizze übernehmen sie innerhalb von etwa einer Stunde. Willst du etwas nur an einem Quiz ausprobieren, kopiere das Theme zuerst. Siehe Theme und Layout des Quiz anpassen.
• Sobald ein Theme eigenen Code hat, wird die Kopfzeile über dem Quiz transparent, damit dein Hintergrund bis nach oben reicht. Gib .bb-q-header-bar einen Hintergrund, wenn du eine durchgehende Leiste willst.
• Beim ersten Laden zeigt eine Startseite oder Frage mit Vorlage kurz den Hintergrund des Themes, bis der Code der Vorlage geladen ist.
• Custom code funktioniert auf Shopify, WooCommerce, Magento und CCV Shop gleich, weil das Quiz auf jeder Plattform in einem eigenen Rahmen läuft.