Controls – SingleConceptMatching

• Recording a risk

  This scenario demonstrates a simple case of a clinician recording a risk without typing any additional text.

  1. Select Adverse Drug Reaction (ADR) entry from the Select a scenario drop-down list.
  2. Select Drugs from the Search filter drop-down list.
  3. Type the word 'Penicillin' into the Enter a substance field. The search is executed and the results are displayed in a list.
  4. Select Penicillin from the list of returned concepts. Leave the additional qualifier text field blank.
  5. Click the Save button. The concept is added to the list of encoded terms.
• Widening of subsets

  This scenario demonstrates a case where the scope of terminology search can be changed by altering the subsets.

  1. Select Adverse Drug Reaction (ADR) entry from the Select a scenario drop-down list.
  2. Select Food from the Search filter drop-down list.
  3. Type the word 'Gaviscon' into the Enter a substance field. The search is executed, however no results are displayed.
  4. Select All Allergies from the Search filter drop-down list. The search is re-executed and the results are displayed in a list.
  5. Select Gaviscon from the list of returned concepts. Leave the additional qualifier text field blank.
  6. Click the Save button. The concept is added to the list of encoded terms.
• No match found

  This scenario demonstrates a case where no results could be found for the clinical term typed in the concept entry field.

  1. Select Adverse Drug Reaction (ADR) entry from the Select a scenario drop-down list.
  2. Select All Allergies from the Search filter drop-down list.
  3. Type the word 'bcoprevir' into the Enter a substance field. The search is executed, however no results are displayed.
  4. Click the Save button. The concept is added to the list of encoded terms.
• Reaction entry

  This scenario demonstrates an example of a clinician recording a reaction entry which is also qualified with a severity attribute.

  1. Select Diagnosis entry from the Select a scenario drop-down list.
  2. Select Clinical Findings from the Search filter drop-down list.
  3. Type the word 'Rash' into the Enter a diagnosis field. The search is executed and the results are displayed in a list.
  4. Select Rash from the list of returned concepts.
  5. Type the words 'reported as severe' into the additional qualifier text field. The text 'severe' is identified as a valid laterality qualifier and highlighted. The concept Severe is shown with a check-box to the side of the additional qualifier text field.
  6. Click the Save button. The concept is added to the list of encoded terms.
• Diagnosis entry (involving laterality)

  This scenario demonstrates an example of a clinician recording a diagnosis which is also qualified with a laterality attribute.

  1. Select Diagnosis entry from the Select a scenario drop-down list.
  2. Select Clinical Findings from the Search filter drop-down list.
  3. Type the phrase 'fracture of neck of femur' into the Enter a substance field. The search is executed and the results are displayed in a list.
  4. Select Fracture of neck of femur from the list of returned concepts.
  5. Type the word 'left' in the additional qualifier text field. The word 'left' is identified as a valid laterality qualifier and highlighted. The concept Left is shown with a check-box to the side of the additional qualifier text field.
  6. Check the Left check-box. The highlighted text 'left' in the additional qualifier text field changes from blue to grey.
  7. Click the Save button. The concept is added to the list of encoded terms.
• Diagnosis entry (not body site)

  This scenario demonstrates an example of a clinician recording a diagnosis.

  1. Select Diagnosis entry from the Select a scenario drop-down list.
  2. Select Clinical Findings from the Search filter drop-down list.
  3. Type the word 'Gastroenteritis' into the Enter a diagnosis field. The search is executed and the results are displayed in a list.
  4. Select 'Gastroenteritis' from the list of returned concepts.
  5. Type the phrase 'symptoms displayed for the last 3 days' in the additional qualifier text field. No text is highlighted in the additional qualifier text field as no relevant matches are found.
  6. Click the Save button. The concept is added to the list of encoded terms.
• Negation

  This scenario demonstrates a case of a clinician wanting to encode the absence of an allergic reaction by prefixing the term with the word 'No'.

  1. Select Diagnosis entry from the Select a scenario drop-down list.
  2. Select Clinical Findings from the Search filter drop-down list.
  3. Type the word 'No rash' into the Enter a diagnosis field. The search is executed and the results are displayed in a list.
  4. Select 'no allergic skin rash' from the list of returned concepts. Leave the additional qualifier text field blank.
  5. Click the Save button. The concept is added to the list of encoded terms.
• Synonym

  This scenario demonstrates an example of a clinician recording a concept which has a synonym.

  1. Select Diagnosis entry from the Select a scenario drop-down list.
  2. Select Clinical Findings from the Search filter drop-down list.
  3. Type the phrase 'tennis elbow' into the Enter a diagnosis field. The search is executed and the results are displayed in a list.
  4. Place the cursor over the concept Tennis elbow in the search results. The flyout panel is displayed which indicates that 'tennis elbow' is a synonym of Lateral epicondylitis (disorder).
  5. Click anywhere on the screen to hide the flyout panel. Leave the additional qualifier text field blank.
  6. Click the Save button. The concept is added to the list of encoded terms.

This code shows how concepts within a clinical terminology (SNOMED CT®) can be matched against text typed in by a clinician.

Although this code can be used without customization, it is recommended that the following factors be considered when implementing the desired functionality:

• Screen real estate availability
• Order of fields on the screen
• Relationships with other fields
• Other user interface widgets in the vicinity
• The specific tasks that clinicians perform with this control
• Whether additional qualifier text is required

One or more of these factors may require the code to be customized to best match the specific requirements. However, it is recommended that only the following elements be changed (if at all):

• Presentation of the Single Concept Matching control; for example whether it is presented as a pop-up dialog or whether it is part of the main screen
• The 'additional qualifier text' field:
1. Location
2. Size
3. Presentation; for example, whether it is always present or whether it is only accessed by a user action (for example, a button click)
• Typeface formatting
• Background color
• Iconography

It is recommended that the following customization not be made:

• Minimum length of the matching entry field

The following steps show how to use the Single Concept Matching control to create a very simple Silverlight application. The steps do not rely on the service of an external terminologies provider.

Note: The steps do not rely on the services of an external terminologies provider.

1. Create a new Silverlight application in either VS.NET or Blend.
2. Add a reference to Microsoft.Cui.Controls.dll.

Perform one of the following:

• If using Blend, drag the Single Concept Matching control on to the form
• If using VS.NET, copy the XAML as produced from Blend

    public class ClinicalConcept
    {
        private int SnomedIDField;
        private string DescriptionField;
        private int SnomedDescriptionIDField;
        private string PreferredTermField;

        public ClinicalConcept()
        {
        }

        public ClinicalConcept(int snomedid, string description, int descripid)
        {
            this.SnomedID = snomedid;
            this.Description = description;
            this.SnomedDescriptionID = descripid;
            PreferredTermField="Preferred term " + description;
        }

        public int SnomedID
        {
            get { return SnomedIDField; }
            set { SnomedIDField = value; }
        }

        public string Description
        {
            get { return DescriptionField; }
            set { DescriptionField = value; }
        }

        public int SnomedDescriptionID
        {
            get { return SnomedDescriptionIDField; }
            set { SnomedDescriptionIDField = value; }
        }

        public string PreferredTerm
        {
            get { return PreferredTermField; }
            set { PreferredTermField = value; }
        }
    }

1. Provide a handler for InputBoxEnterPressed.
2. In this handler, carry out a 'search' using the text typed by the user and assign a collection of ClinicalConcept objects to the InputBoxItemsSource property of the Single Concept Matching control.

The following code calls the template for displaying the results from applying the selected subset picker (the Search filter):

<DataTemplate x:Key="SubsetPickerItemTemplate">
              <Border>
                  <TextBlock Margin="12" Text="{Binding Path=Value}" FontSize="12" />
              </Border>
</DataTemplate>

The following code calls the template for displaying the search results list:

<DataTemplate x:Key="InputBoxItemTemplate">
              <Border>
                  <controls:IndentedLabel
                            MaxLines="2" Text="{Binding Description}" 
                            VerticalAlignment="Top" FontSize="12" />
              </Border>
</DataTemplate>

1. Create a class to represent a matched term in the additional text

    public class MatchingTerm
    {
        public MatchingTerm()
        {
        }

        public MatchingTerm(int startindex, bool isselected, int length)
        {
		///initialization code
        }

        private int StartIndexField;
        private int LengthField;
        private bool IsSelectedField;
        private ClinicalConcept SelectedItemField;
        private ObservableCollection<ClinicalConcept> alternateItems;
        
        public int StartIndex
        {
            get { return StartIndexField; }
            set { StartIndexField = value; }
        }

        public int Length
        {
            get { return LengthField; }
            set { LengthField = value; }
        }

        public bool IsSelected
        {
            get { return IsSelectedField; }
            set { IsSelectedField = value; }
        }

        public ClinicalConcept SelectedItem
        {
            get { return SelectedItemField; }
            set { SelectedItemField = value; }
        }

        public ObservableCollection<ClinicalConcept> AlternateItems
        {
            get
            {
                return this.alternateItems;
            }
        }
    }

2. Each of the matched terms is represented by:

• StartIndex - the numerical location of the first character of the matched term.
• Length - the number of characters in the matched term.
• AlternateItems - a collection of possible alternatives for the matched term. For example, left or right.
• SelectedItem - the item in the collection that represents the matched term
• IsSelected - indicates whether the user has accepted the matched term

3. Provide a handler for the event AdditionalTextBoxEnterPressed.

4. In this handler, do the parsing of the additional text, initialize a collection of MatchingTerm, and assign this to AdditionalTextBoxMatchingTermItemsSource.

• AdditionalTextBoxDecoratorItemContainerStyle – Gets or sets the additional text box's decorator container item style
• AdditionalTextBoxDisplayedMatchingTerms – Gets the additional text box's displayed matching terms property
• AdditionalTextBoxIsReadOnly – Gets or sets a value indicating whether the additional text box is read-only
• AdditionalTextBoxMatchingTermIsSelectedMemberPath – Gets or sets the additional text box's matching terms is selected member path
• AdditionalTextBoxMatchingTermItemsSource – Gets or sets the additional text box's matching terms items source
• AdditionalTextBoxMatchingTermLengthMemberPath – Gets or sets the additional text box's matching terms length member path
• AdditionalTextBoxMatchingTermStartIndexMemberPath – Gets or sets the additional text box's matching terms start index
• AdditionalTextBoxMaxLength – Gets or sets the additional text box's maximum length
• AdditionalTextBoxSelectedTerms – Gets a list of selected terms
• AdditionalTextBoxStyle – Gets or sets the additional text box's style
• AdditionalTextBoxText – Gets or sets the additional text
• AdditionalTextBoxWatermark – Gets or sets the additional text watermark
• AdditionalTextBoxWatermarkTemplate – Gets or sets the additional text watermark template property
• InputBoxEncodedItemTemplate – Gets or sets the input box's encoded item template
• InputBoxFlyOutTemplate – Gets or sets the input box's flyout template
• InputBoxFlyOutWidth – Gets or sets the flyout width
• InputBoxIsSearchButtonVisible – Gets or sets a value indicating whether the search button on the input box is visible
• InputBoxItemContainerStyle – Gets or sets the input box's item container style
• InputBoxItemsSource – Gets or sets the input box's items source
• InputBoxItemTemplate – Gets or sets the input box's item template
• InputBoxLabelText – Gets or sets the input box's label text
• InputBoxMaxLength – Gets or sets the maximum length of the input box
• InputBoxSearchButtonToolTip – Gets or sets the input box's search button tooltip
• InputBoxSelectedItem – Gets or sets the input box's selected item
• InputBoxStyle – Gets or sets the input box's style
• InputBoxText – Gets or sets the input box's text
• InputBoxWatermark – Gets or sets the input box's watermark
• InputBoxWatermarkTemplate – Gets or sets the input box's watermark template
• IsSaveButtonEnabled – Gets or sets a value indicating whether the save button is enabled
• LabelStyle – Gets or sets the label style
• MatchingTermAlternateItemsMemberPath – Gets or sets the matching term alternate items member path
• MatchingTermFlyOutContentTemplate – Gets or sets the matching term flyout content template
• MatchingTermItemsControlEncodedItemTemplate – Gets or sets the matching term items control item template
• MatchingTermItemsControlItemContainerStyle – Gets or sets the matching term items control item container style property
• MatchingTermItemsControlItemTemplate – Gets or sets the matching term items control item template
• MatchingTermSelectedItemMemberPath – Gets or sets the selected item member path for the matching term items
• MatchingTermSelectedItemTextMemberPath – Gets or sets the selected item text member path for the matching term items
• SubsetPickerDataTemplate – Gets or sets the subset picker's (Search filter) data template
• SubsetPickerItemsSource – Gets or sets the subset picker's (Search filter's) items source
• SubsetPickerLabelText – Gets or sets the subset picker's (Search filter's) label text
• SubsetPickerSelectedIndex – Gets or sets the subset picker's (Search filter's) selected index
• SubsetPickerSelectedItem – Gets or sets the subset picker's (Search filter's) selected item

• Clear – Clears the fields in the control
• FocusAdditionalTextBox – Gives focus to the additional text box
• FocusInputBox – Gives focus to the input box

• AdditionalTextBoxEnterPressed – Occurs when the enter key is pressed in the additional text box
• AdditionalTextBoxTextChanged – Occurs when the additional text box's text is changed
• Cleared – Occurs when cleared
• FilterSelectedIndexChanged – Occurs when the filter selected index is changed
• InputBoxEnterPressed – Occurs when the enter key is pressed in the input box's text field
• InputBoxSearchButtonClicked – Occurs when the input box's search button is clicked
• InputBoxSelectionChanged – Occurs when the input box's selection is changed
• InputBoxTextChanged – Occurs when the input box's text is changed
• Saved – Occurs when saved

While reviewing the programmability of the Single Concept Matching control, an understanding of the core object implementation is required. The Single Concept Matching control is implemented by the class SingleConceptMatching. The SingleConceptMatching class is a composite control and inherits from the base class control.

To consume the control within a Silverlight application, a reference to the SingleConceptMatching control needs to be created:

<mscui:SingleConceptMatching x:Name="MySingleConceptMatchingControl"> 
                             </mscui:SingleConceptMatching>

The namespace element that needs to be added within the XAML is:

xmlns:mscui="clr-namespace:Microsoft.Cui.Controls;assembly=Microsoft.Cui.Controls"

The Single Concept Matching control contains a ComboBox control, called SubsetPicker, as one of its constituent controls. The purpose of this SubsetPicker is to allow the clinician to select a SNOMED CT® subset, or a collection of SNOMED CT® subsets and thereby change the scope of search.

The properties SubsetPickerItemsSource and SubsetPickerDataTemplate should be used to specify the data source of subsets, and the XAML template used for rendering the SubsetPicker respectively.

An example of a data template is shown here. This snippet assumes that the data source of subsets is a collection of custom objects, and that the custom class has a public property called Description.

<DataTemplate x:Key="SubsetPickerItemTemplate">
              <Border>
                  <TextBlock Text="{Binding Path=Description}" FontWeight="Normal" />
              </Border>
</DataTemplate>

The Single Concept Matching control publishes several events which can be subscribed to through the container application.

The events InputBoxSearchButtonClicked, InputBoxEnterPressed and InputBoxTextChanged are triggered when a clinician explicitly clicks on the Search button, presses the Enter key or presses a key in the input text box respectively.

The control implements properties InputBoxItemTemplate and InputBoxFlyOutTemplate which should be used for configuring the presentation of the results list and the flyout respectively.

The control implements a property InputBoxItemsSource which should be initialized with a collection of custom objects, each of which represents a clinical concept.

The XAML snippets below assume that the custom class has properties SnomedID, Description and SnomedDescriptionID.

An example of a DataTemplate for configuring the display of items in the results drop down list:

<DataTemplate x:Key="InputBoxItemTemplate">
              <Border>
                  <mscui:IndentedLabel 
                         MaxLines="2"  Text="{Binding Description}" 
                         VerticalAlignment="Top" FontWeight="Normal" />
              </Border>
</DataTemplate>

An example of a DataTemplate for configuring the display of the flyout which pops up when the mouse cursor hovers over an item in the results:

<DataTemplate x:Key="FlyoutTemplate">
              <StackPanel Orientation="Vertical">
                  <StackPanel Orientation="Horizontal">
                      <TextBlock Text="SNOMED Description:" FontWeight="Normal" />
                      <TextBlock Text="{Binding Description}" FontWeight="Bold" />
                  </StackPanel >
                  <StackPanel Orientation="Horizontal">
                      <TextBlock Text="SNOMED Id:" FontWeight="Normal" />
                      <TextBlock Text="{Binding SnomedID}" FontWeight="Bold" />
                  </StackPanel>
              </StackPanel>
</DataTemplate>

The Single Concept Matching control contains a multi-line text box control, called AdditionalTextBox, as one of its constituent controls. The purpose of this control is to let the clinician type free text.

The control fires the events AdditionalTextBoxEnterPressed and AdditionalTextBoxTextChanged when the clinician presses the Enter key and when any text update occurs within the additional qualifier text field respectively. These events must be handled and the additional text parsed to determining clinically encodable terms within the text.

If clinical terms are present in the text, the property AdditionalTextBoxMatchingTermItemsSource should be initialized with a collection of custom objects. Each of these objects represents a clinical concept and contains information regarding the position of these terms within the AdditionalTextBox's text.

The following snippets assume that a custom class representing a matched term has the properties StartIndex, Length and IsSelected.

The properties StartIndex and Length denote the zero based position of the first character of the matched term and the number of the characters in the matched term respectively.

The application logic for parsing the additional text is responsible for setting these properties so that the Single Concept Matching control can render the matched words.

The property MatchingTermAlternateItemsMemberPath has been initialized to the member name of the custom class which represents the SNOMED CT® preferred name of the concept.

The property MatchingTermAlternateItemsMemberPath has been initialized to the member name of the custom class which returns a collection of all concepts that are possible choices for replacing the matched term.

<mscui:SingleConceptMatching  
       ...  
       AdditionalTextBoxMatchingTermStartIndexMemberPath="StartIndex"
       AdditionalTextBoxMatchingTermIsSelectedMemberPath="IsSelected"
       AdditionalTextBoxMatchingTermLengthMemberPath="Length"
       ...
       MatchingTermSelectedItemMemberPath="SelectedItem"
       MatchingTermSelectedItemTextMemberPath="PreferredTerm"
       MatchingTermAlternateItemsMemberPath="AlternateItems"
       ...
       MatchingTermItemsControlItemTemplate="{StaticResource MatchingTermItemTemplate}"
       MatchingTermItemsControlEncodedItemTemplate="{StaticResource MatchingTermEncodedItemTemplate}"
       ...>
</mscui:SingleConceptMatching>

An example of a DataTemplate for configuring the display of the alternate concepts within the check box:

<DataTemplate x:Key="MatchingTermItemTemplate">
              <Border>
                  <mscui:IndentedLabel
                         MaxLines="2" IndentCharacterCount="2"
                         Text="{Binding PreferredTerm}" />
              </Border>
</DataTemplate>

An example of a DataTemplate for configuring the display of the matched word within the check box:

<DataTemplate x:Key="MatchingTermEncodedItemTemplate">
              <Border>
                  <mscui:IndentedLabel
                         MaxLines="2" IndentCharacterCount="2"
                         Margin="2" Text="{Binding PreferredTerm}" /> 
              </Border>
</DataTemplate>