Skip to main content
Docs: Integration

Integration

PIE renders and runs assessment content in the browser. The host application owns the content, the learner record and the policy around them, and assembles its player from PIE's building blocks in one of four patterns.

Integration patterns

Item player

<pie-item-player> alone

One item in a page: authoring, previews, practice.

Item player

Item player with toolkit

<pie-assessment-toolkit> around a <pie-item-scope> per item, with <pie-item-toolbar>

Items rendered one at a time, with tools and accommodations.

Example

Section player

A layout element with runtime and section

A section screen: passages, items, section tools, section session.

Section player

Custom assessment player

Section players, one coordinator per assessment, the assessment-session helpers

Multi-section delivery with the host's routing, persistence and submission.

Example

Authoring (mode="author") and print (<pie-print>) use the item player and the print player on their own; Players covers both.

Item player with toolkit

<pie-assessment-toolkit> needs no section. Each <pie-item-scope> registers its item and the item's settings with the coordinator the toolkit builds from its properties; the toolbar inside the scope renders the placed tools, and the tools act on the scope's [data-region="content"]. The item player's events pass through the scope unchanged, and the session stays the item player's.

Item player with the toolkit: the host sets tools, toolRegistry, toolContextResolvers and assessment on a pie-assessment-toolkit and receives runtime-ready with the coordinator. A pie-item-scope per item registers the item and its settings with the coordinator; its item toolbar takes tool policy and services from the coordinator, and the tools act on the content region that holds the item player.

The first scope that registers starts the coordinator from the toolkit's inputs at that moment. runtime-ready carries the coordinator once it exists, and coordinator.waitUntilReady() resolves once saved tool state has loaded and text-to-speech has started, unless it starts lazily. toolkit-ready and section-ready belong to a bound section and do not fire here.

Custom assessment player

A custom assessment player mounts a section player per section with one coordinator for the whole assessment, keeps the attempt in an AssessmentSession, and persists through the coordinator's hooks against the host's backend. Construct a coordinator when the host needs the services directly; otherwise the section player builds one from runtime.tools. Coordinator hooks exist only on a host-built coordinator, because they must be in place before the first section controller exists.

A coordinator the host passes stays the host's: a layout disposes only a coordinator it built. The coordinator's subscribeItemEvents and subscribeSectionLifecycleEvents follow the active section across navigation. createNewAssessmentSession, upsertSectionSession and setCurrentSectionPosition keep the section sessions and the current position in the attempt, which the host stores.

The reference assessment player assembles this pattern from the same public exports, with navigation, a cancelable assessment-navigation-requested event and submission; read it as a pattern for a host's own player.

Assessment player README(opens in new tab) · Reference assessment player

What PIE and the host own

The players and the toolkit run the assessment in the browser; the host owns durable data and policy. The host stores what the players report, through session-changed, getSession() and the persistence hooks, and decides navigation between sections.

PIE in the browser, with the players, the assessment toolkit and the elements, next to what the host application and its servers own: item bank, sign-in, administration, session storage, scoring and reporting. Item config, env and the saved session flow into PIE; session-changed and saveSession() flow out to the host.

PIE

  • Rendering: items, passages and rubrics with their layout, styling and behavior
  • Composition: items, passages and tools composed into section layouts
  • Interaction: learner responses captured through accessible interfaces
  • Authoring: each element's configuration UI
  • Accessibility: the WCAG 2.2 AA target, keyboard support, screen reader compatibility
  • Tools and accommodations: calculators, text-to-speech, annotation, color schemes, tool policy
  • Session lifecycle: hydration, persistence through host strategies, and session change events

The host

  • Item storage: the item bank or CMS that stores item configs as JSON
  • Authentication and authorization: users, permissions, sign-in
  • Assessment administration: assignments, time limits, attempt counts
  • Session storage: the sessions the players report, stored through the persistence hooks or from session-changed
  • Scoring: for graded delivery, the element controllers run on your server under hosted delivery
  • Reporting: score reports and analytics

Controller API

Players are custom elements and work in any framework. Object inputs — config, runtime, section, session, toolRegistry — are set as JS properties; attributes carry strings.

The layouts' DOM events — pie-stage-change, pie-loading-complete, toolkit-ready, framework-error, session-changed, composition-changed — are the lifecycle contract. In-section change arrives through the SectionController's typed subscribe() stream, or through the coordinator's subscribeItemEvents and subscribeSectionLifecycleEvents, which follow the active section across navigation.

waitForSectionController(timeoutMs) resolves with the controller, or null at the timeout; getSectionController() returns null while the controller is pending. hydrate() reloads from the persistence strategy on demand, and getSession() is the snapshot to store. Persistence strategies implement loadSession(ctx), saveSession(ctx, session) and optionally clearSession(ctx), keyed by assessment, section and attempt.

DOM events carry the lifecycle, errors and each item session as it changes. The controller carries the section's state — current item, visited items, completion — through its subscribe() stream and getSession().

Section player integration guide(opens in new tab) · Section player README(opens in new tab)

Delivery and scoring

By default the whole item config reaches the browser, answer keys included, and the element controllers run there. That fits practice and formative delivery. Graded delivery runs the controllers on a server instead; Security sets out what it takes.

Delivery backend

A delivery backend answers four operations: load, saveSession, model and score. The built-in client speaks the PIE API service's player routes; a host with another backend supplies its own client. The section player configures it once in its runtime and derives each embedded item player's backend from it; a hosted player cannot score in the browser, so formative delivery needs an unhosted one.

Element controllers

model(question, session, env, updateSession) turns the authored model into the view model an element renders. outcome(model, session, env) resolves to { score, empty } with a score from 0 to 1; feedback and correctness reach the learner through model() in evaluate mode.

env carries mode (gather collects responses, view shows them read-only, evaluate shows correctness and feedback) and role (student or instructor); controllers also read lockChoiceOrder and partialScoring.

Where the controller runs · Security(opens in new tab) · Element contract(opens in new tab)