Atoms

An atom is one thing on a screen: a paragraph, a question, a picture, a button, an exercise. A sequence puts atoms on its pages; a journey can also give one atom to a participant on its own (a user atom).

An atom is published as it is saved: every save is its next version, and there is no draft. Its type is fixed once it exists, and decides three things together: what the participant sees, which config keys it takes (an unknown key is refused), and what a response stores.

The types

Type	What the participant does	What a response stores
content	Reads markdown	nothing
asset	Looks at, watches or listens to a file	nothing
embed	Watches something hosted elsewhere	nothing
button	Taps through to somewhere else	true, once tapped
text	Writes in their own words	the text, trimmed; nothing when empty
number	Types a figure	a number
slider	Picks a point on a scale	a number
single_select	Picks one option	the option's value
multi_select	Picks any number of options	the values, in authored order
boolean	Answers yes or no	true or false
datetime	Picks a date, a time or both	a string in the mode's shape
blood_pressure	Types a systolic and a diastolic reading	{ systolic, diastolic } in mmHg
breathing	Does a paced breathing practice	the rounds completed and the seconds spent
kinestex	Does a KinesteX workout, the phone's camera counting and correcting	KinesteX's summary of the workout, as it reports it

Words on the screen

• name is never shown to a participant. The prompt is label, rich text above the control. An atom whose question went into name shows a control with nothing above it.
• Only content puts prose on a page. For a paragraph above a question, put a content atom above it on the same page.
• code is how copy quotes the atom, so an atom without one can't be quoted (below).

Behaviour by type

• asset and embed play by the file's address, not a setting: an image address draws inline; a YouTube or Vimeo address opens a player; an audio address gets a listen row; anything else opens a direct player. A library file must be public and finished uploading, or the write is refused. Write alt every time.
• button, breathing and kinestex are each one button, drawn the same way: text, icon and variant (primary or secondary), green with a tick once done. None shows a label. A button needs its text; a breathing or kinestex without one reads "Start breathing exercise" or "Start workout".
• button with a web address opens the browser and leaves the sequence open; with an app:// address it moves to that tab and closes the sequence, keeping the responses so far. A tap records a response, so a button satisfies a required page.
• text: default fills the box in advance, and the participant can edit it. maxLength caps the length; format (email, url or number) sets the keyboard and refuses a value of another shape when the participant moves on.
• number: a figure outside min–max, or off the step grid counted from min, is refused when the participant moves on. unit is a label; nothing converts.
• slider: min and max are required. minLabel and maxLabel are shown under each end. The thumb starts at default, or at min; a slider nobody touched stores nothing, so set required where the response must be given.
• single_select, multi_select, boolean: options show in the order written, there and on Progress, so reorder only before anyone has responded. default pre-selects an option on single_select and boolean. multi_select takes minSelections and maxSelections. A boolean's two labels are what the participant reads; the stored value stays true or false.
• datetime: the bounds compare as text, so write them in exactly the shape the mode stores.
• blood_pressure takes no settings: the fields and their plausible ranges are fixed, and a systolic at or below the diastolic is refused. It is recorded, never interpreted or alerted on.
• breathing runs rounds of inhale, hold and exhale (inhaleSecs, holdSecs, exhaleSecs); pattern names the practice under the orb. Leaving early records what was done.
• kinestex names its workout, the id of a workout in the tenancy's KinesteX account; the editor searches the account's workouts by title. The tenancy needs that account set up first; without it the workout shows as unavailable. Leaving before the workout's summary records nothing.

Knowledge questions

An option on a single_select, multi_select or boolean can be marked correct and carry feedback. Once answered, the question shows whether it was right, marks the right options, and shows the feedback of every option picked or right; it then takes no more taps. A multi_select is right only with exactly the right options. correct doesn't score: give the right options their points too, and make the pass mark a band.

Quoting earlier answers

A {{ }} token in any text an atom shows (its label, a content body, an option's label or feedback, a placeholder, a slider's end labels, a button's text) is filled on the phone with something about the participant: an answer earlier in the same sitting (atomResponses.<atom>.current), one from another day, an extra, their first name. What can be named, how it reads and its fallback are in Referencing a participant's data.

Responses

Responses are added, never overwritten: a correction is a new response, and the earlier one stays. With defaultRevisable: false a response is fixed once given, and a change is refused with response_not_revisable.