Documentation by version:
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 the using the
bower package manager (i.e. bower
install lforms). If you aren't using bower, the simplest way to start
using LHC-Forms is by linking to the prebuilt version hosted on
clinicaltables.nlm.nih.gov. The
URLs for the JavaScript and the CSS are:
(Note that the URLs contain a release version number, 13.6.0, for which you can substitute any of the other prebuilt versions available at https://clinicaltables.nlm.nih.gov/lforms-versions).
Although LHC-Forms internally uses AngularJS and offers a directive for use by AngularJS projects, you do not need to know anything about AngularJS to use it.
In your HTML, create a 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 LHC-Forms JavaScript and CSS files on the page. In your page header:
<link
href="https://clinicaltables.nlm.nih.gov/lforms-versions/13.6.0/styles/lforms.min.css"
media="screen" rel="stylesheet" />
<script
src="https://clinicaltables.nlm.nih.gov/lforms-versions/13.6.0/lforms.min.js"
></script>
LForms.Util.addFormToPage(formDefinition, 'myFormContainer');
As in the non-Angular method, you will need to include the LHC-Forms CSS and JavaScript (possibly using bower and wiredep, if you are using those).
The HTML in your page will look something like:
<body ng-app="myApp">
<div ng-controller="myController">
<lforms lf-data="myFormDefinition"></lforms>
</div>
</body>
The directive is contained by a controller (in this example named "myController") which will have the responsibility of providing the form definition data as a JSON object (in this example named "myFormDefinition").
In the JavaScript for the AngularJS app, include 'lformsWidget' as a module to be loaded. Then, in the JavaScript for the AngularJS controller, construct an LFormsData object with the JSON form definition and assign that object to the scope variable "lfData". The form should initialize and display. For example:
angular.module('myApp', ['lformsWidget'])
.controller('myController', ['$scope', function ($scope) {
$scope.myFormData = new LForms.LFormsData(myFormDefinition);
}]);
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 the following utility method:
LForms.Util.getUserData(formElement, noFormDefData, noEmptyValue, noHiddenItem)
$scope.myFormData.getUserData(noFormDefData, noEmptyValue, noHiddenItem)
With no arguments (i.e. LForms.Util.getUserData()), the data for the first LForm found on that page will be returned, and will include the form definition, along with entries for questions the user left blank and for questions that were hidden by skip-logic (which the user might not have seen). This default return behavior can be changed by the parameters, but in all cases the returned data will follow the structure of the form, in that answers will be nested inside containing sections.
The parameters are:
As an example, here is the data from a partially filled-in vital signs panel,
returned via $scope.myFormData.getUserData(null, true, true, true):
{
"itemsData": [{
"questionCode": "35094-2",
"items": [{
"questionCode": "8480-6",
"value": "100",
"unit": {
"name": "mm[Hg]",
"default": false,
"normalRange": null,
"absoluteRange": null
}
}, {
"questionCode": "8357-6",
"value": {
"label": null,
"code": "LA24014-5",
"text": "Oscillometry",
"other": null
}
}]
}],
"templateData": [{
"value": "2015-11-09T05:00:00.000Z"
}]
}The first section in the returned data "itemsData" contains all of the data from the form itself. LHC-Forms (optionally) adds a section to the top of the form that includes fields like "Date" and "Comment", and the data for these elements shows up in "templateData". The form definition data was not included in the above example, but you can see the structure if you look closely at itemsData. In this form, there was a section (question code "35094-2") which contained both of the two filled-in items as data. That is why there is just one entry in the itemsData itself, and that item has two sub-items in "items" array. One of the two items was numeric and had an associated unit field, while the other was a coded list field.
Another utility method, LForms.Util.getFormData(), will return both the user data and 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 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:
LHC-Forms can import and export FHIR Questionnaire and QuestionnaireResponse resources. Also, there is partial support for importing and exporting DiagnosticReports (but those need to be 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. If you are using one of the prebuilt versions, you can include:
<script src="https://clinicaltables.nlm.nih.gov/lforms-versions/13.6.0/fhir/R4/lformsFHIR.min.js"></script>If you are installing via bower, the additional files to include are:
As with the prebuilt files, you may include either the R4 or the STU3 version, or both.
The form definiton 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:
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:
LForms.Util.convertFHIRQuestionnaireToLForms(fhirData, fhirVersion)
The parameters are:
The return value is a form definition in the LHC-Forms format.
FHIR DiagnosticReports (if generated by LHC-Forms) and FHIR QuestionnaireResponses can be loaded into an LHC-Forms form definition to produce a structure that can be loaded into the LHC-Forms widget (using the same methods as for JSON form defintions described above) to show the form along with the user data. 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 described above.
Form definitions are stored in a JSON structure. To get a rough idea of what these are you can take a look at one of the samples, or for a detailed description see the form definition documentation.
See the LICENSE.md file in the lforms package on GitHub.