Blazor OceanAutoComplete Component

Introduction

Most line-of-business applications have use cases for an autocomplete control of some sort. For my upcoming Moo2U application, I need an autocomplete control for address (city, state, zip) and for products. I did look around before writing this component but found my business use case didn’t match other Blazor components I looked at.

Features

  • Has a highly customizable auto-complete experience.
  • Search callback to return items.
  • Selected item changed event when an item is selected or when the user leaves the control without selecting an item.
  • Change the appearance of the search results container by creating a class ocean-blazor-auto-complete-container and setting desired values.
  • Change the appearance of the selected search result item by creating these classes ocean-blazor-selected-search-result, ocean-blazor-not-selected-
    search-result, and ocean-blazor-not-selected-search-result:hover and setting desired values.
  • Handles the arrow up and down, page up and down, escape, enter, and tab keys.
    • Arrow up and down moves the selected item 1 item up or down.
    • Page up and down move the selected item 6 items up or down.
    • Escape closes the search results lists.
    • Enter and tab keys raise the selected item changed event and close the search results lists.

Desired User Experience

User experience in line-of-business applications is critical to the success of the application as measured by user productivity and lack of frustration.

Enable the user to enter a few characters and display a list of matching records.  Users must be able to navigate the list using the keyboard and then select an item.  Optionally, the user should be able to use their mouse for record selection and browsing.

Users must be able to dismiss the search results using the keyboard.

Users must be able to select a search result item using the ENTER or TAB keys or by clicking the item with the mouse.

Setup

Install Oceanware.OceanBlazor NuGet package for the client-side and/or the server-side applications.  If using a shared component library for your pages, also install the NuGet package as well.  See NuGet packages below.

For the server-side apps, edit the _Host.cshmtl file as shown below.  The two highlight areas show the required text you need to add.

For the client-side apps, edit the wwwrooot/index.html file and include the same below highlighted edits.

Text Snippets

You can copy these text snippets and add them to your files as required.

<link href="_content/Oceanware.Ocean.Blazor/css/ocean-blazor.css" rel="stylesheet" />

<script src="_content/Oceanware.Ocean.Blazor/ocean-blazor.js"></script>

Usage

Home Address

The below image captures the razor markup for the Home Address City field.

Component Specific Properties

  • @bind-Value is the binding to the model property, in this case, the model object is Person, the property is City.
  • MinimumSearchLength is the minimum number of characters entered before the SearchCallback is invoked. The default value is 1, the above is set to 2.  The best value for this property is dependent on your application, the amount of data, the amount of data returned by the user entering 1, 2, 3, … characters.
  • TItem is the object type that will be returned in the search results.  In this case, it’s the CityStateZip class.
  • ItemStringSelector is the function that will return a string from the selected item. In this case, each time a record is selected the City property will be used to populate the OceanAutoComplete input control.
  • SearchCallback is the function that will be invoked when the minimum number of characters has been entered by the user.  This function will return an IEnumerable<T> where T is a TItem.
  • SelectedItemChanged is a function that will be invoked when the user selects an item.
  • Debounce (not shown) is the time in milliseconds between the last keypress and the invocation of the SearchCallback.  The default value is 300.

SelectedItemChanged Function

The below CitySelectedItemChanged method is invoked by the OceanAutoComplete control when an item is selected.

Note: this method can be passed null for the selectedItem argument, so be sure to check if not null and handle null use cases as required. For the Home Address City, if the user enters a value not in the search results, the application considers this to be valid.  Each application is different.  The below Work Address Zip does not allow entries no in the search results.

The method sets the related property values and sets Focus to the field after the Home Address Zip which if the Work Address, Address Line One.

See the third video for how the Interop.Focus method works.  This method is actually in the Oceanware.Ocean.Blazor assembly and it invokes the JavaScript setFocus method to set focus the control with the id of, “workAddressLineOne.”

Work Address

In this use case, we are using the WorkZip as the lookup property.  Notice the changes from the above example highlighted in green.

SelectedItemChanged Function

This function is similar to the above one for the Home Address City. When the selectedItem is not null, the corresponding properties are set and the focus is moved to the phone.

If selectedItem is null, all the properties are cleared and focus returned to the Work Zip OceanAutoComplete.  This is one example of forcing the user to select an item from the search results before proceeding.

Customizing

The below CSS is taken from the ocean-blazor.css file from the above setup edits to _Host.cshtml file.

You can use the same class names in your applications site.css file to alter the look of the OceanAutoComplete Component search results.

  • ocean-blazor-selected-search-result is used to style the selected item in the search results.  The selected item is one that has been selected by the user using the keyboard.
  • ocean-blazor-not-selected-search-result is used to style search results that are not selected.
  • ocean-blazor-not-selected-search-result:hover is used to style a search result when the mouse is over that result.  Tip:  set the same values for this class as the ocean-blazor-selected-search-result to get the same look for keyboard selected and mouse over search result items.
  • ocean-blazor-auto-complete-not-found is used to style the not found template.
  • ocean-blazor-auto-complete-container is used to style the search results container.  If you change the background, be sure to match the background-color you assign with this class ocean-blazor-not-selected-search-result so that the colors will match.
    • Note:  don’t change the overflow properties as this will break the component.  The others can be changed to suit your application requirements.

Tip: You can copy the below text into your site.css and edit as required.  This is not a requirment if the default styling is compatible with your application.

.ocean-blazor-selected-search-result {
    background-color: gainsboro;
}

.ocean-blazor-not-selected-search-result {
    background-color: white;
}

    .ocean-blazor-not-selected-search-result:hover {
        background-color: gainsboro;
    }

.ocean-blazor-auto-complete-not-found {
    padding: .5em;
    border: 1px solid;
    width: 100%;
}

.ocean-blazor-auto-complete-container {
    cursor: pointer;
    border: 1px solid;
    width: 100%;
    max-height: 300px;
    position: relative;
    overflow-x: hidden;
    overflow-y: auto;
}

References

Before beginning this component, I studied these two components to get an understanding of the business use cases and a general structure for creating my own autocomplete component.

https://chrissainty.com/getting-started-with-blazored-typeahead/

https://github.com/SamProf/MatBlazor

Source

Project Source: https://github.com/Oceanware/BlazorAutoComplete

Ocean Library: https://github.com/OceanLibrary/Ocean

NuGet Packages

Oceanware.Ocean and Oceanware.Ocean.Blazor can be installed using Visual Studio.

All Oceanware NuGet Packages can be downloaded from here:  https://www.nuget.org/packages?q=OCEANWARE

Video

Oceanware OceanAutoComplete Component Demo (video of this source project)

Oceanware OceanAutoComplete Component (video from the Oceanware Ocean Library, OceanAutoComplete component and the demo project in the Ocean Library source project.)

Share Blazor Pages and JavaScript Across Assemblies

Close

I hope you find this demo useful in your Blazor projects.

Just a grain of sand on the world’s beaches.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s