PRC Quiz Builder

Canonical docs: docs/plugins/prc-quiz-builder/

An interactive, block-based quiz system for the PRC platform.

Overview

Quiz Builder provides a custom quiz post type and a suite of Gutenberg blocks backed by the WordPress Interactivity API. Authors compose quizzes in the block editor using a Controller → Pages → Page → Question → Answer hierarchy; the Controller block injects all runtime state into the Interactivity API context and coordinates submission, scoring, and results display on the frontend. The plugin supports three quiz modes (scored quiz, typology/clustering, freeform), three display types (paged, scrollable, and fluid), community group results, and iframe-embeddable views.

Firebase Realtime Database is the persistence layer for archetype (result) records and community groups. WordPress post meta tracks submission analytics.

Dependencies

• Upstream: prc-platform-core (provides \PRC\Platform\Firebase and the prc_api_endpoints, prc_platform_on_post_init, and prc_iframe_content hooks), prc-research-teams (optional — registers team-prefixed quiz URLs via prc_research_teams_rewrite_config), WP Consent API (wp_add_cookie_info)
• Downstream: Internal analytics tooling queries the _submissions REST field on the quiz post type; any page embedding a quiz via /embed/ or /iframe/ URLs

Architecture

The plugin bootstraps through includes/class-plugin.php, which loads all dependencies, registers the quiz CPT, sets up rewrite rules, and instantiates each block class. Blocks are loaded from build/ (production) or src/ (local/dev), controlled by wp_get_environment_type().

Archetype lookups are cached in the WordPress object cache (prc_quiz_builder_archetypes group, 1-day TTL) and backed by Firebase. Community groups are stored only in Firebase; Groups::get_group() reads from Firebase.

The Controller block's render_callback is the key server/client bridge: it writes all runtime context (quizId, quizType, displayType, configuredDisplayType, allowSubmissions, groupId, archetype, etc.) into data-wp-context and wires up all Interactivity API directives. configuredDisplayType is an immutable copy of the author's displayType setting; displayType may be rewritten at runtime (e.g. fluid → scrollable on narrow viewports). Core/buttons blocks that carry specific CSS classes (prc-quiz-start-button, prc-quiz-next-page-button, prc-quiz-submit-button, etc.) have data-wp-on--click attributes injected server-side via WP_HTML_Tag_Processor.

Key Files

Blocks

Quiz blocks appear in the block inserter only when editing the quiz post type, grouped under the Quiz Builder category (prc-quiz slug). The Quiz embeddable block (prc-quiz/embeddable) remains available on other post types for synced cross-post reuse.

Knowledge quiz features (type: quiz)

These options apply only when the Controller type is quiz (not typology or freeform).

Live feedback and answer lock

Enable Live Feedback on the Controller block. After a participant selects an answer on a single-choice or thermometer question, the UI shows whether the choice is correct or incorrect and locks further changes on that question. Multiple-choice questions stay open so participants can select every required answer before locking.

Live feedback is implemented in src/answer/view.js via context.liveFeedback and state.isQuestionLocked.

Answer correctness tri-state

Knowledge-quiz answers use a tri-state correct attribute:

The toolbar control lives in src/answer/correct-toggle.js. Freeform quizzes hide the control.

Question outcome

getQuestionOutcome() (src/controller/question-outcome.js) resolves each question to correct, incorrect, unsure, or unanswered:

• Correct — selected UUIDs exactly match every answer marked correct: true
• Unsure — only correct: null answers are selected (no wrong or right answers)
• Incorrect — any other non-empty selection
• Unanswered — no selection

The Results block exposes a Correct / Incorrect block bit (prc-quiz-builder/question-outcome-label) that prints the active question outcome from context. Labels come from the Quiz Controller (Correct / Incorrect / Not sure outcome label settings) and can be overridden per bit in the bit insert/edit popover. Empty bit fields inherit the quiz-wide defaults.

Any core/paragraph or core/heading that contains this bit receives the class has-prc-quiz-question-outcome and the interactive class is-awaiting-selection while the question is unanswered, so the whole host block stays hidden until the user has a selection.

Progress Circles use the same outcome logic for per-question marks.

Exclusive score buckets

The Controller Score Buckets panel stores a JSON catalog of named, non-overlapping closed ranges ([min, max] inclusive; shared endpoints count as overlap). Validation runs in the editor via validateExclusiveBuckets() (src/controller/score-buckets.js).

At results time, matchScoreBucket() returns the first bucket containing the participant's score. Insert the Matching Score Bucket block bit (prc-quiz-builder/matching-score-bucket) in the Results block to print the matched label.

Progress bar variations

prc-quiz/progress-bar has two block variations:

Circles reflect live outcomes when Live Feedback is enabled; otherwise they show answered vs unanswered.

Display Types and Frontend Behavior

The Controller block's displayType attribute accepts paged, scrollable, or fluid. Runtime behavior is implemented in src/controller/view.js and src/page/view.js.

Fluid resolution

A fluid quiz resolves to a concrete display mode by viewport width (782px breakpoint, matching the block editor's mobile preview). Resolution runs on init and re-runs on window resize via actions.applyDisplayType (data-wp-on-async-window--resize on the Controller when displayType is fluid):

configuredDisplayType retains the original fluid value so client logic can distinguish a fluid quiz that resolved to scrollable from a natively scrollable quiz, and so resize handlers can re-resolve without losing the fluid configuration.

Page visibility (displayPages)

The Pages block binds hidden to !state.displayPages (src/pages/class-pages.php). Visibility rules:

Native scrollable quizzes keep pages visible on results URLs so inline, submit-as-you-go results can render below the questions. Fluid quizzes on mobile hide pages when landing on a results URL so users are not dropped at the top of the question stack.

Navigation buttons

Quiz action buttons are core/buttons block variations patched with Interactivity API click handlers:

Submission behavior

Submission is controlled by the allowSubmissions Controller attribute and the active display type:

When submissions are enabled, scrollable and fluid-on-mobile quizzes require a prc-quiz-submit-button on the last page. Quizzes with submissions disabled and a native scrollable display type advance to results automatically once the answer threshold is met.

Results display scroll

When results become visible, onResultsDisplay in src/results/view.js scrolls the results block into view (scrollIntoView with block: 'start'). This applies to all display types, including fluid quizzes on mobile: after submit, question pages hide and the viewport moves to the top of the results block so users are not left scrolled to the middle of the page.

Hooks & Filters

REST API

All endpoints are registered through the platform's prc_api_endpoints filter. Public write endpoints validate the quiz post (exists, quiz post type, published) and apply per-IP rate limiting on submit.

The quiz REST resource also exposes a _submissions field containing the _report post meta (requires edit_posts capability).

WP Abilities API

WP-CLI

Requires manage_options. All mutation subcommands support --dry-run.

# Inspect report
wp prc quiz report get --quiz-id=313764

# Backfill from Firebase (delta mode adds firebase_hits - current_total)
wp prc quiz report sync-firebase --quiz-id=313764 --year=2026 --month=06 --dry-run
wp prc quiz report sync-firebase --quiz-id=313764 --year=2026 --month=06

# Manual correction
wp prc quiz report add --quiz-id=313764 --year=2026 --month=06 --month-count=500 --total=500
wp prc quiz report set --quiz-id=313764 --year=2026 --month=06 --month-count=125653 --total=125653

sync-firebase loads the full quiz/{id}/archetypes node; large quizzes may be slow. first_24_hours and first_week are not modified by these commands.

URL Patterns

Research-team-prefixed variants (e.g. /politics/quiz/{slug}/...) follow the same sub-patterns, registered via prc_research_teams_rewrite_config.

Data Storage

Cookies

Both cookies are registered with WP Consent API as functional, 30-day expiry.

Admin: Quizzes DataViews list

Quizzes → All Quizzes opens a DataViews screen (prc-quiz-builder-library) instead of the classic edit.php list table. The list reads mirrored post meta (_prc_quiz_type, _prc_quiz_display_type, _prc_quiz_groups_enabled, _prc_quiz_question_count) synced on save because quiz configuration lives in block attributes inside post_content.

• Open analytics for a quiz from the list actions (same modal as the editor inspector sidebar).
• Escape hatch: append ?classic=1 to edit.php?post_type=quiz to use the classic list table (Trash and other status views redirect with the same filter preserved).

Implementation: includes/class-quiz-list.php + GET quiz/library (via prc_api_endpoints).

Local Development

# From the monorepo root:
npx turbo build --filter=@prc/quiz-builder
npm run start -w @prc/quiz-builder

To run Playwright tests (from the monorepo root — VIP dev-env and Playwright are all centralized at root):

npm run vip:start
npm test -- tests/prc-quiz-builder/e2e/

Firebase availability

Archetype persistence and community groups require Firebase Realtime Database. Archetypes::is_available() and Groups guard all writes when prc-firebase is not configured or the service account is missing.

Submit behavior when Firebase is down

Group creation (quiz/create-group) returns HTTP 503 when Firebase Auth is unavailable.

Local Firebase setup

Service account generation is documented in docs/dependency-auth.md (npm run gen:firebase-sa). prc-firebase reads WPCOM_VIP_PRIVATE_DIR/firebase-service-account.json.

Troubleshooting

Blocks not appearing after a build

Symptom: prc-quiz/controller (or any quiz block) is missing from the editor or throws a "block is invalid" error.
Cause: load_blocks() globs build/*/ for block directories and calls include_block() on each. If a compiled PHP file is missing from build/{block-name}/class-{block-name}.php, the error is logged but swallowed silently — the block just won't register.
Fix: Run npx turbo build --filter=@prc/quiz-builder and confirm PHP files exist under build/. Check PHP error logs for Block missing. entries.

Quiz submissions failing silently

Symptom: Users complete a quiz but results don't persist; the submit endpoint returns a 403, 404, 429, or generic error.
Cause: Rest_API::$rest_disabled may be flipped to true (emergency kill switch in class-rest-api.php), the quiz post may be unpublished or missing, or the per-IP rate limit (100 submissions per quiz per minute) may be exceeded.
Fix: If the kill switch is active, set $rest_disabled = false and redeploy. Confirm the quiz post is published. For 429 responses, wait and retry or investigate abusive traffic.

Group quizzes fail with 503

Symptom: Group submit or create-group returns "results service is temporarily unavailable."
Cause: Firebase Realtime Database or Auth is not configured (private/firebase-service-account.json missing locally, or deploy injection skipped).
Fix: Run npm run gen:firebase-sa locally; confirm prc-firebase loads the service account on the target environment. Normal (non-group) quizzes may still return in-session results with persisted: false.

Inspector sidebar panel not loading

Symptom: No quiz analytics panel appears in the block editor sidebar.
Cause: Inspector_Sidebar_Panel::enqueue_block_plugin_assets() only enqueues on screens where $screen->post_type === 'quiz'. It also checks is_admin(). Opening the editor from a non-quiz post type silently skips enqueue.
Fix: Confirm you are editing a quiz post type, not a page or another CPT that embeds the quiz via prc-quiz/embeddable.