Documentation by version:

LForms

A widget for rendering feature-rich forms defined in JSON definition files


What is LForms?

LForms (a.k.a. LHC-Forms) 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.

Features

See the demos for a step-by-step introduction. Features include:

Installation

LForms 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 LForms is by linking to the prebuilt version hosted on clin-table-search. The URLs for the JavaScript and the CSS are:

JavaScript
https://clin-table-search.lhc.nlm.nih.gov/lforms-versions/11.2.0/lforms.min.js
CSS
https://clin-table-search.lhc.nlm.nih.gov/lforms-versions/11.2.0/styles/lforms.min.css

(Note that the URLs contain a release version number, 11.2.0, for which you can substitute any of the other prebuilt versions available at https://clin-table-search.lhc.nlm.nih.gov/lforms-versions).

Usage

Although LForms internally uses AngularJS and offers a directive for use by AngularJS projects, you do not need to know anything about AngularJS to use it.

Rendering a Form (Without AngularJS)

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.

HTML (without AngularJS)

<div id="myFormContainer"></div>

Also include the LForms JavaScript and CSS files on the page. In your page header:


<link
 href="https://clin-table-search.lhc.nlm.nih.gov/lforms-versions/11.2.0/styles/lforms.min.css"
 media="screen" rel="stylesheet" />
And with your other JavaScript:
<script
 src="https://clin-table-search.lhc.nlm.nih.gov/lforms-versions/11.2.0/lforms.min.js"
 ></script>

JavaScript (without AngularJS)

Your form definition should be loaded into a variable on the window object, e.g.:
window.myFormDefinition = {...}
Pass that variable name and the form container element to a utility function which will render the form:
LForms.Util.addFormToPage('myFormDefinition', 'myFormContainer');

Rendering a Form (AngularJS Method)

As in the non-Angular method, you will need to include the LForms CSS and JavaScript (possibly using bower and wiredep, if you are using those).

HTML

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").

JavaScript

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);
  }]);

Retrieving User-Entered Data

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, LForms provides the following utility method:

LForms.Util.getUserData(formElement, noFormDefData, noEmptyValue, noHiddenItem)
Or, from wihin an AngularJS app, there is also an API on the LFormsData object:

$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:

  1. formElement - an HTML element that includes the LForm's rendered form. If this is omitted, the "body" tag will be used. If there is more than one LForm within formElement, the first found will be used.
  2. noFormDefData (optional, default false) - If this is true, the form definition data will not be returned along with the data.
  3. noEmptyValue (optional, default false) - If this is true, items that have an empty value will be removed.
  4. noHiddenItem (optional, default false) - If this is true, items that are hidden by skip logic will be removed.

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. LForms (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 LForms 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.

Form Definition Format

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.

Licensing and Copyright Notice

The LForms software employs the LOINC data model, including the LOINC table, LOINC codes, LOINC panels and forms file, which are copyrighted © 1995-2015, Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee, and are available at no cost under the license at http://loinc.org/terms-of-use. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.

Please cite as: http://lhncbc.nlm.nih.gov/project/lhc-forms

This software is distributed under the license set forth below, which is based on the BSD open-source license.

No warranty or indemnification for damages resulting from claims brought by third parties whose proprietary rights may be infringed by your usage of this software are provided by any of the owners.

NIH License

Owner Notice: The Owner of this software, LForms, is the National Institutes of Health/Department of Health and Human Services, Bethesda, MD, U.S.A. All rights reserved.

The software includes elements owned by Joyent, Inc., TJ Holowaychuk, Google, Inc., Kit Cambridge, Kristopher Michael Kowal, jQuery Foundation, Twitter, Inc, The AngularUI Team, and Karsten Sperling, who have distributed them to NIH under the MIT open-source license.

Redistribution and use in source and binary forms, with or without modification, are permitted for commercial and non-commercial purposes and products alike, provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE OWNER AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Project maintained by lhncbc Hosted on GitHub Pages — Based on theme by mattgraham