bugsplat-git/ngb-filterable-dropdown

⚡️🥾🔌 Powerful ng-bootstrap dropdown control for complicated filtering.

BugSplat

Crash and error reporting built for busy developers.

👋 Introduction

BugSplat's @bugsplat/ngb-filterable-dropdown package provides a powerful dropdown control for complicated filtering. Take a peek our example that demonstrates how to filter and select various items in a collection.

🏗 Installation

Install @bugsplat/ngb-filterable-dropdown and the associated peer dependencies @ng-bootstrap/ng-bootstrap and Bootstrap:

npm i @bugsplat/ngb-filterable-dropdown @ng-boostrap/ng-bootstrap bootstrap

🏃 Usage

Add NgbFilterableDropdownModule to your NgModule imports for each module where you plan to use the filterable dropdown:

import { NgbFilterableDropdownModule } from '@bugsplat/ngb-filterable-dropdown'

@NgModule({
  ...
  imports: [
    NgbFilterableDropdownModule
  ],
  ...
})

Add ngb-filterable-dropdown to your component's template:

<ngb-filterable-dropdown
  [allowCreateItem]="allowCreateItem"
  [autoClose]="autoClose"
  [items]="items"
  [disabled]="disabled"
  [placeholder]="placeholder"
  [searchInputPlaceholder]="searchInputPlaceholder"
  [selection]="selection"
  [selectionMode]="selectionMode"
  (itemCreated)="onItemCreated($event)"
  (openChanged)="onOpenChanged($event)"
  (selectionChanged)="onSelectionChanged($event)"
>
</ngb-filterable-dropdown>

🧩 API

Customize your dropdown by leveraging the inputs and outputs of @bugsplat/ngb-filterable-dropdown as described below.

Selection

The component takes two main inputs, a list of strings that are selectable and a sub-list of strings that are already selected.

items: Array<string> = ['Beetle', 'Ant', 'Moth', 'Fire Ant', 'Dung Beetle', 'Grass Ant'];
selection: Array<string> = ['Moth'];

Selection Modes

You can also specify whether or not to allow multiple items to be selected. By default, the component allows one item to be selected.

selectionMode: NgbFilterableDropdownSelectionMode =
  NgbFilterableDropdownSelectionMode.SingleSelect;

Create New Items

You can specify whether or not to allow new items to be created. By default, the component does not allow new items to be created.

allowCreateItem: boolean = false;

Opening and Closing

The open/close behavior of the dialog can be changed by setting autoClose to true or false. Alternatively you can specify whether to close on an outside or inside click.

autoClose: boolean | 'inside' | 'outside' = false;

Disabling

Dropdowns can be disabled at any time by setting disabled to true.

disabled: boolean = false;

Loading

You can also display a loading placeholder by setting loading to true.

loading: boolean = false;

Placeholders

If you'd like to specify the placeholder in the search input you can set the value of searchInputPlaceholder to a string of your choosing.

placeholder: string = 'No Items Selected';
searchInputPlaceholder: string = 'Search';

Outputs

The component provides the selected data back to the parent through the selectionChanged event.

onSelectionChanged(event: SelectionChangedEvent) {
  const selection = event.selection;
}

When an item is created the component outputs an event with the properties created, items, and selection.

onItemCreated(event: ItemCreatedEvent) {
  const created = event.created;
  const selection = event.selection;
  const items = event.items;
}

The component also provides an event when the dropdown is opened or closed through the openChanged event.

onOpenChanged(event: OpenChangedEvent) {
  const open = event.open;
}

🐛 About

@bugsplat/ngb-filterable-dropdown is an open source library developed by BugSplat! BugSplat is a crash and error reporting tool used by developers to find, fix, and track errors in their applications.

If you're interested in error reporting, check out our Angular integration.

With ❤️
BugSplat

ngb-filterable-dropdown's Issues

Enter should create item when create item is enabled

State should be DESELECT if component is initialized in Multi-Select mode with items selected

Background should not disappear when dropdown runs out of space

Fix icon styles

Ok I think I have a good fix for this - see the end result below

Screen Shot 2020-10-05 at 5 01 49 PM

Fix:
Change left and right padding to match that of the other dropdown items with

padding-left: .5rem!important;
padding-right: .5rem!important;

Then put some padding the right side of the svg

icon-all {
padding-right: 7px;
}

And locally add an element style to the svg to give it 4px of bottom margin

**

autoClose type should match ng-bootstrap

got an error in our web app today when we enabled strictTemplates. the correct type should be boolean | 'outside' | 'inside'; as seen here

Make multi-select more discoverable

Copied from https://github.com/BugSplat-Git/angular-web-app/issues/1181

You can select multiple items with the enter key but this isn't very discoverable. Let's add a Select Multiple button!

Dropdown missing downward arrow

Prior to #32

After #32

Add e2e tests

• Inside/outside clicks
• Multi-select

Add semantic-release

Let's add standard-version and try out conventional commits

Fix linting rules

Allow items to be string or string array

Found after enabling strictTemplate checking in our web app

Add support for creating a new item if one does not exist

If the user types something that doesn't exist in the filter we should emit some sort of event that requests its creation by the consumer. This would support the enter key and have a button in the list that would both function the same. This functionality should probably be turned on or off by an input. There might be some funny cases we need to handle to make sure it plays nice with allowMultiSelect for instance.

Disabled functionality is broken

Broken by #32

Dropdown should not close on inside click when autoClose is 'outside'

Should Not Submit Outer Forms

Remove dead onClick handler

Remove this, we got rid of it :)

Originally posted by @bobbyg603 in #60 (comment)

Loading functionality broken

Loading was broken by #32

import ngb-filterable-dropdown instead of ng-filterable-dropdown

In README.md

Add CI/CD

https://medium.com/better-programming/ci-cd-for-angular-developers-be9a1485d22b

Update docs for allowCreateItem

Cleanup subscription when component is destroyed

Add Support for Shift+Click

Copied from https://github.com/BugSplat-Git/bugsplat-web-app/issues/1829

Allow for ranges of items to be selectable by adding in a Shift+Click range selection option

Migrate to ESLint

TSLint's support is discontinued and we're deprecating its support in Angular CLI.
To opt-in using the community driven ESLint builder, see: https://github.com/angular-eslint/angular-eslint#migrating-an-angular-cli-project-from-codelyzer-and-tslint.

Remove Protractor

Protractor is toast, let's remove it and all the e2e stuff.

Should display items after opening dropdown

1. Add ngb-filterable-dropdown to a component and provide it with a list of items
2. Click button to show dropdown with items and search input
3. Notice dropdown shows 'No items to display' however there are in fact several items and they are revealed upon searching

Switch to templates for providing buttons

I tried to use the official FontAwesome icons package for Angular today but hit a blocker where I couldn't use the component inside of ngb-custom-filterable-dropdown. I can only assume this is because of transclusion because doing the same thing in ngx-datatable via ng-template has no such problems.

Should hide default-content if ng-content is provided

Update Peer Dependency to @ng-bootstrap/ng-bootstrap 13

Updated Docs

We made some changes for 6.0.0 and need to update the documentation to reflect this.

Search input should be autofocused

1. Click the dropdown toggle to review the list of items and search input
2. Notice that the search input is not focused

Search input should be focused so user can start typing immediately

Update README

Update README to match new repo conventions.