Tasks and steps

A task is an ordered list of steps that the participant works through, and a step is one screen of it. RPUITask shows a task one step at a time and collects one result for the whole run. See Running tasks.

Research Package has these step types:

Task classes

RPUITask shows two task classes:

Both take these parameters:

For navigation rules, see Branching.

Three rules apply when you build a task:

• Unique identifiers: the result keys each step result by step identifier, so two steps with one identifier share one entry.
• One object per step: RPOrderedTask finds the next step by the position of the current one in the list. A step object that appears twice makes the task loop.
• A new task for each run: some objects change while a task runs. A free-text choice stores the typed text in the task, and a reorganizer rule rewrites the step list.

Common step fields

Every step class extends RPStep, which has these fields:

Each of these texts can be a translation key or plain text. A step shows the translation when one exists, and the text as written otherwise. See Localization.

Only RPStep and RPInstructionStep take nextButtonText as a constructor parameter. For other steps, set it with a cascade:

final readyCheck = RPQuestionStep(
  identifier: 'readyCheck',
  title: 'Are you in a quiet place?',
  answerFormat: RPChoiceAnswerFormat(
    answerStyle: RPChoiceAnswerStyle.SingleChoice,
    choices: [
      RPChoice(text: 'Yes', value: 1),
      RPChoice(text: 'No', value: 0),
    ],
  ),
)..nextButtonText = 'Start the test';

Instruction step

RPInstructionStep shows information without asking anything: a title, a text and optionally an image, a video or an audio player. NEXT is enabled from the start, and the step records no result.

An instruction step with a recording and a Learn more page:

final intro = RPInstructionStep(
  identifier: 'intro',
  title: 'Breathing exercise',
  text: 'Listen to the recording, then answer three questions.',
  detailText:
      'The recording guides you through four minutes of slow breathing.',
  audioPath: 'audio/breathing.mp3',
  footnote: 'Recording by the study team',
);

The three media paths take either an asset path or an http or https URL. For an asset, the image and the video take the full asset key, and the audio takes a path relative to assets/:

Neither the video nor the audio starts by itself. To add the files to your app, see Add media and sound assets.

Question step

RPQuestionStep asks one question. Its answer format decides what the participant enters and what type the answer has. See Answer formats.

A question that the participant may skip:

final sleepHours = RPQuestionStep(
  identifier: 'sleepHours',
  title: 'How many hours did you sleep last night?',
  answerFormat: RPIntegerAnswerFormat(
    minValue: 0,
    maxValue: 24,
    suffix: 'hours',
  ),
  optional: true,
  footnote: 'Do not count naps.',
);

The screen shows the question and the input of the answer format. NEXT is enabled while the question has a valid answer. The step records an RPStepResult with the answer under the key answer, and Skip this question records one whose answer is null.

Form step

RPFormStep shows several questions on one scrolling page, each with its own answer format. Use it for questions that belong together, such as demographics.

A form with one required and one optional question:

final aboutYou = RPFormStep(
  identifier: 'aboutYou',
  title: 'About you',
  questions: [
    RPQuestionStep(
      identifier: 'age',
      title: 'How old are you?',
      answerFormat: RPIntegerAnswerFormat(
        minValue: 18,
        maxValue: 110,
        suffix: 'years',
      ),
    ),
    RPQuestionStep(
      identifier: 'occupation',
      title: 'What is your occupation?',
      answerFormat: RPTextAnswerFormat(hintText: 'For example, nurse'),
      optional: true,
    ),
  ],
);

The form behaves as follows:

• NEXT is enabled once every question that is not optional has an answer. In a form whose questions are all optional, it is enabled after the first answer.
• From each question, the form uses only identifier, title, answerFormat and optional. The autoSkip, timeout and footnote of a question have no effect inside a form.
• forceWait works only together with autoSkip. Without the countdown, NEXT never becomes enabled.
• The form records one RPStepResult under its own identifier, which holds one RPStepResult per question. For the result of this form, see JSON format.

Timer step

RPTimerStep makes the participant wait, for example between two exercises. It shows the title and the remaining time as minutes and seconds, and it enables NEXT when the countdown reaches zero. The step records no result.

A two-minute rest that moves on by itself:

final rest = RPTimerStep(
  identifier: 'rest',
  title: 'Sit still for two minutes',
  timeout: const Duration(minutes: 2),
  autoSkip: true,
);

The countdown shows no hours, so keep timeout under one hour. The package does not bundle the sound for playSound into your app. See Add media and sound assets.

Completion step

RPCompletionStep ends a task with a title, a text, a checkmark animation and a DONE button. It hides the bottom bar and records no result. When it is the last step, DONE finishes the task.

A closing screen:

final done = RPCompletionStep(
  identifier: 'done',
  title: 'Thank you',
  text: 'Your answers are saved. You can close the app.',
);

Consent steps

RPVisualConsentStep and RPConsentReviewStep make up an informed consent flow, and both show an RPConsentDocument:

A task that contains a consent review step is a consent task: it has no close button, and the participant leaves it with DISAGREE. Both steps hide the bottom bar and bring their own buttons. See Informed consent.

Activity step

RPActivityStep is the base class of interactive tests, such as the cognitive tests in cognition_package. A subclass draws the test and records an RPActivityResult; the base class itself shows an empty screen. See Activity steps.