The LHC Expression Editor

A widget to add and edit FHIRPath expressions to a given FHIR Questionnaire.

Usage

The Lister Hill Center (LHC) Expression Editor can be used both as an Angular Component or a Web Component.

Attributes available

Note: To use the attributes for Web Components change the camel case below to kebab case (with a dash). This does not apply to the keys of the lhcStyle object.

• fhirQuestionnaire - The FHIR Questionnaire the user will edit using the widget.
• itemLinkId - The linkID on which the FHIRPath expression will be stored. If the FHIRPath expression is to be stored at the Questionnaire root level rather than at the item levels, then an empty 'itemLinkId' should be passed in.
• save - Callback called after the user clicks save inside the widget. The callback passes in the new version of the FHIR Questionnaire the user entered as a parameter.
• expressionUri - By default the widget modifies the calculatedExpression. You can specify any expression URI here; it is preserved unchanged in the result. The target Questionnaire or item's extensions and sub-extensions are searched, and an existing expression is saved back to its original parent. At the Questionnaire root, the Output Expression section is available for a recognized SDC extraction expression; otherwise root mode edits Questionnaire variables and expressionUri is not needed.
• expressionValueType - Controls how the output expression is stored. Use valueExpression (the default) for the FHIR Expression datatype or valueString for string-backed extraction expressions.
• expressionParentIndex - Optional index in the target Questionnaire or item's extension array of the definitionExtract or templateExtract extension that owns a bundle field such as fullUrl. It is only needed when that target contains more than one extract extension. Without it, a missing bundle field is added to the target's only extract extension; the target is rejected if it has no extract extension, more than one, or one that does not define the field (for example, resourceId in definitionExtract).
• itemVariablesReadOnly - In the standard expression context, when true, variables declared on the current item are shown with the other read-only variables in scope instead of in the editable Item Variables section. Defaults to false. Extraction expressions exclude ordinary Questionnaire variables regardless of this setting.
• expressionLabel - Heading name to use to show user when entering the expression.
• titleName - Main widget heading shown to the user.
• advancedInterface - Show options to edit FHIRPath and x-fhir-query directly in dropdowns. This mode is automatically enabled for complex Questionnaires. This attribute sets the default which can be overridden by the user.
• doNotAskToCalculateScore - Do not ask the user if they would like to calculate a score.
• userExpressionChoices - Choices of expression type to output. Array of objects with name and uri values of choices to present to the user in a dropdown. If no value is provided the dropdown will not be present.
• lhcStyle (object) - Specify custom CSS to be used by the widget for:
  • h1 - Main heading
  • h2 - Secondary headings
  • previewArea - FHIRPath preview area
  • variableHeader - Variable section table header
  • variableRow - Variable section table row
  • buttonPrimary - Button style for primary action
  • buttonSecondary - Button style for secondary actions
  • buttonDanger - Button style for delete, etc
  • input - Input forms
  • select - Input forms
  • description - Instructions presented to the user

Use as an Angular Component

1. Install in your project using npm install --save-prod @lhncbc/expression-editor
2. Make sure your application has @angular/animations, @angular/cdk, @angular/common, @angular/core and @angular/material as dependencies since they are needed as peer dependencies by the Expression Editor.
3. Add the lhc-expression-editor and required tags similar to the example below:

Angular Component Example

Note that the attribute names need to be surrounded by square brackets. The only required attributes are [fhirQuestionnaire] and [itemLinkId].

If the FHIRPath expression is to be stored at the Questionnaire root level, only the [fhirQuestionnaire] is the requied attribute. An empty [itemLinkId] can be passed in or omitted altogether in that case.

To retrieve data use the (save) attribute.

<lhc-expression-editor
  [fhirQuestionnaire]="fhir[questionnaire]"
  [itemLinkId]="linkId"

  (save)="onSave(fhirResult)"

  [submitButtonName]="'Save'"
  [titleName]="'My Expression Editor'"
  [expressionLabel]="'My Expression'"
  [expressionUri]="'http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression'"
  [lhcStyle]="{
    buttonPrimary: { backgroundColor: 'blue' },
    buttonSecondary: { backgroundColor: 'blue', color: 'white' },
    input: { backgroundColor: 'lightblue' },
    select: { backgroundColor: 'lightblue' }
  }">
</lhc-expression-editor>

Use as a Web Component

1. Install in your project using npm install --save-prod @lhncbc/expression-editor
2. Import jQuery.
3. Import the JavaScript file dist/expression-editor/expression-editor.js on the page or integrate it as part of your build process (webpack, etc.)
4. Add the tag along with necessary attributes to the HTML.
5. Add event handlers for the save event.

Web Component Example

To retrieve data add an event listener for save.

<lhc-expression-editor
  id="editor"
  title-name="Test Expression Editor"
  submit-button-name="Test Submit">
</lhc-expression-editor>

<pre id="output"></pre>

<script src="/expression-editor/expression-editor.js"></script>

<script src="mock-data.js"></script>

<script>
  const editor = document.getElementById('editor');
  const output = document.getElementById('output');

  editor.fhirQuestionnaire = fhir.phq9;
  editor.itemLinkId = '/39156-5';
  editor.titlename = 'test';

  editor.addEventListener('save', (data) => {
    output.innerText = JSON.stringify(data.detail, null, 2);
  });
</script>

Build

Run npm run build to build the project. The build artifacts will be stored in the dist/ directory. Use the --prod flag for a production build.

Demo project

Run npm start after building to see the two ways to use the widget:

• The Angular Library can be used at http://localhost:4202.
• The Web Component can be used at http://localhost:4202/web-component.html.

Running tests

Run npm test to execute the unit tests via Karma and the end-to-end tests via Protractor.