Find an Entity

A highly configurable Angular component for generating a UI for lists of content.

Living example: ngx-find-an-entity

Primary features:

• A robust list view search/filtering experience with very little effort
• Full text keyword searching
• Ability to configure custom filters for fields using a control you specifcy[1]
• List view automatically generated based on your config
• A guided search mode that allows the user to choose one filter option at a time before seeing results[2]
• Filters can be used as query params to enhance the user's experience. This also allows linking of specific search results[3]
• Uses ngx-infinite-scroll to enhance performance[4]

[1] The following filter controls are currently implemented:

• Text (A field specific version of the keyword search)
• Select (Great for a list of options)
• Radio (Similar functionality as select, but with different styling)
• Checkbox (Good for bool values)
• Combo Box (A custom select field that allows the user to limit options with text entry)

[2] To enable the guided search mode pass true as the value for the optional "guidedSearch" input as shown below:

<lib-find-an-entity [properties]="properties" [searchableEntities]="resultsInput" [guidedSearch]="true"></lib-find-an-entity>

[3] To enable the usage of query params pass true as the value for the optional "useQueryParams" input as show below:

<lib-find-an-entity [properties]="properties" [searchableEntities]="resultsInput" [useQueryParams]="true"></lib-find-an-entity>

[4] The number of results to show before scrolling can be customized by using the "resultLimit" input.

Usage

1. After installing this module, add it to the imports array of the Angular module you intend to use it in, similar to the below:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { FindAnEntityModule } from 'ngx-find-an-entity'; // <- Add this

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    FindAnEntityModule // <- Add this
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

2. Retrieve your data as normal. For the best results, this data should be well structured json. The below is an example used in the next step:

export const resultsInput = [
  {
    name: 'Bob',
    age: 35,
    hasChildren: true,
    gender: 'male',
    favoriteColor: 'red',
    url: 'https://www.google.com',
    profilePhoto: 'https://images.vexels.com/media/users/3/140754/isolated/preview/18b7f2915116bea1ba6ce812505813b6-male-profile-avatar-8-by-vexels.png'
  }
];

3. Create an array of IProperty that describes your data. The below example describes the data seen above so that it can be consumed by find-an-entity. Learn more about IProperty members through their JSDoc comments.

import { IProperty, ControlType } from 'ngx-find-an-entity';

export const resultsInputProperties: Array<IProperty> = [
  {
    propertyName: 'name',
    label: 'Name',
    controlType: ControlType.Text,
    currentValue: '',
    tag: 'h2'
  },
  {
    propertyName: 'favoriteColor',
    label: 'Favorite Color',
    controlType: ControlType.Select,
    currentValue: '',
    tag: 'p'
  },
  {
    propertyName: 'age',
    label: 'Age',
    controlType: ControlType.Select,
    currentValue: '',
    tag: 'p'
  },
  {
    propertyName: 'gender',
    label: 'Gender',
    controlType: ControlType.Radio,
    currentValue: '',
    tag: 'div'
  },
  {
    propertyName: 'hasChildren',
    label: 'Has children',
    controlType: ControlType.Checkbox,
    currentValue: false,
    tag: 'div'
  },
  {
    propertyName: 'profilePhoto',
    label: 'Profile Photo',
    controlType: ControlType.None,
    currentValue: '',
    tag: 'img'
  },
  {
    propertyName: 'url',
    label: 'Homepage',
    controlType: ControlType.None,
    currentValue: '',
    tag: 'a',
    hide: true
  }
];

4. Add the find-an-entity component to whatever template you desire like you would any other custom component. Be sure to pass in your data and the array of IProperty you just made as inputs. Here's an example:

<lib-find-an-entity [properties]="properties" [searchableEntities]="resultsInput"></lib-find-an-entity>

5. Style the results to your liking. The default styles are pretty basic, and you'll likely want to spruce them up a bit. Keep view encapsulation in mind when attempting to override styles, as it is not disabled for the find-an-entity components. In other words, put your style overrides somewhere that bypasses view encapsulation, such as the root styles.css file if you're working with an Angular CLI project.
   *Alternatively, you can disable view-encapsulation on the containing component and style find-and-entity from there.