Research Package API

This tutorial describes the overall software architecture of ResearchPackage and its API, and how to get started.

Architecture and API

API Naming

We are following the API naming pattern from Apple’s Research Kit. ResearchKit uses the prefix ORK (Open Research Kit) before the names of classes, types etc. Following this naming model, the class names in ResearchPackage starts a RP prefix. UI widgets uses the RPUI (Research Package UI) prefix.

> Note that objects prefixed with 'RP' are part of the Model (e.g. RPConsentDocument) while those prefixed with 'RPUI' are part of the UI library (e.g. RPUIVisualConsentStep). 

Domain Model

At the top, ResearchPackage uses a Task to hold the individual steps the user must go through, fx. a series of questions or an informed consent with a few sections of information to read about. The task models available are RPOrderedTask and RPNavigableOrderedTask. Both are ordered but the latter can navigate inside the questions if needed.

A step can be either RPQuestionStep, RPInstructionStep, RPFormStep, RPCompletionStep, RPVisualConsentStep or RPConsentReviewStep, depending on what is needed. The latter two are used for consent only, but it is also possible to mix them with the other steps.

For the RPNavigableOrderedTask, ResearchPackage uses RPStepNavigationRule types to specify any behavior where the task should not simply go to the next step every time. The different types of navigation rules are: RPStepJumpRule, RPStepReorganizerRule and RPDirectStepNavigationRule. An example of a navigation survey could be the situation below:

In the example below, a survey is modelled as a task with 5 steps. The task is an RPOrderedTask object and the steps are RPQuestionStep with and RPInstructionStep after the first question. Each RPQuestionStep is created with an RPAnswerFormat which decides how the the question can be answered.

Once the task is “done”, the answers (results) are saved as a RPTaskResult object.

BLoC Architecture

ResearchPackage follows the BLoC architecture, which is recommended by the Flutter Team. In ResearchPackage, the BlocTask is holding the StreamControllers needed for the communication. Following the BLoC architecture, ResearchPackage uses streams and callbacks for internal communication (e.g. between Task and Steps). There is a BLoC class responsible for the communication between the task and the steps it’s containing (BlocTask). Communication between the question container and their question body is made possible via callback functions.

Style and UI Theme

Research Package is accessing the parent application’s style through Flutter’s context feature. This means that the given Theme of the application is shared also with Research Package and appears in its styling (colors, font styles…). As an example, the example application shows how the theme colors of the parent application are modified, and this is reflected in the ResearchPackage screens. See this article by the Flutter team on how to Theme your application.

ResearchPackage uses the values of specific Theme-items such as the Theme.of(context).textTheme.headline6 for styling, an as such it is possible to parse a TextStyle to the theme and with the ability for complete customization. Some other used theme-values are sliderTheme.activeColor, sliderTheme.inactiveColor, textTheme.subtitle1 and colorScheme.onPrimary. Many more are used and you may consult the source code for specific elements.

Here is an example of how to change the these default values:

  Widget build(BuildContext context) {
    return Theme(
      data: ThemeData.light().copyWith(
        sliderTheme: SliderThemeData(
        activeTrackColor: Colors.green,
        inactiveTrackColor: Colors.red,
      )),
      child: RPUITask(
        ...
      ),
    );
  }

How to set up a ResearchPackage project

Research Package is published to `pub.dev` and can be add as a dependency in the pubspec.yaml file.

dependencies:
    research_package: ^{latest_version}

After you run the flutter packages get command, you are able to import and start using ResearchPackage. You can import the whole package including the Model and UI libraries:

import 'package:research_package/research_package.dart';

Or you can decide which library of the package you want to use:

import 'package:research_package/model.dart'; 
import 'package:research_package/ui.dart';

Answer Formats

Answer formats are extension on the RPAnswerFormat class. They all change how the RPQuestionStep can be answered depending on which answer format is chosen. The answer formats currently available are:

• Singe Choice
• Multiple Choice
• Integer
• Date and Time (Date)
• Date and Time (Time of Day)
• Date and Time (Date and Time)
• Image Choice
• Slider
• Free Text
• Form Step (This answer format is not used, but will be automatically applied if using a RPFormStep)

Below is a UI representation of the currently available answer formats of Research Package at the moment.

Single Choice | Multiple Choice | Integer

Date And Time (3 answer styles)

Date Answer Type | Date and Time Answer Type | Time of Day Answer Type

Image Choice | Slider | Free Text

Form Step

It is possible to put multiple questions on the same page by using a form step – RPFormStep. Each question step have a separate card, which is shown below.

Active Tasks

Research Package has a sister package Cognition Package that builds upon the active tasks of Research Package.

Limitations and Contributing

ResearchPackage currently supports the answer formats listed above, which can be put on separate pages or combined in one page (using a FormStep). Nonetheless, we are constantly working on the package so these features, as well as other types of questions will be implemented in the future.

ResearchPackage is available as open source under an MIT license, so if you’re interested in helping to maintain and expand it, please reach out and make pull requests. Also, please report any issues you may find.