fhir_questionnaire 8.0.2

A library to render FHIR Questionnaires and generate a QuestionnaireResponse

FHIR Questionnaire

A Flutter package for working with FHIR® Questionnaires. FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of this product by HL7.

This package takes care building the UI of a FHIR R4 Questionnaire, handle behavior and validations and finally generates the QuestionnaireResponse from the user answers.

Important

This package is now based on fhir_plus if you need a version based on fhir_r4 from fhirfli.dev use fhir_questionnaire_r4

Supported Questionnaire Items

So far this package only supports FHIR R4 Item Types

Item	Supported
Group	✅
Display	✅
Question	☑️
Boolean	✅
Decimal	✅
Integer	✅
Date	✅
DateTime	✅
Time	✅
String	✅
Text	✅
Url	✅
Choice	✅
OpenChoice	✅
Attachment	✅
Reference	☑️
Quantity	✅

Supported extra features

1. enableWhen supported
2. enableBehavior supported.
3. Calculated Expression supported
4. Extension for translation supported.
5. Extension for questionnaire-hidden supported.
6. Extension for minLength extension.
7. Extesion for minValue extension.
8. Extesion for maxValue extension.
9. Extesion for hint texts using entryFormat extension.
10. Extension for helper text or helper button using questionnaire-displayCategory and questionnaire-itemControl with the codes help and flyover.
11. Hand written signature capture via the questionnaire-signatureRequired extension (root or item level), emitted in the response as a questionnaireresponse-signature. See the Signatures section.

How to use

Just add a QuestionnaireView widget to your widget tree and you will have your Questionnaire UI.

QuestionnaireView(
    questionnaire: questionnaire, // A FHIR R4 Questionnaire instance
    onAttachmentLoaded: onAttachmentLoaded, // A callback to handle attachment loading (explained below) 
    locale: locale, // The specific locale for the Button and validation texts
    localizations: localizations, // To add support for extra localization 
    isLoading: loading, // Wether is some ongoing operation before loading the UI 
    onSubmit: onSubmit, // Callback to get the QuestionnaireResponse
    controller: controller, // The QuestionnaireController to use for item view and response generation.
    subject: patient, // QuestionnairePerson subject of the QuestionnaireResponse
    author: practitioner, // QuestionnairePerson author of the QuestionnaireResponse
    source: practitioner, // QuestionnairePerson who provided the answers
    whoSigns: practitioner, // QuestionnairePerson who signs the QuestionnaireResponse / signatures
    signsOnBehalfOf: patient, // QuestionnairePerson the response is signed on behalf of
)

QuestionnaireView

1. Questionnaire questionnaire: QuestionnaireView requires an object of type Questionnaire this is the definition of the Questionnaire and will be used to build the Form UI and generate the Questions and Answers.
2. Locale? locale: Optionally you can specify the language like "es" or "en" or "fr", etc. you want to use for validation messages and Submit button, by default the system language will be used.
3. List: this is a list allows you to add extra language translations to the Questionnaire, currently the package supports only English and Spanish, so you can add other Languages, you just need to create a class for each new Language you want to support and extend QuestionnaireBaseLocalization.
4. QuestionnaireBaseLocalization? defaultLocalization: Indicates what should be the fallback localization if the specified language or the system language is not supported, by default English is the fallback.
5. bool isLoading: use this to indicate there is an ongoing operation, for instance if you need to make an API request to load your Questionnaire you can set isLoading = true so the QuestionnaireView will show a Shimmer loading effect view.
6. Future<Attachment?> Function()? onAttachmentLoaded: To make this package simpler and compatible with all Flutter supported platforms, the feature to load an attachment is delegated to the App, so you have to handle this logic by implementing this function and returning an Attachment instance according to FHIR.
7. ValueChanged: This is the callback that will be triggered once the user taps on the Submit button, and you will get a QuestionnaireResponse instance ready with the answers covered, and with the subject, author and source already set if you provided them (see below). You can still set any extra data you consider necessary.
8. QuestionnaireController? controller: This is the controller to be used for items and response generation within the QuestionnaireView, the purpose of this controller here is to allow you to use an instance of an extension of QuestionnaireController so you can override the behavior and widgets.
9. QuestionnairePerson? subject: Optional QuestionnairePerson for the subject of the QuestionnaireResponse (e.g. the Patient the answers are about). When provided its reference is set on the generated QuestionnaireResponse.subject.
10. QuestionnairePerson? author: Optional person for the author of the QuestionnaireResponse (the person or device that received and recorded the answers). When provided its reference is set on QuestionnaireResponse.author.
11. QuestionnairePerson? source: Optional person for the individual who provided the information reflected in the answers. When provided its reference is set on QuestionnaireResponse.source.
12. QuestionnairePerson? whoSigns: Optional person who signs the QuestionnaireResponse. Its reference is used as Signature.who, and its name/title are shown beneath each signature pad.
13. QuestionnairePerson? signsOnBehalfOf: Optional person on behalf of which the QuestionnaireResponse is signed. Its reference is used as Signature.onBehalfOf.

If you use your own controller instead of letting QuestionnaireView create one, the subject, author, source, whoSigns and signsOnBehalfOf properties are ignored; provide the corresponding subjectProvider, authorProvider, sourceProvider, whoSignsProvider and signsOnBehalfOfProvider callbacks to your QuestionnaireController instead.

Signatures

This package can capture hand written signatures and embed them into the generated QuestionnaireResponse, powered by the hand_signature package.

Declaring a required signature

A signature is requested wherever a questionnaire-signatureRequired extension is present, either at the root of the Questionnaire or on any item (typically a group). The extension's valueCodeableConcept.coding declares the kind of signature required and is reused verbatim as the Signature.type in the response.

{
  "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-signatureRequired",
  "valueCodeableConcept": {
    "coding": [
      {
        "system": "urn:iso-astm:E1762-95:2013",
        "code": "1.2.840.10065.1.12.1.7",
        "display": "Consent Signature"
      }
    ]
  }
}

A questionnaire may declare several signatures at once (root level plus one or more item level markers); each one is captured and validated independently. A signature declared this way is always required before the form can be submitted, regardless of the item's own required flag.

Capturing the signature (UI)

For each signature marker a QuestionnaireSignatureView renders a tappable preview:

• Empty: a placeholder ("Tap to sign") inviting the user to sign.
• Tapping it opens a SignaturePadDialog with the actual drawing pad; the user draws and taps Done to commit or Cancel to discard. Drawing happens in a dialog so the pad's gesture is not stolen by the surrounding scrolling form.
• Once signed, the preview shows the drawn signature, with a button to clear it and sign again.

Placement depends on where the marker is declared:

• Root level: shown at the end of the form.
• Group item: shown inside the group's container, after the group's own items.
• Non-group item: shown together with the item's normal content.

The generated response

On submit, each drawn signature is embedded as a PNG (base64) inside a questionnaireresponse-signature extension holding a FHIR Signature:

• on QuestionnaireResponse.extension for a root level signature,
• on the matching QuestionnaireResponseItem.extension for an item level signature.

The Signature.type is taken from the marker's coding (falling back to a default Author's Signature coding only when the marker declares none), sigFormat is image/png, when is the submit time, and who / onBehalfOf come from the whoSigns / signsOnBehalfOf you provide.

Signer information (QuestionnairePerson)

subject, author, source, whoSigns and signsOnBehalfOf are of type QuestionnairePerson:

QuestionnairePerson(
  reference: practitionerReference, // FHIR Reference written into the response
  name: 'Dr. Jane Doe',             // Display name
  title: 'Attending Physician',     // Optional subtitle
)

When whoSigns (and optionally signsOnBehalfOf) is provided, the signature field also shows the signer's name/title beneath the pad ("By: …" / "On behalf of: …"), and the reference is written into the response Signature.who / Signature.onBehalfOf.

Overriding the UI

All signature widgets are public and can be extended/overridden: QuestionnaireSignatureView, SignaturePadDialog (with its public generic SignaturePadDialogState) and SignatureController. Detection helpers hasSignature and signatureTypeCoding are exposed as extensions on Questionnaire and QuestionnaireItem.

Some extra notes

1. This widget will use the app Theme to build, so if you want to change colors, InputDecorations, etc, you just have to change it in your app Theme. Also all the package widgets are public and exposed so you could override it if necessary.
2. The QuestionnaireView implementation takes care of validations depending on each QuestionnaireItem definition.
3. Check the example project which shows all the features in action.

Demo

Try the demo app here.