Stream: implementers
Topic: Questionnaires and questionnaire-displayCategory extension
Tadas Antanavicius (Nov 01 2019 at 21:28):
Hi all - I'm trying to understand the best way to attach "helper text" to Questionnaire items.
It seems like using display items is the way to go here, and in particular I'm interested in leveraging the questionnaire-display-category extension (https://www.hl7.org/fhir/codesystem-questionnaire-display-category.html) to classify my helper text as code "help".
If I want to ask a question, e.g. "When was your last visit?" and I want to attach helper text to that question, e.g. "If you don't remember, enter a best guess", which of these approaches is the correct way to model this?
1) Display item for helper text at the root, with a nested item for the actual question item.
{
"resourceType": "Questionnaire",
"item": [
{
"linkId": "last-visit-helper",
"text": "If you don't remember, enter a best guess",
"type": "display",
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-displayCategory",
"valueCodeableConcept": {
"coding": {
"code": {
"system": "http://hl7.org/fhir/questionnaire-display-category",
"code": "help",
"display": "Help"
}
}
}
}
],
"item": [
{
"linkId": "last-visit",
"text": "When was your last visit?",
"type": "dateTime"
}
]
}
]
}
2) Actual question item at the root, with a nested display item for the helper text
{
"resourceType": "Questionnaire",
"item": [
{
"linkId": "last-visit",
"text": "When was your last visit?",
"type": "dateTime",
"item": [
{
"linkId": "last-visit-helper",
"text": "If you don't remember, enter a best guess",
"type": "display",
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-displayCategory",
"valueCodeableConcept": {
"coding": {
"code": {
"system": "http://hl7.org/fhir/questionnaire-display-category",
"code": "help",
"display": "Help"
}
}
}
}
],
}
]
}
]
}
3) Create a group item that contains the question item and the display item
Omitting example because this seems wrong to me, because enforcing this group -> question + display model would require a profile of some kind.
I understand that one alternative would be to rely on Questionnaires' ordering guarantees, and put "helper text" display items before the questions where the text is relevant - but I want to explicitly tie the helper text to specific questions.
#2 seems like the most obvious approach to me, but my main concern: it suggests that _every_ nested display item is "secondary text" to its parent question item. What if I have a deeply nested Questionnaire and sometimes I want "secondary text" but other times I just want a normal inline display item that isn't simply supporting the parent question item -- especially in the case where the parent question item is a group.
#1 seems like it might avoid the above issue, but also seems to suggest that we should avoid having any more than one question item nested immediately inside the display item, which feels odd.
Can someone please point me in the right direction for what the intended approach is, and any bad assumptions I'm making here?
Thanks!
Lloyd McKenzie (Nov 01 2019 at 21:32):
Just so you know, there's a #questionnaire stream that may be a better target for some of these questions :)
There isn't a right or wrong answer. It's really a question of style. #2 makes clear that the display applies to the question (or items within that question). #1 could apply to pretty much anything. #3 is really just a special case of #1.
Lloyd McKenzie (Nov 01 2019 at 21:33):
Key thing is to think about how you want things to render. Typically things listed beneath a question will appear below or on the same line as the question. Display items listed prior to a question will appear before the question.
Lloyd McKenzie (Nov 01 2019 at 21:34):
(That's not a strict rule as rendering engines have some degree of flexibility in how they render content with different display categories
Tadas Antanavicius (Nov 04 2019 at 19:50):
Thanks! Helpful to know that there isn't some specific preferred approach.
Just so you know, there's a #questionnaire stream that may be a better target for some of these questions :)
Sorry, I did ask my other question in there, and realize now this question made sense to ask there as well. I am both implementing the rendering engine and using it, if that might affect the perspective you can offer here.
I think I'm going to go with #2, and have my engine assume that all "help" categorized display items are intended to serve as "helper text" to their parent (hidden in tooltips as appropriate, etc.). I can continue to have non-"help" display items render alongside all other questionnaire items.
In my implementation, I'm considering wrangling display items tagged as "help" into a data representation that is akin to the questionnaire-instruction extension that last existed in DSTU2 (https://hl7.org/fhir/DSTU2/extension-questionnaire-instruction.html). Do you recall the reason for that extension's removal, or could point me to any discussion that covered it? I'd like to make sure I'm not re-creating some modeling mistake that I'll regret later.
Lloyd McKenzie (Nov 04 2019 at 21:31):
It got removed because we decided that having instructions of some sort was part of core
Paul Lynch (Nov 04 2019 at 23:34):
There is also the extension http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl (with code "help") which can be used for help. Issue GF#24117 was raised to resolve the apparent duplication.
Paul Lynch (Nov 04 2019 at 23:39):
@Tadas Antanavicius Since you mentioned writing a form renderder, I wanted to mention our open-source LHC-Forms widget which renders FHIR forms. (Just FYI.)
Paul Lynch (Nov 04 2019 at 23:47):
LHC-Forms, BTW, follows your approach in #2, except that it uses the questionnaire-itemControl extension. #1 does not look right to me, and I am not sure what @Lloyd McKenzie meant by "#1 could apply to pretty much anything". It is probably an area that could use some clarification in the spec.
Last updated: Apr 12 2022 at 19:14 UTC
