Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Next major version of Blazored Typeahead #46

Merged
merged 8 commits into from
Oct 22, 2019
Merged

Next major version of Blazored Typeahead #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
dc5a214
Removed seperate forms typeahead and added partial implementation of …
chrissainty Sep 18, 2019
06976d1
Added up/down arrow navigation
chrissainty Sep 18, 2019
b4a6e97
Sorted mixed keyup keydown events
chrissainty Oct 4, 2019
b7657a8
WIP: more updates
Oct 18, 2019
c95c3db
Added ability to disable the typeahead
chrissainty Oct 19, 2019
31f4566
Final testing and fixes
chrissainty Oct 19, 2019
c445183
Merge branch 'master' into vnext
chrissainty Oct 19, 2019
aba9c87
Adds multi-select and various styling fixes
Oct 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 29 additions & 101 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ You can install from NuGet using the following command:
Or via the Visual Studio package manger.

### Setup
If will need to include the following CSS and JS files in your `index.html` (Blazor WebAssembly) or `_Host.cshtml` (Blazor Server).
Blazor Server applications will need to include the following CSS and JS files in their `_Host.cshtml`.

In the `head` tag add the following CSS.

Expand All @@ -30,109 +30,57 @@ Then add the JS script at the bottom of the page using the following script tag.
<script src="_content/Blazored.Typeahead/blazored-typeahead.js"></script>
```

## Usage
The component comes in two flavors, standalone and forms integrated.

### Forms Integrated
This version of the component is integrated with the forms and authentication system Blazor provides out the of box.
**NOTE** If you're using Blazor WebAssembly then these files will get added to your `index.html` automagically.

I would suggest adding the following using statement to your main `_Imports.razor` to make referencing the component a bit easier.
I would also suggest adding the following using statement to your main `_Imports.razor` to make referencing the component a bit easier.

```cs
@using Blazored.Typeahead.Forms
```

### Local Data Example
```cs
<EditForm Model="@MyFormModel" OnValidSubmit="@HandlValidSubmit">
<BlazoredTypeaheadInput SearchMethod="@SearchFilms"
@bind-Value="@MyFormModel.SelectedFilm">
<SelectedTemplate>
@context.Title
</SelectedTemplate>
<ResultTemplate>
@context.Title (@context.Year)
</ResultTemplate>
</BlazoredTypeaheadInput>
<ValidationMessage For="@(() => MyFormModel.SelectedFilm)" />
</EditForm>

@code {
## Usage
The component can be used standalone or as part of a form. When used in a form the control fully integrates with Blazors forms and authentication system.

[Parameter] protected IEnumerable<Film> Films { get; set; }
Below is a list of all the options available on the Typeahead.

private async Task<IEnumerable<Film>> SearchFilms(string searchText)
{
return await Task.FromResult(Films.Where(x => x.Title.ToLower().Contains(searchText.ToLower())).ToList());
}
**Templates**

}
```
In the example above, the component is setup with the minimum requirements. You must provide a method which has the following signature `Task<IEnumerable<T> MethodName(string searchText)`, to the `SearchMethod` parameter. The control will call this method with the current search text everytime the debounce timer expires (default: 300ms). You must also set a value for the `Value` parameter. This will be populated with the item selected from the search results. As this version of the control is integrated with Blazors built-in forms and validation, it must be wrapped in a `EditForm` component.
- `ResultTemplate` (Required) - Allows the user to define a template for a result in the results list
- `SelectedTemplate` (Required) - Allows the user to define a template for a selected item
- `NotFoundTemplate` - Allows the user to define a template when no items are found
- `FooterTemplate` - Allows the user to define a template which is displayed at the end of the results list

The component requires two templates to be provided...
**Parameters**

- `SelectedTemplate`
- `ResultTemplates`
- `MinimumLength` (Optional - Default: 1) - Minimum number of characters before starting a search
- `Debounce` (Optional - Default: 300) - Time to wait after last keypress before starting a search
- `MaximumSuggestions` (Optional - Default: 10) - Controls the amount of suggestions which are shown
- `Disabled` (Optional - Default: false) - Marks the control as disabled and stops any interaction

The `SelectedTemplate` is used to display the selected item and the `ResultTemplate` is used to display each result in the search list.
The control also requires a `SearchMethod` to be provided with the following signature `Task<IEnumerable<TItem>>(string searchText)`. The control will invoke this method
passing the text the user has typed into the control. You can then query your data source and return the result as an `IEnumerable` for the control to render.

If you wish to bind the result of the selection in the control to a different type than the type used in the search this is also possible. For example, if you passed in a list
of `Person` but when a `Person` was selected you wanted the control to bind to an `int` value which might be the `Id` of the selected `Person`, you can achieve this by providing
a `ConvertMethod` The convert method will be invoked by the control when a selection is made and will be passed the type selected. The method will need to handle the conversion
and return the new type.

### Remote Data Example

### Local Data Example
```cs
@inject HttpClient httpClient

<EditForm Model="@MyFormModel" OnValidSubmit="@HandlValidSubmit">
<BlazoredTypeahead SearchMethod="@SearchFilms"
@bind-Value="@SelectedFilm"
Debounce="500">
<EditForm Model="MyFormModel" OnValidSubmit="HandlValidSubmit">
<BlazoredTypeaheadInput SearchMethod="SearchFilms"
@bind-Value="MyFormModel.SelectedFilm">
<SelectedTemplate>
@context.Title
</SelectedTemplate>
<ResultTemplate>
@context.Title (@context.Year)
</ResultTemplate>
<NotFoundTemplate>
Sorry, there weren't any search results.
</NotFoundTemplate>
</BlazoredTypeahead>
</BlazoredTypeaheadInput>
<ValidationMessage For="@(() => MyFormModel.SelectedFilm)" />
</EditForm>

@code {

[Parameter] protected IEnumerable<Film> Films { get; set; }

private async Task<IEnumerable<Film>> SearchFilms(string searchText)
{
var response = await httpClient.GetJsonAsync<IEnumerable<Film>>($"https://allfilms.com/api/films/?title={searchText}");
return response;
}

}
```
Because you provide the search method to the component, making a remote call is really straight-forward. In this example, the `Debounce` parameter has been upped to 500ms and the `NotFoundTemplate` has been specified.

### Standalone
I would suggest adding the following using statement to your main `_Imports.razor` to make referencing the component a bit easier.

```cs
@using Blazored.Typeahead
```

### Local Data Example
```cs
<BlazoredTypeahead SearchMethod="@SearchFilms"
@bind-Value="@SelectedFilm">
<SelectedTemplate>
@context.Title
</SelectedTemplate>
<ResultTemplate>
@context.Title (@context.Year)
</ResultTemplate>
</BlazoredTypeahead>

@code {

[Parameter] protected IEnumerable<Film> Films { get; set; }
Expand All @@ -144,7 +92,7 @@ I would suggest adding the following using statement to your main `_Imports.razo

}
```
In the example above, the component is setup with the minimum requirements. You must provide a method which has the following signature `Task<IEnumerable<T> MethodName(string searchText)`, to the `SearchMethod` parameter. The control will call this method with the current search text everytime the debounce timer expires (default: 300ms). You must also set a value for the `Value` parameter. This will be populated with the item selected from the search results.
In the example above, the component is setup with the minimum requirements. You must provide a method which has the following signature `Task<IEnumerable<T> MethodName(string searchText)`, to the `SearchMethod` parameter. The control will call this method with the current search text everytime the debounce timer expires (default: 300ms). You must also set a value for the `Value` parameter. This will be populated with the item selected from the search results. As this version of the control is integrated with Blazors built-in forms and validation, it must be wrapped in a `EditForm` component.

The component requires two templates to be provided...

Expand Down Expand Up @@ -185,24 +133,4 @@ The `SelectedTemplate` is used to display the selected item and the `ResultTempl

}
```
Because you provide the search method to the component, making a remote call is really straight-forward. In this example, the `Debounce` parameter has been upped to 500ms and the `NotFoundTemplate` has been specified.


### Full Options List
Below is a list of all the options available on the Typeahead.

**Templates**

- ResultTemplate (Required) - Allows the user to define a template for a result in the results list
- SelectedTemplate (Required) - Allows the user to define a template for a selected item
- NotFoundTemplate - Allows the user to define a template when no items are found
- FooterTemplate - Allows the user to define a template which is displayed at the end of the results list

**Parameters**

- Item (Required) - Used for binding local field to selected item on control
- Data (Required) - Method to call when performing a search
- Placeholder (Optional) - Allows user to specify a placeholder message
- MinimumLength (Optional - Default 1) - Minimum number of characters before starting a search
- Debounce (Optional - Default 300) - Time to wait after last keypress before starting a search

Because you provide the search method to the component, making a remote call is really straight-forward. In this example, the `Debounce` parameter has been upped to 500ms and the `NotFoundTemplate` has been specified.
Loading