Choice and text

MC Populated Blank

Fill a sentence blank by picking a choice.

Delivery

Respond, review and evaluate

Authoring

Visual editor available

Print view available

A short passage titled "The Dog" ("The brown dog ran to the park. I gave it a stick. The dog sat down.") above the question "Pick a word that describes the dog." with a blank line and three radio-button choices: brown, ran and gave. — MC Populated Blank example

Try the interaction

Live example: @pie-element/mc-populated-blank@0.3.4 · players 1.0.0-beta.5.

Open all examples for this element →

Use it in an item

Map the tag to an exact package version and match the model ID to the markup. The item player loads the views. You can use any frontend framework.

{
  "elements": {
    "mc-populated-blank": "@pie-element/mc-populated-blank@0.3.4"
  },
  "markup": "<mc-populated-blank id=\"example\"></mc-populated-blank>",
  "models": [
    {
      "id": "example",
      "element": "mc-populated-blank",
      "prompt": "<div><p class=\"iat-align-center\"><strong>The Dog</strong></p><p>The brown dog ran to the park. I gave it a stick. The dog sat down.</p></div>",
      "template": "<span>Pick a word that describes the dog.</span> {{blank}}",
      "choiceMode": "text",
      "choices": [
        {
          "id": "choice-A",
          "labelHtml": "<div><p><span class=\"iat-text-large\">brown</span></p></div>"
        },
        {
          "id": "choice-B",
          "labelHtml": "<div><p><span class=\"iat-text-large\">ran</span></p></div>"
        },
        {
          "id": "choice-C",
          "labelHtml": "<div><p><span class=\"iat-text-large\">gave</span></p></div>"
        }
      ],
      "correctChoiceId": "choice-A",
      "hasAudio": false,
      "interactionMode": "populate_blank",
      "layoutProfile": "inline_sentence",
      "customType": "sel_r1-g_plusggg",
      "choiceLayout": "horizontal",
      "locale": "en_US"
    }
  ]
}

Embed an item · Embed authoring · Print integration

Responses and scoring

The controller defines scoring for this element. Browser scoring returns one outcome per element. Your application combines those outcomes into an item score and handles trusted server scoring.

Scoring, partial credit and rubrics →

Model, configuration and session reference

The model holds content, configuration controls the editor, and the session holds the response. Fields below come from generated JSON Schemas.

Schema version: @pie-element/mc-populated-blank@0.3.6. Example version: 0.3.4. Use the schema matching your content. Schema checks cover data structure; controller validation checks authoring rules.

model fields (34)

Field	Type	Meaning	Default / values
`id`Required	`string`	Identifier to identify the Pie Element in html markup, Must be unique within a pie item config.	`—`
`element`Required	`string`	The html Element tag name: the key in the item config's `elements` map, e.g. "multiple-choice"	`—`
`accessibilityCatalogs`	`array`	QTI-aligned accessibility catalogs whose cards dock to content nodes by `data-catalog-idref`	`—`
`prompt`	`string`	The question prompt or item stem	`—`
`promptEnabled`	`boolean`	Determines if prompt should show	`—`
`interactionMode`	`McpbInteractionMode`	How the learner answers	`"populate_blank"`
`layoutProfile`	`string`	Selects the arrangement: `inline_sentence`, `audio_blank_only`, `token_sequence` or `stimulus_image_blank`; unset is block flow in DOM order. Lands on the root as `layout-<layoutProfile>`.	`—`
`choiceLayout`	`string`	The choices' direction, `horizontal` or `vertical`. Unset, choices are horizontal when the template is only `{{blank}}` or `interactionMode` is `audio_mc_only`, and vertical otherwise.	`—`
`layoutProfilePresets`	`object`	Layout limits keyed by `layoutProfile`, merged over the bundled preset of that name. Delivery applies the current profile's preset over `layoutLimits`.	`—`
`layoutLimits`	`object`	Numeric visual constraints, each a positive number; a key left out takes the CQT-tuned default	`—`
`audioButtonSkin`	`union`	The listen button's images when `audioButtonSkinsByLocale` has none for the locale	`—`
`audioButtonSkinsByLocale`	`object`	The listen button's images keyed by lower-case `locale`, its two-letter language, or `default`, tried in that order	`—`
`sentenceHtml`	`string`	A sentence or stimulus (HTML) rendered between the audio and the template	`—`
`template`	`string`	The sentence (HTML); with `populate_blank` it holds exactly one `{{blank}}`	`—`
`choiceMode`	`McpbChoiceMode`	Whether the choices are text or images	`"text"`
`choices`	`array`	The choice options for the question	`—`
`choiceGroupLabel`	`string`	The choice group's accessible name when the item has no prompt to label it.	`—`
`correctChoiceId`	`string`	The `id` of the correct choice	`—`
`hasAudio`	`boolean`	Indicates if the item plays `audioUrl`	`—`
`autoplayAudioEnabled`	`boolean`	Indicates if the audio plays when the item loads	`—`
`autoplayAudioHeld`	`boolean`	Set by the player when the host holds autoplay; it outranks `autoplayAudioEnabled`	`—`
`completeAudioEnabled`	`boolean`	Keeps the item incomplete until the audio has played to the end	`—`
`audioUrl`	`string`	The audio prompt's URL; required when `hasAudio` is set	`—`
`audioTranscript`	`string`	Transcript text for the audio prompt. Not rendered by delivery: on `pie-section-player` the toolkit renders it from the item's accessibility catalog, gated by the learner's profile (PIE-902). It stays on the model for the print view, which has no toolkit, and renders it unconditionally until print resolves catalogs itself (PIE-904), and as the source the pie-api-aws import writes the card from.	`—`
`useFeatureButtonAudio`	`boolean`	`true` plays the audio from the listen button, `false` from native audio controls. Unset, the `audio_blank_only`, `stimulus_image_blank` and `token_sequence` layouts use the listen button.	`—`
`locale`	`string`	Picks the audio button skin; also the learner-facing strings' language when `language` is unset.	`—`
`language`	`string`	The learner-facing strings' language, as `@pie-lib/translator` reads it (`en_US`, `es_ES`, …).	`—`
`lockChoiceOrder`	`boolean`	`false` shuffles the choices for a student; unset or `true` keeps the authored order.	`—`
`shuffle`	`boolean`	The older spelling of `lockChoiceOrder: false`, read only when `lockChoiceOrder` is unset. Deprecated: Use `lockChoiceOrder`.	`—`
`teacherInstructions`	`string`	Indicates teacher instructions	`—`
`teacherInstructionsEnabled`	`boolean`	`false` hides `teacherInstructions`; unset shows them, as in multiple-choice.	`—`
`printAnswerKey`	`boolean`	`false` leaves the answer key out of an instructor's printout; a student's never has it.	`—`
`customType`	`string`	The CQT `custom_type` whose bundled variant stylesheet applies, e.g. `sel_r1-_plusggg`	`—`
`source`	`object`	Provenance metadata from the content import; the element does not read it.	`—`

Named object types

AccessibilityCatalog

Field	Type	Meaning	Default / values
`identifier`Required	`string`	See the named type or the example model.	`—`
`cards`Required	`array`	See the named type or the example model.	`—`

CatalogCard

Field	Type	Meaning	Default / values
`catalog`Required	`string`	See the named type or the example model.	`—`
`language`	`string`	See the named type or the example model.	`—`
`content`	`string`	See the named type or the example model.	`—`
`payload`	`CatalogCardPayload`	See the named type or the example model.	`—`

SignLanguageCardPayload

Field	Type	Meaning	Default / values
`signLang`	`string`	Language tag for the signed translation — BCP 47, which admits ISO 639-3 subtags for languages with no 639-1/2 code. "ase" is ASL, matching QTI 3 `xml:lang`. This is the language of the adaptation, not the item's base content language (AfA/PNP's `languageOfAdaptation`). The distinction is load bearing: a Spanish item's signed alternate is LSM, not ASL, so `signLang` must never be inferred from the item or assessment content language. Optional, and redundant on almost every card. The card's `language` states the same code and is the only field pie-players resolves a card on — resolution runs before anything knows the card is a signing card, so it can only key on the generic field — and the player falls back to it when this is absent. Author it only where the two differ: a card tagged with the item's content language (`language: 'en-US'`, `signLang: 'ase'`) so resolution reaches it by the default-language rung. The pie-api-aws importer emits `language` alone.	`—`
`media`Required	`MediaAssetRef`	See the named type or the example model.	`—`
`fragment`	`MediaFragmentRange`	See the named type or the example model.	`—`

MediaAssetRef

Field	Type	Meaning	Default / values
`version`Required	`number`	See the named type or the example model.	`—`
`id`Required	`string`	See the named type or the example model.	`—`
`kind`Required	`MediaKind`	See the named type or the example model.	`—`
`sources`Required	`array`	See the named type or the example model.	`—`
`poster`	`string`	See the named type or the example model.	`—`
`thumbnail`	`string`	See the named type or the example model.	`—`
`durationSeconds`	`number`	See the named type or the example model.	`—`
`tracks`	`array`	See the named type or the example model.	`—`
`transcript`	`TranscriptRef`	See the named type or the example model.	`—`
`label`	`string`	See the named type or the example model.	`—`
`description`	`string`	See the named type or the example model.	`—`
`lang`	`string`	Language of the asset itself, as authored metadata. Sign-language cards leave it unset: the card's `language` already states the adaptation language, and a second copy is a second thing to keep in agreement.	`—`

MediaSource

Field	Type	Meaning	Default / values
`src`Required	`string`	See the named type or the example model.	`—`
`type`	`string`	MIME type, e.g. "video/mp4".	`—`
`width`	`number`	See the named type or the example model.	`—`
`height`	`number`	See the named type or the example model.	`—`
`bitrate`	`number`	See the named type or the example model.	`—`

TextTrackRef

Field	Type	Meaning	Default / values
`src`Required	`string`	See the named type or the example model.	`—`
`kind`Required	`string`	See the named type or the example model.	`—`["captions","subtitles","descriptions","chapters","metadata"]
`lang`Required	`string`	See the named type or the example model.	`—`
`label`Required	`string`	See the named type or the example model.	`—`
`default`	`boolean`	See the named type or the example model.	`—`

TranscriptRef

Field	Type	Meaning	Default / values
`src`	`string`	See the named type or the example model.	`—`
`html`	`string`	See the named type or the example model.	`—`
`plainText`	`string`	See the named type or the example model.	`—`
`lang`	`string`	See the named type or the example model.	`—`

MediaFragmentRange

Field	Type	Meaning	Default / values
`startSeconds`Required	`number`	See the named type or the example model.	`—`
`endSeconds`	`number`	See the named type or the example model.	`—`

SpokenAudioCardPayload

Field	Type	Meaning	Default / values
`media`Required	`MediaAssetRef`	See the named type or the example model.	`—`
`fragment`	`MediaFragmentRange`	See the named type or the example model.	`—`

McpbAudioButtonSkin

Field	Type	Meaning	Default / values
`silentUrl`Required	`string`	Image URL for the button while the audio is not playing	`—`
`playingUrl`Required	`string`	Image URL for the button while the audio plays	`—`

McpbChoice

Field	Type	Meaning	Default / values
`id`Required	`string`	Identifier of the choice, unique within the item; the session stores the picked one	`—`
`labelHtml`	`string`	The choice's content (HTML), shown when `choiceMode` is `text`	`—`
`imageUrl`	`string`	The choice's image (URL), shown when `choiceMode` is `image`	`—`
`imageAlt`	`string`	Text alternative for `imageUrl`	`—`

Open the complete JSON Schema

configuration fields (4)

Field	Type	Meaning	Default / values
`prompt`	`McpbFieldConfigure`	Configuration for the prompt; `settings` and `label` are not read	`—`
`teacherInstructions`	`McpbFieldConfigure`	Configuration for the teacher instructions; `settings` and `label` are not read	`—`
`minAnswerChoices`	`number`	The fewest choices `validate()` accepts	`2`
`maxAnswerChoices`	`number`	The most choices `validate()` accepts; unset allows any number	`—`

Named object types

McpbFieldConfigure

Field	Type	Meaning	Default / values
`settings`	`boolean`	Indicates if the item has to be displayed in the Settings Panel	`—`
`label`	`string`	Indicates the label for the item that has to be displayed in the Settings Panel	`—`
`required`	`boolean`	Indicates if the item is required and the value cannot be empty	`—`

Open the complete JSON Schema

session fields (9)

Field	Type	Meaning	Default / values
`id`	`string`	Identifier of the session	`—`
`element`	`string`	The element the session belongs to	`—`
`value`	`array`	The picked choice id in a one-entry array, as multiple-choice stores it.	`—`
`choiceId`	`string`	Where older sessions hold the pick; read, never written. Deprecated: Sessions hold the pick in `value`.	`—`
`audioStartTime`	`number`	When the first playback of the audio started (epoch milliseconds)	`—`
`audioEndTime`	`number`	When the first playback of the audio ended (epoch milliseconds)	`—`
`waitTime`	`number`	Milliseconds from `audioStartTime` to `audioEndTime`	`—`
`shuffledValues`	`array`	The choice ids in the order a student saw them when `lockChoiceOrder` is `false`	`—`
`data`	`object`	Where some sessions hold `shuffledValues`; read in preference to the root key	`—`

Open the complete JSON Schema

How to use the schemas →

Accessibility and content requirements

PIE targets WCAG 2.2 AA. Provide clear prompts and media alternatives, and test the question with a keyboard and assistive technology. Manual testing is still incomplete; see the coverage notes below.

Accessibility and evidence · Element evidence and manual checks(opens in new tab)

Element package source(opens in new tab) · Example source(opens in new tab) · Snapshot cb30a68f