Controls – SearchAndPrescribe

The Search and Prescribe Control allows designers and developers to implement a set of prescribing functionality and is available in Silverlight and WPF.

You can bind any data to the control, but this configuration of the control represents data to support a limited set of specific scenarios. To integrate the control into your application, you will need to provide relevant source data and prescribing rules.

Although the sample application conforms to all mandatory elements of the published Search and Prescribe design guidance, the following point is not supported in the sample control:

• Regular prescriptions
  • Prescribe clarithromycin using the quick list and a template prescription and with more than one possible route
  • Prescribe salbutamol metred dose inhaler with a starting condition
  • Prescribe salbutamol nebuliser PRN with a starting condition
  • Prescribe fluticasone + salmeterol – by searching for salmeterol

• Continue current medication
  • Search for PREDSOL and prescribe a generic equivalent
  • Prescribe diltiazem and select brand name (DILZEM)

• Less common prescriptions
  • Prescribe chloramphenicol by cutaneous route

The following steps show how to use the Search and Prescribe control to create a very simple Silverlight application. The steps use a simplified data model that would not be appropriate for a fully functioning search and prescribe system.

Note: The steps assume additional logic to populate valid attributes for a selected drug (for example routes, forms, strengths etc.)

Create a Silverlight application and add references

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

Add some classes to provide basic data

1. Add a class named Drug.cs
   The following code describes a basic drug object, with members that can be populated from a drug data source. This object assumes that the possible attributes for a drug (for example routes, forms, strengths etc.) are known.

       public class Drug
       {
           // Basic drug information.
           public string Name { get; set; }
   
           // Attributes available for this drug.
           public string[] Routes { get; set; }
           public string[] Forms { get; set; }
           public string[] Strengths { get; set; }
           public string[] Dosages { get; set; }
           public string[] Frequencies { get; set; }
           public string[] StartingConditions { get; set; }
           public string[] AdministrationTimes { get; set; }
           public string[] Durations { get; set; }
       }
   

2. Add a class named TemplatePrescription.cs
   The following code describes a template prescription object. The class provides members that allow the selection of a strength, dose and frequency to be made with a single selection.

       public class TemplatePrescription
       {
           public string Dose { get; set; }
           public string Strength { get; set; }
           public string Frequency { get; set; }
           public bool IsAsRequired { get; set; }
       }
   

3. Add a class named Prescription.cs
   The following code describes a basic prescription object. The class contains members that store the selections (for example drug, route, form, strength etc.) as well as option members that provide a list of the valid options for each attribute, as well as the possible other options for each attribute. This example assumes that the logic is available to populate the lists of valid attributes and other attributes.

       public class Prescription
       {
           // Prescription selection members.
           public Drug Drug { get; set; }
           public string Route { get; set; }
           public bool IsFormMandatory { get; set; }
           public string Form { get; set; }
           public bool IsStrengthMandatory { get; set; }
           public TemplatePrescription TemplatePrescription { get; set; }
           public string Strength { get; set; }
           public string Dose { get; set; }
           public string Frequency { get; set; }
           public bool IsAsRequired { get; set; }
           public string StartingCondition { get; set; }
           public string AdministrationTimes { get; set; }
           public DateTime StartDate { get; set; }
           public DateTime FirstDoseTime { get; set; }
           public string Duration { get; set; }
   
           // Prescription option members.
           public string[] ValidRoutes { get; set; }
           public string[] OtherRoutes { get; set; }
           public string[] ValidForms { get; set; }
           public string[] OtherForms { get; set; }
           public string[] ValidTemplatePrescriptions { get; set; }
           public string[] ValidStrengths { get; set; }
           public string[] OtherStrengths { get; set; }
           public string[] ValidDosages { get; set; }
           public string[] OtherDosages { get; set; }
           public string[] ValidFrequencies { get; set; }
           public string[] OtherFrequencies { get; set; }
           public string[] ValidStartingConditions { get; set; }
           public string[] ValidAdministrationTimes { get; set; }
           public DateTime[] ValidFirstDoseTimes { get; set; }
           public string[] ValidDurations { get; set; }
       }

Add the Search and Prescribe Control to the page

1. Add an XML namespace to the top of the XAML page

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

2. Add an instance of the control to the page, set some initial properties and add some event handlers

       <Cui_Controls:SearchAndPrescribeControl 
               x:Name="SearchAndPrescribeControl"
               IsDrugSearchButtonEnabled="True"
               VerticalAlignment="Top"
               CascadingListMaximumHeight="400"
               DrugSearchButtonClick="SearchAndPrescribeControl_DrugSearchButtonClick"
               Preview="SearchAndPrescribeControl_Preview"
               Authorize="SearchAndPrescribeControl_Authorize"
               Close="SearchAndPrescribeControl_Close"
               />
   

3. In the page's constructor method, give the Search and Prescribe Control a data context of a new prescription

           public MainPage()
           {
               InitializeComponent();
               this.SearchAndPrescribeControl.DataContext = new Prescription();
           }
   

Enable searching for a drug

1. Add the following code to the page hosting the search and prescribe control, for example

   	private void SearchAndPrescribeControl_DrugSearchButtonClick(object sender, RoutedEventArgs e)
   	{
   	    this.SearchAndPrescribeControl.PrimaryDrugsItemsSource = 
   	        this.GetMatches(this.SearchAndPrescribeControl.DrugSearchText);
   	
   	    this.SearchAndPrescribeControl.IsShowingAllDrugResults = false;
   	    this.SearchAndPrescribeControl.RefreshDrugsList();
   	}
   	
   	private Drug[] GetMatches(string text)
   	{
   	    // Some logic to search for drugs.
   	}
   	

2. Add a DataTemplate for displaying the drug search result

       <DataTemplate x:Key="DrugDataTemplate">
           <TextBlock Text="{Binding Name}"
                      FontWeight="Bold" />
       </DataTemplate>
       
       <Cui_Controls:SearchAndPrescribeControl 
               x:Name="SearchAndPrescribeControl"
               ...
               DrugItemTemplate="{StaticResource DrugDataTemplate}"
               />
   

Bind the members of the Search and Prescribe Control

1. Add the following XAML properties to the Search and Prescribe Control to bind the members of the Precription class to the control. This will allow the control to read the possible options for selection and modify the selections in the Prescription.

       <Cui_Controls:SearchAndPrescribeControl 
           x:Name="SearchAndPrescribeControl"
           ...
           SelectedDrug="{Binding Mode=TwoWay, Path=Drug}"
           SelectedRoute="{Binding Mode=TwoWay, Path=Route}"
           SelectedForm="{Binding Mode=TwoWay, Path=Form}"
           SelectedTemplatePrescription="{Binding Mode=TwoWay, Path=TemplatePrescription}"
           SelectedStrength="{Binding Mode=TwoWay, Path=Strength}"
           SelectedDose="{Binding Mode=TwoWay, Path=Dose}"
           SelectedFrequency="{Binding Mode=TwoWay, Path=Frequency}"
           SelectedAdministrationTimes="{Binding Mode=TwoWay, Path=AdministrationTimes}"
           SelectedStartDate="{Binding Mode=TwoWay, Path=StartDate}"
           SelectedFirstDoseTime="{Binding Mode=TwoWay, Path=FirstDoseTime}"
           SelectedDuration="{Binding Mode=TwoWay, Path=Duration}"
           
           ValidRoutesItemsSource="{Binding Path=ValidRoutes}"
           OtherRoutesItemsSource="{Binding Path=OtherRoutes}"
           ValidFormsItemsSource="{Binding Path=ValidForms}"
           OtherFormsItemsSource="{Binding Path=OtherForms}"
           ValidStrengthsItemsSource="{Binding Path=ValidStrengths}"
           OtherStrengthsItemsSource="{Binding Path=OtherStrengths}"
           ConciseDosagesItemsSource="{Binding Path=ValidDosages}"
           DetailedDosagesItemsSource="{Binding Path=OtherDosages}"
           ConciseFrequenciesItemsSource="{Binding Path=ValidFrequencies}"
           DetailedFrequenciesItemsSource="{Binding Path=OtherFrequencies}"
           ValidAdministrationTimesItemsSource="{Binding Path=ValidAdministrationTimes}"
           ValidFirstDoseTimesItemsSource="{Binding Path=ValidFirstDoseTimes}"
           ValidDurationsItemsSource="{Binding Path=ValidDurations}"
           />
   

Finally, adding handlers for the control's remaining events will allow the application to handle Previewing, Closing and Authorising of the prescription.

The Search and Prescribe Control provides the user interface elements for searching for a drug, and completing a prescription. However, the logic used to provide valid attributes such as routes, forms, strengths, dosages etc. is provided by a data model.

The information below explains how the sample data and data model have been structured.

Note: The sample data and data model are not representative of those that should be used in a production search and prescribe system. They are used here to demonstrate the control's functionality.

XML Data

The data for the sample application is stored in an XML file. The main body of the XML data is made up of the drug data used in the sample scenarios. Below is an example block of XML that contains some of the data for paracetamol.

    <Drug Name="paracetamol" CommonlyPrescribed="True">
      <Routes>
        <Route Value="oral" />
        <Route Value="rectal" />
        ...
      </Routes>
      <TemplatePrescriptions>
        <TemplatePrescription Route="oral" Dose="500 mg" 
                              Frequency="four times a day" 
                              AdministrationTimes="08:00;12:00;18:00;22:00" 
                              Duration="Unlimited" />
        <TemplatePrescription Route="rectal" Dose="500 mg" 
                              Frequency="four times a day" 
                              AdministrationTimes="08:00;12:00;18:00;22:00" 
                              Duration="Unlimited" />
        ...
      </TemplatePrescriptions>
      <Forms>
        <Form Value="tablet" ValidRoutes="oral" 
              ValidStrengths="" />
        <Form Value="oral suspension" ValidRoutes="oral" 
              ValidStrengths="250 mg in 5 mL" />
        <Form Value="suppository" ValidRoutes="rectal" 
              ValidStrengths="" />
        ...
      </Forms>
      <Strengths>
        <Strength Value="250 mg in 5 mL" ValidRoutes="oral" 
                  ValidForms="oral suspension"  />
        <Strength Value="500 mg in 100 mL" ValidRoutes="intravenous" 
                  ValidForms="solution for injection" />
      </Strengths>
      <Dosages>
        <Dose Value="500 mg" ValidFrequencies="four times a day" />
        ...
      </Dosages>
      <Frequencies>
        <Frequency Value="four times a day" 
                   AdministrationTimes="08:00;12:00;16:00;20:00" 
                   ValidDosages="500 mg" Duration="Unlimited" />
      </Frequencies>
    </Drug>

The drug data contains name information about the drug, some of the licensed routes and some template prescriptions for the routes. The data also contains possible attributes for the drug including forms, strengths, dosages and frequencies. Each of these attributes contains a list of valid other attributes used to determine if a selection is valid.

For example, the strength data below specifies that this strength is valid when 'oral' is selected as a route and/or 'oral suspension' is selected as a form.

        <Strength Value="250 mg in 5 mL" ValidRoutes="oral" 
                  ValidForms="oral suspension"  />

The Class Structure

The XML drug data is de-serialized into a drug class, which contains all of the drug information and attributes. The diagram below shows the members of the drug class.

The template prescriptions use a template prescription class, which contains each of the drug attributes that will be set if that template prescription is selected. The template prescription class is pictured below.

The other drug attributes, for example form, strength, dose, frequency etc. have a simple object hierarchy that allows each attribute to contain a list of validation values, e.g. ValidBrands, ValidDosages etc. The validation values are used to determine which attributes are valid selections based on other selections in the prescription.

The Prescription Class

The Prescription class contains the all of the selections for the prescription, as well as the logic to determine which are the valid attributes.

The image below shows the prescription class members that store the selections for the prescription, and the properties exposed for providing lists of valid attributes.

The following code example shows how the valid dosages are determined:

    public Dose[] ValidDosages
    {
        get
        {
            if (this.Drug != null &&
                this.Route != null && 
                (!this.Route.MandatoryForm || this.Form != null) && 
                this.Drug.Dosages != null)
            {
                DrugElement[] sourceAttributes = this.GetValidDrugElements(this.Drug.Dosages);

                // Convert sourceAttributes to a Dose[]
                // and return...
            }

            return null;
        }
    }
    
    private DrugElement[] GetValidDrugElements(DrugElement[] sourceAttributes)
    {
        DrugElement[] attributes = sourceAttributes;
        if (this.Route != null)
        {
            attributes = (from attribute in attributes
                          where attribute.ValidRoutes == null || 
                          attribute.ValidRoutes.Contains(this.Route.DisplayValue)
                          select attribute).ToArray();
        }

        if (this.Form != null && !this.Form.IsCustomValue)
        {
            attributes = (from attribute in attributes
                          where attribute.ValidForms == null || 
                          attribute.ValidForms.Contains(this.Form.Value.Trim())
                          select attribute).ToArray();
        }

        // Continue for the other selected attributes.

        return attributes;
    }

The GetValidDrugElements(...) method uses LINQ to filter down the source attributes (in this case, all of the dosages for the selected drug) based on the selections for the other attributes. The code above shows that if a route is selected, and the dose doesn't contain the route in the ValidRoutes, it is not returned as a valid attribute. This is then repeated for form, strength, frequency etc.

The Getting Started section above shows how to implement a simple data model with the control.

While reviewing the programmability of the Search and Prescribe control, an understanding of the core object implementation is required. The Search and Prescribe control is implemented by the class SearchAndPrescribeControl. The SearchAndPrescribeControl class is a composite control and inherits from the base class SearchAndPrescribeBase, which in turn inherits from the base class Control.

To consume the control within a Silverlight application, a reference to the Search and Prescribe control needs to be created:

    <Cui_Controls:SearchAndPrescribeControl 
            x:Name="SearchAndPrescribeControl"
            />

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

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

SearchAndPrescribeBase Members

SearchAndPrescribe Members

SearchAndPrescribe Methods

SearchAndPrescribe Events