A widget for rendering feature-rich forms defined in JSON definition files
LHC-Forms (a.k.a. LForms) is a feature-rich, open-source widget that creates input forms based on definition files for Web-based applications. It was developed by the Lister Hill National Center for Biomedical Communications (LHNCBC), National Library of Medicine (NLM), part of the National Institutes of Health (NIH), with the collaboration and support from the Regenstrief Institute, Inc. and the LOINC Committee.
LHC-Forms can be used either as a prebuilt package or installed using
npm (npm
install lforms), but see the note below about the
npm installation). If you aren't using npm, the simplest way to start using
LHC-Forms is by linking to the prebuilt version hosted on
lhcforms-static.nlm.nih.gov. The URLs for the CSS and JavaScript are:
The zone.min.js file should be left out if you already have that in your page (e.g. if the page contains an Angular app).
Note that the URLs contain a release version number, 34.0.0, for which you can substitute any of the other prebuilt versions (34 or higher) available at https://lhcforms-static.nlm.nih.gov/lforms-versions.
For production applications, if you would prefer to download these files and serve them from your server to avoid introducing a dependency on the lhcforms-static servers, zip files of each version's files are avaialble at https://lhcforms-static.nlm.nih.gov/lforms-versions.
If you decide to use the npm package, note that for now the JavaScript files do not work when the package is required or imported, so you will still need to load the above files from the npm package's directory via script tags. We are hoping to find a solution that will allow them to be imported in the future.
In your HTML, create an element to hold the form. You will pass a reference to this element or its ID to a utility function load the form.
<div id="myFormContainer"></div>
Also include the above JavaScript and CSS files on the page.
LForms.Util.addFormToPage(formDefinition, 'myFormContainer', options);
After the user fills out a form, the data they have entered and things like codes for coded answer lists will be stored in the data model. To retrieve that data, LHC-Forms provides several utility methods. To get the data as a FHIR QuestionnaireResponse (recommended), see the Exporting FHIR part of the FHIR support section. Alternatively, the functions below will return the data in LHC-Forms' internal format.
LForms.Util.getFormData(formElement, noEmptyValue, noDisabledItem)The utility method LForms.Util.getFormData() will return both the user
data and the complete form definition data together in a way that can be fed back to LHC-Forms
to display the form with the data. This is useful when you want to allow the
user to save the form so it can be redisplayed later for completion or editing.
The parameters are:
LForms.Util.getUserData(formElement, noFormDefData, noEmptyValue, noHiddenItem)
To get a compact structure with just the user-entered data and minimal form
definition data, you can call LForms.Util.getUserData(formElement, true, true,
true). The parameters are:
The user entered data, along with some form definition data can be retrieved as HL7 v2 OBR and OBX segments. To retrieve that data, LHC-Forms provides the following utility method:
LForms.Util.getFormHL7Data(element)
The parameter is:
Prior to submitting the form, the form can be checked to make sure required fields are filled in and that the values have the correct format, by using the following function:
LForms.Util.checkValidity(formElement)An array of errors will be returned if the form is invalid. If the form is valid this function returns null.
The parameter is:
LHC-Forms can import and export FHIR Questionnaire and QuestionnaireResponse resources. For the current extent of that support, see the documentation for version R4 support" and SDC support. Also, there is partial support for exporting DSTU2 DiagnosticReports, and for importing them if generated by LHC-Forms.
Because adding support for FHIR (and multiple versions of FHIR) would increase the size of the LHC-Forms library, support for FHIR is added through separate files. See the Installation section for the options for FHIR support files.
The form definition and user-entered data can be retrieved as FHIR resources, using the following utility method:
LForms.Util.getFormFHIRData(resourceType, fhirVersion, formDataSource, options)
The parameters are:
A FHIR Questionnaire resource can be converted/imported into the LHC-Forms format, which can then be loaded into the LHC-Forms widget to show the form. To do that conversion, LHC-Forms provides the following utility method. Note also that the addFormToPage method documented above can take a FHIR Questionnaire, so this step is only needed if you are trying to show a QuestionnaireResponse.
LForms.Util.convertFHIRQuestionnaireToLForms(fhirData, fhirVersion)
The parameters are:
The return value is a form definition in the LHC-Forms format.
If the Questionnaire referenced external FHIR resources or launchContext variables, those will still need to be loaded. Before that can happen, you will need to tell LForms about the connection to the FHIR server, via:
LForms.Util.setFHIRContext(fhirContext, fhirContextVars)The "fhirContext" parameter should be an instance of 'client-js', a.k.a. the npm package fhirclient, version 2. (See http://docs.smarthealthit.org/client-js for documentation.). A non-npm version, ready to use in a browser, can be found at https://cdn.jsdelivr.net/npm/fhirclient@2/build/fhir-client.min.js. It should be initialized with a connection to the FHIR server to be used. If all that is needed by the Questionnaire are launchContext variables, this parameter can be omitted if the next parameter is provided.
The "fhirContextVars" parameter (optional) is used for the FHIR launchContext which makes variables available to other expressions in a Questionnaire. If provided, fhirContextVars should be a map from launchContext variable names to FHIR resources (as objects). Note that some launchContext variables can be retrieved from the FHIR server (via the fhirContext parameter). Values provided here will take priority over values from fhirContext.
If rendering using LForms.Util.addFormToPage(), the external FHIR resources will be loaded when that is called, and if you have passed in prepopulate=true as an option, prepopulation will also be performed when the resources are loaded. The addFormToPage function returns a promise that will resolve after all external FHIR resources have been loaded (at which point the form should be visible).
FHIR QuestionnaireResponses (and also a DSTU2 version of DiagnosticReports, if generated by LHC-Forms) can be loaded into an LHC-Forms form definition to produce a structure that can be loaded into the LHC-Forms widget (using addFormToPage) To merge FHIR resources into LHC-Forms data, LHC-Forms provides the following utility method:
LForms.Util.mergeFHIRDataIntoLForms(resourceType, fhirData, formData, fhirVersion)
The parameters are:
The return value is a form definition object but with the user data merged into it. It can be displayed using LForms.Util.addFormToPage as described above.
Form definitions are stored in a JSON structure, which is either FHIR Questionnaire (recommended) or the LHC-Forms internal format. To get a rough idea of what the internal format is you can take a look at one of the samples, or see the form definition documentation.
See the LICENSE.md file in the lforms package on GitHub.
For reporting problems with LHC-Forms, please open an issue on GitHub. Note that the team developing LHC-Forms also works on several others packages, so we might not be able to respond as quickly as we would like.
To receive occasional announcements about changes or updates to LHC-Forms, sign up for the email list by sending the message "subscribe LHCFORMS-ANNOUNCE" (no subject needed) to listserv@list.nih.gov. These annoucements will probably just be about significant changes.